fix(objectql): [] no longer satisfies required on a multi-value field — the #9447 ruling's enforcement half

[os-elon]

Fixes#9476

What

required on a multi-value field now means non-empty array, per the #9447 maintainer ruling (2026-08-18). validateRecord judged required through isMissing (undefined / null / blank string), so an explicit [] satisfied a required multiple: true lookup on both INSERT and UPDATE while null was correctly rejected — the enforcement gap the card measured.

How

One def-aware helper, isEmptyForRequired(def, value) — isMissing(value) || (isMultiValueField(def) && Array.isArray(value) && value.length === 0) — read by exactly the two required sites:

• INSERT required check (validateOne): [] gets the required envelope, same as a missing value.
• UPDATE ADR-0113 non-regression check: a SUPPLIED [] is an explicit clear — the distinct required_cleared sentence (wire code required), same as an explicit null. An omitted field still never 400s.

Scope is the spec's own multi-value predicate (isMultiValueField, ADR-0104 D1): inherently-multi option types plus multi-capable types flagged multiple: true. Structured-JSON types stay out — [] there is a legitimate document (pinned). Every other path keeps def-free isMissing semantics untouched; a [] on a NON-required multi-value field still flows to the array-shape branch.

Reverse verification — the before leg was observed, not inherited

Fix committed first, then origin/main's validator stood up via git restore --source=origin/main -- …/record-validator.ts, and the new suite run against it (merge-base 2065e31d5):

• the three [] rejection pins FAIL — expected undefined to be an instance of ValidationError, i.e. today validateRecord(schema, { members: [] }, 'insert') and …'update' both pass, and multiselect [] passes — the card's measurement reproduced;
• all 79 other tests pass, including the null controls (insert required, update required_cleared) — the required machinery works; it never judged array emptiness.

Fix restored from the commit (git checkout HEAD -- …): 82/82 green.

The dispatch's three required pins

1. Rejection envelope — err instanceof ValidationError, err.code === 'VALIDATION_FAILED', fields[0] matching { field, code: 'required' }, plus the message sentence. On the status half: this validator-level error deliberately carries no .status property — REST maps the VALIDATION_FAILED class to HTTP 400 in packages/rest/src/error-response.ts (pinned in packages/rest tests); the new pin's comment names that mapping. Same envelope depth as the house's closest prior art (engine-lookup-referential-integrity.test.ts).
2. Populated-array control — ['u1'] on insert and ['u1','u2'] on update still land.
3. null controls — still rejected with the two DISTINCT reasons exactly as on main: insert renders the required sentence, update the required_cleared sentence (both keep wire code required; the two reasons are distinguished by message-catalog key, unchanged).

Rollout blast radius: zero, with a positive control

Probes: an order-free brace-block scan over every tracked .ts/.json/.yml under packages / apps / examples / scripts for field defs holding BOTH required: true AND (multiple: true OR an inherently-multi type: multiselect / checkboxes / tags), then a repo-wide grep for name: [] writes against every declared name.

• Shipped surface: zero. No platform object, plugin object, example, app, seed, or JSON metadata declares a required multi-value record field.
• Test surface: one declaration — rosterRequiredMulti in packages/objectql/src/engine-cascade-delete.test.ts (Docs and engine disagree on deleteBehavior: 'set_null' written EXPLICITLY on a required lookup — the escalation to restrict cannot see the difference #9625's pin). No [] write against it, and the cascade path cannot produce one: the engine escalates set_null on a required FK to restrict BEFORE the member-removal branch (engine.ts, pinned by Docs and engine disagree on deleteBehavior: 'set_null' written EXPLICITLY on a required lookup — the escalation to restrict cannot see the difference #9625), so a required multi-value set is never emptied by cascade.
• Positive control: the same probes find the planted declarations and [] writes this PR's own test block adds (members, labels) and Docs and engine disagree on deleteBehavior: 'set_null' written EXPLICITLY on a required lookup — the escalation to restrict cannot see the difference #9625's accounts — the probe demonstrably detects the class it reports absent elsewhere.
• Runtime probe: full @objectstack/objectql suite post-fix — 218 files / 3865 tests green, Docs and engine disagree on deleteBehavior: 'set_null' written EXPLICITLY on a required lookup — the escalation to restrict cannot see the difference #9625 cascade pins included.
• Surfaces that pattern-matched but are different machinery (never validateRecord, which has exactly four call sites, all in engine.ts): UI bulk-action params (project.view.ts), flow approval form (dynamic-approval.flow.ts), designer form defs (hook.form.ts / action.form.ts), SCIM group members, an auth-manager fake engine.

Fences

• cascadeDeleteRelations' set_null limb nulls the WHOLE multi-value array, dropping every other live reference #9438's cascade member-removal question untouched — and unreachable from this diff (see blast radius).
• [Decision] Multi-value lookup after set_null member removal: does the emptied array read back as [] or null? #9447 not weakened or re-opened; this is its enforcement half.
• No pre-existing pin asserts [] passes required — measured: the entire pre-existing suite stays green under the ruled behavior.

Follow-up finding (filed separately, not in this diff)

Two comments justify #9625's blanket cascade refusal partly by "today [] still satisfies required in the record validator (#9476)" — engine.ts (cascade region) and engine-cascade-delete.test.ts. That clause goes stale when this lands (the refusal itself stays ruled behavior). Out of this card's declared file surface and inside a concurrently-claimed file, so filed as #9781.

Gates

All local readings taken at final HEAD cd7aa7a42 (fix + merge of origin/main @ e9534a4ac), after the last commit — nothing changed after these runs.

• pnpm --filter @objectstack/objectql test — 218 files / 3865 tests green (also green pre-merge at the branch tip).
• pnpm --filter @objectstack/objectql typecheck — green.
• Dispatch lead, all green: check:cross-package-test-inputs (pnpm + node forms) · check:durability-log-level · check:error-code-casing · scripts/check-engine-split-ratio.mjs (informational, exit 0) · scripts/docs-audit/check-affected-docs.mjs.
• Re-derived via node scripts/pm/dispatch-gates.mjs (no paths — script derives the changed set): additions beyond the lead, all green: check:changeset-gate-self-tests · check:objectui-changeset · check-adr-0087-registration · check-changeset-no-major · check-empty-changeset · convention-triggered for a test-file edit: check:query-options-erasure · check:type-check-coverage · check:type-check-debt -- --re-measure (closure BUILT first via turbo run build --filter=./packages/* --filter=./packages/*/*; 33 ledger entries re-measured, none above recorded — baselines untouched) · check:engine-double-contract · check:where-matcher.
• check:nul-bytes — green.

Changeset

@objectstack/objectql patch with adr-0087: not-required (no-migration-prescription) — nothing authorable is renamed, retired, or tombstoned; a write-time data-plane tightening to a ruled, already-documented contract.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

3 anchor(s) derived from 1 changed package(s); no hand-written page names any of them. ✅

What this run could not see

Coarse fallback — 14 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 985a9cd2dbbad0bec9edce107f35d20791c9ac5c → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 2f3b48807e7856b55ab3fb78ac7a37f41a554cc6 — the merge of head cd7aa7a42c31a112c24c5545660683ffdbd448ce into base 985a9cd2dbbad0bec9edce107f35d20791c9ac5c, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 2f3b48807e7856b55ab3fb78ac7a37f41a554cc6 && git checkout 2f3b48807e7856b55ab3fb78ac7a37f41a554cc6
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 985a9cd2dbbad0bec9edce107f35d20791c9ac5c cd7aa7a42c31a112c24c5545660683ffdbd448ce && git checkout -B drift-repro 985a9cd2dbbad0bec9edce107f35d20791c9ac5c && git merge --no-ff cd7aa7a42c31a112c24c5545660683ffdbd448ce
node scripts/docs-audit/affected-docs.mjs --json 985a9cd2dbbad0bec9edce107f35d20791c9ac5c

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.