Zendesk API2 cutover operations

Run the read-only comparator in production through Infisical; a direct ECS Exec invocation does not provide the application secrets required by API2:

AWS_PROFILE=AdministratorAccess-879381255132 \
  bin/aws/ecs-shell.sh api2-prod-us \
  "bash -lc 'infisical run --projectId=\$INFISICAL_PROJECT_ID --env=\$INFISICAL_ENV -- /app/node_modules/.bin/tsx /app/rulebase-api2/scripts/check-zendesk-parity.ts 1'"

Use scripts/check-zendesk-parity.ts <sample-size> during shadow validation. The sample size is applied independently to every active, non-discarded Zendesk organization data source, so the output reports activeZendeskSources and selected records across all sources. Fresh conversations are reported as skipped; use scripts/check-zendesk-parity.ts <sample-size> --force for a read-only comparison that bypasses freshness skipping.

The comparator samples only conversations matching organization_data_source_id = ?, source_deleted_at IS NULL, and external_created_at IS NOT NULL, ordered by external_created_at DESC. This matches the existing idx_conversations_source_external_created_active index. If a source has fewer eligible conversations than requested, the comparator reports the smaller sample and does not fall back to an unindexed query.

The comparator waits for Redis before making Zendesk requests and deterministically awaits its Redis and PostgreSQL cleanup on success and failure. Field parity reads Rails conversation_field_values joined to conversation_fields, matching planned nonblank values by stable conversation_fields.external_id. Values are compared using the exact JSON representation API2 persists; missing rows and different values are reported with the field name and label for diagnostics. Extra Rails rows for fields omitted from the plan are ignored because blank Zendesk values are skipped and existing rows are preserved.

The comparator exits non-zero when any configured mismatch-rate threshold fails. The JSON output includes checks for parts, authors, status, tags, assignee, provider status, work schedule, and canonical fields, plus normalization diagnostics. Unsupported Zendesk Change events include their fieldName so unsupported provider behavior can be classified without writing data.

Enable source-owned sync for one low-volume organization first. Watch sync failure rate, retry exhaustion, Rails fallback count, Zendesk 429s, part presence/type mismatches, and canonical field mismatches before expanding. If those metrics regress, disable the Zendesk API2 source-sync flag; immediate enqueue failures and exhausted API2 jobs fall back to Rails, with the latter logged with organization, data-source, and conversation identifiers.