PROD-2542: validate content against the target model before sending it; harden batch result alignment

[5PK]

Problem

Content items missing a value for a Required field are sent to the Management API anyway, and the database rejects them (Column 'ftdTitle' does not allow nulls. on the 2026-09-18 and 09-28 runs). Neither --preflight nor the run's own reporting flags these items ahead of time. Batch results are also matched to their source items purely by array position, with no length or ID check. logBatchErrors could already name the wrong item, because it took a position from the failed list instead of from the batch.

Change

Validation before the API call (always on, no new flags)

• New validate-required-fields.ts checks each item against the target model's field definitions.
  • Fails when a Required field is missing or null. This applies to Text, LongText, HTML, Integer, Decimal, Date, DropdownList and Boolean.
  • Warns only on "", text longer than the field's Length, dropdown values not in Choices, and on Link, Image, File, Gallery, CustomField and linked-content fields. We haven't confirmed the API rejects nulls for those.
  • Field names and the Required setting are matched case-insensitively.
• The target model comes from a new run-scoped effectiveTargetModels registry, which the model pusher fills after a save. The target cache isn't rewritten after a save in the same run, so the registry is checked first, then the target cache, then the source model.
• Invalid items are removed in filterContentItemsForProcessing, before any batch is built.

Reporting

• Real runs: a skipped item appears in the console log, the ERROR SUMMARY and --jsonSummary failures, with the model, fields, contentID and locale. This covers both the linked-content pass and the normal pass. The item is registered as failed straight away.
• --preflight: a new invalid action, shown as a warning. It isn't counted as a create or update, and the exit code doesn't change.
• Cascade: the "Unresolved content reference(s)" message now names the skipped child and why. The failed-content registry is keyed by locale + contentID. In preflight, pages note "N component(s) would be dropped".

Batch alignment hardening

• prepareContentPayloads returns a single list of {source, payload} pairs, so payloads and source items can't drift apart.
• No API call is made for an empty batch. When a batch throws, only the prepared items are marked failed, so items aren't counted twice.
• extractBatchResultsImpl: if the number of results differs from the number sent, every item fails as "unverifiable batch result alignment". For updates, a returned itemID that differs from the contentID sent fails that item.
• logBatchErrors finds the payload through batchItemId. If it can't, it prints "unknown" instead of guessing.

Testing

• npx jest: 119 suites / 2,350 tests pass (main: 116 / 2,256). tsc --noEmit is clean.
• New hermetic scenario 17-required-field-missing-in-batch: item 2 of 4 is invalid, and the other three map to the correct target IDs.
• Unit tests cover:
  • the validator rules
  • filter routing
  • the model lookup order
  • an all-invalid batch, which makes no API call
  • the error path, with no double counting
  • a length mismatch and an ID mismatch
  • logBatchErrors naming the right item
  • the JSON summary
  • the cascade message
  • locale-scoped lookups
• Live read-only preflight 067c2568-us2 → e711e981-us2: 3 create / 5,843 skip / 24 conflict / 8 invalid. The invalid items are 7 DepositBanner items, including 12942 (ftdTitle, lowBalanceTitle, …), plus einstants_einstantallgames (sectionTitle). The exit code was 1 because of the 24 conflicts already on that pair, not the invalid items.

Known limits

• The ID cross-check is skipped for an --overwrite recreate of a deleted target, where the server can assign a new ID.
• Page batches get the length check but not the ID cross-check.
• PROD-2552 (the verify command) contains a copy of validate-required-fields.ts with the same interface. This branch's copy should win at merge.

Closes PROD-2542.

🤖 Generated with Claude Code