feat(objectql): enforce the select idiom — the option marked default: true is the field default (#7246) - #7388

Closes #7246

Executes the maintainer ruling of 2026-08-10 (comment 5237213604): enforce. That ruling post-dates and supersedes the 06:50Z delegated retire-ruling, which had declared its own veto condition ("a maintainer word reverses this at zero cost").

SelectOption.default was authorable, spec-valid, and read by nothing on the insert path. Its only consumer anywhere in the repo was lint's isNullableField, which concluded from it that a column was always valued — a build-breaking verdict resting on a declaration the engine did not honour. This makes the declaration real, which is what makes that heuristic honest.

1. Premise check — re-verified on origin/main before implementing

Premise holds in full. No part of the card had expired.

Spec schema is untouched — the key already exists, so there is zero acceptance-face movement. packages/spec/, docs/adr/ and content/docs/releases/ have no changed files in this PR.

2. Corpus census — whose insert behaviour moves

Scanned the whole repo (comment-stripped, brace-balanced per field, so a container fields: block is not miscounted as a field). 31 fields declare an option marked default: true.

• 30 declare no defaultValue → insert behaviour moves (null becomes the marked option)
• 1 declares both — examples/app-crm/src/objects/lead.object.ts:41 status, option new + defaultValue: 'new'. They agree, so nothing observable changes; it is now resolved by the defaultValue path.
• 0 fields mark more than one option; 0 fields with multiple: true carry a marked option (the corpus's two multi-selects — app-todo task.tags, sys-webhook.triggers — mark none). Both of those shapes are still decided and pinned below, since the spec permits them.

The 30 whose behaviour moves, all status/stage/priority-style selects whose marked option is the intended initial state:

Every one is a change toward what the declaration always described, and 13 of them are additionally required — those inserts previously had to supply the value or be rejected, and now default cleanly.

3. Design points, decided explicitly

(a) multiple: true, and several options marked

Decision: multiple: true assembles an ARRAY of every marked option in declaration order. A single-valued field takes the FIRST marked option.

This is not a style preference — it is what the surrounding contracts already require, measured rather than assumed:

• FieldSchema.multiple is documented "Allow multiple values (Stores as Array/JSON)", so the default's shape must follow the field, not the number of marked options. One marked option on a multi-select is therefore a one-element array, never a bare scalar.
• validateRecord's multi-value branch rejects a non-array outright (invalid_type_array, packages/objectql/src/validation/record-validator.ts). A scalar default on a multiple: true field would have failed the engine's own validator on the very insert it was meant to complete. This is the measurement that settles the question.
• The Field.select builder normalizes option value to lowercase and does not dedupe or refuse the default flag, so "several marked on a single-valued field" is reachable metadata. One slot means declaration order decides — deterministic, and the option a picker preselects when it takes the first match.
• Refusing (throwing) was rejected: the metadata is spec-valid, and a runtime throw on spec-valid input is a worse answer than a well-defined value. Ignoring multi-selects was rejected too — it would preserve, for that one shape, exactly the inertness this change removes, with a carve-out the author cannot see from the schema.

(b) SQL DDL — no physical column DEFAULT for an option-default

Decision: the DDL does NOT emit one. The asymmetry with a defaultValue literal (which is emitted) is the decision, not an omission, and it is recorded on SqlDriver.applyDeclaredColumnDefault so nobody "fixes" it by accident.

The #4560 engine-token discipline does not forbid emitting here — an option's value is a plain literal, not a runtime token, so it could legally be emitted. The reasons not to:

1. One resolver owns the precedence. defaultValue beats the option flag, and that ordering lives in the engine. A column DEFAULT is a second resolver that fires only where the engine did not.
2. The shape has no scalar DDL form. On multiple: true the default is an array; emitting would need an invisible "except for multi-selects" carve-out.
3. It would divide deployments silently. applyDeclaredColumnDefault runs for a fresh column (createColumn) and a re-materialized one (rebuildSqliteTablePatched) — never a retrofit. Emitting would give new databases, and any SQLite rebuild, a DEFAULT that older databases on identical metadata lack. Schema-drift semantics checked: detectDrift's only default_mismatch producer is the data: the SQL driver emits the current_user framework token as a literal column DEFAULT, so the database itself writes a non-id into a lookup('sys_user') #4560 runtime-token check, and there is no general declared-literal-vs-physical comparison anywhere — so nothing would ever report that divergence.
4. It would make SQL the odd driver out. The engine fallback serves memory, mongodb, sql and turso identically from day one; a SQL-only second enforcement point is precisely the per-datasource split that data: the SQL driver emits the current_user framework token as a literal column DEFAULT, so the database itself writes a non-id into a lookup('sys_user') #4560 and data: the NOW() defaultValue token is unresolved on non-SQL datasources — the engine stamps the literal string, and the record validator then rejects the insert #4597 were both about.

Consequence, stated in the tests rather than left implicit: only a writer bypassing the engine entirely sees NULL — and that writer is not reading options either.

(c) Presence semantics

The engine's own dv == null test governs. The fallback fires only when defaultValue is absent by that test, so defaultValue: '' is a real default and wins over the option flag — the same rule that makes a caller-supplied '' a real value. Reading presence as truthiness instead would silently store the marked option where the author declared "empty".

(d) Ordering

The fallback resolves inside the defaultValue == null arm, downstream of the token and envelope branches — after reading applyFieldDefaults' real structure. This is structural, not a name check: an option value can therefore never be handed to isCurrentUserDefaultToken / isNowDefaultToken. An option spelled current_user is a picklist entry and stores those twelve characters, not the acting user's id. Pinned by test.

Two further decisions worth naming

• Type-agnostic, exactly like the lint heuristic. options is a field-level key on FieldSchema, not gated on type: 'select', and isNullableField reads it with no type test. Matching that keeps both sides honest by construction: there is no field lint calls always-valued that the engine leaves empty.
• Canonical default spelling only. isDefault / selected are SelectOptionSchema authoring aliases, normalized before metadata reaches the engine. Honouring them here would move the alias contract out of the schema that owns it.

4. Reverse verification — direction predicted in writing first

RV-1: delete the engine fallback

Predicted 7 RED / 7 GREEN, per case, before running. Observed: exactly that, and the 7 reds were the 7 named cases.

× fills an OMITTED field with the marked option — the issue repro
× fills an EXPLICIT null too — the unpicked-control shape (#2706)
× an option spelled `current_user` stores the twelve characters, not the actor id
× `multiple: true` assembles an ARRAY of every marked option, in declaration order
× `multiple: true` with ONE marked option is still an array — shape follows the field
× a SINGLE-valued field takes the FIRST marked option — one slot, declaration order decides
× no `type` test — `isNullableField` has none either, so neither may have one
 Test Files  1 failed (1)
      Tests  7 failed | 7 passed (14)

The greens were predicted, not accidents — and three of them are an inverted direction worth stating plainly. The precedence pins (cases 5–7: defaultValue wins, defaultValue: '' wins, envelope wins) cannot go red when the fallback is deleted: they pin the winner of a two-key contract, and removing the loser does not move the winner. What they guard is the opposite future change — a fallback that starts outranking defaultValue. The remaining greens (3, 4, 12, 14) assert a caller-supplied value or an unset field, which is the reverted behaviour by definition. Reporting these as reds would have required a template-shaped fabrication.

RV-2: make the DDL emit an option-default (the rejected branch of decision (b))

Predicted 2 RED / 1 GREEN. Observed: exactly that — the pin genuinely guards the decision rather than passing vacuously.

× creates an option-defaulted column with NO database default
    AssertionError: expected '\'draft\'' to be null
× a driver-level insert that omits the field stores NULL — the engine, not the database, defaults it
    AssertionError: expected 'draft' to be null
 Tests  2 failed | 1 passed (3)

The green one is the defaultValue-still-emitted regression case, untouched by that branch, as predicted. The probe was reverted immediately (git checkout HEAD --); it appears in no commit.

RV-3: lint

No reverse verification is claimed, because there is nothing to revert. isNullableField's logic is byte-identical; only its docstring changed, to record what now grounds the select-idiom branch. Its suite is run below purely as a regression guard. Manufacturing a direction here would have been a fabrication.

Reverse verification used git checkout origin/main -- ... and git checkout HEAD -- ... throughout — never git stash, whose stack is shared across every worktree of the repo.

5. Gates and tests

All heavy runs were serialized under flock /tmp/os-heavy-verify.lock with a capped heap and --maxWorkers=2.

Changeset: .changeset/select-option-default-enforced.md, @objectstack/objectql: minor, with a migration note. Level taken from precedent, not invented: qa-testing-liveness-enforce.md (the closest analogue — an ADR-0049 enforce leg) and autonumber-default-format-contract.md are both minor. lint and driver-sql carry documentation and test changes only, no behaviour, so neither is bumped.

No ADR or spec edit was needed, and none was made — no gate asked for one.

6. objectui rider

Per the ruling, objectui#4068's defaultValue-only seeding stays correct: after this lands the server honours option-defaults on omitted fields, so the console needs no second default contract. No objectui change accompanies this PR.

7. One thing found, not fixed here

defaultValue: '' on a single-valued select/radio is unstorable — validateRecord checks the value against optionValues(def.options) and '' is not among them, so the insert is refused as invalid_option. This is pre-existing and entirely unmoved by this PR; it surfaced only because a first draft of the precedence test used a select to pin the '' case. The test now pins that precedence on a free-form type, and says why in a comment. Flagged for the record rather than filed, since it is a design question about whether '' should be an authorable default on a closed value set, not a defect with a user hitting it today.

8. CI round 1 — two real failures from this change, both fixed here

The first CI round on this branch went red twice, and both were genuine blast radius, not flakes. Neither was visible to the three package suites run locally, which is the honest lesson: a behaviour-moving default reaches suites the changed packages do not name.

8.1 Test Core (2/3) — examples/app-showcase/test/hook-body-persisted-writes.test.ts (#7258)

Two cases, both about showcase_inquiry.status — a census'd field (inquiry.object.ts:37, option new). Re-pinned to the new contract rather than worked around:

Noted, not changed: StampInquiryDefaultsHook's status branch is now largely redundant with the engine (it still fires for an explicitly-supplied falsy value). It is a demo app's belt-and-braces hook and rewriting it is not this issue's scope.

8.2 TypeScript Type Check — the TEST_DEBT ratchet, not a type break

@objectstack/objectql's TEST_DEBT ledger records 355 raw tsc errors and the run reported 356 (+1). The ledger is a shrink-only ratchet, so +1 is red.

The cause was in this PR's new test file: 12 registry.registerObject(def) calls passing one argument where the signature is registerObject(def, ownerId, …). It was invisible to pnpm --filter @objectstack/objectql typecheck because the package's own tsconfig excludes its tests — that exclusion is precisely what TEST_DEBT measures, so the local green and the CI red were both correct about different things.

Fixed at the source by passing the owner id ('test.issue7246') rather than by raising the ledger. Re-measured with the gate's own method (tsconfig.test-equivalent, test exclusion lifted): 344 errors, 0 of them in this PR's files — at or below the recorded 355, so the ratchet is satisfied. The remaining 355→344 surplus is pre-existing on main and deliberately left alone; the gate states an improvement must not pay a bookkeeping toll to land.

Generated by Claude Code

Generated by Claude Code