fix(objectql)!: refuse a field whose type is absent or not a FieldType member at the registration door (#16319) - #17444

Fixes #16319

Clause-②: yes

Ruled by the dispatching seat and posted as a corrected claim: #16319 (comment) — same session, same branch, same assignee, so the original claim stays governing and this PR posts no second one. needs:contract-review is hung on both carriers (node scripts/pm/check-clause2-carriers.mjs --pair 17444 exit 0); the seat clears it in the same stroke as the review PASS.

A field declaration whose type is absent, or is not a FieldType member, is now refused at the registration door, and the whole object declaration goes with it. Every downstream family default the card measured becomes a loud refusal instead of a guess.

Maintainer ruling, 2026-09-10 (director seat batch #111 item 2), verbatim: 「16319 一个没写 type(或拼错)的字段 应该禁止加载。这个才是合理的吧?其他同意」 — implemented per the director seat's derived shape in that comment, not per this PR's summary of it.

What was wrong

One declaration produced two different columns. Re-derived by symbol on this branch's own head; the live PostgreSQL 16.13 table is the card's:

SqlDriver.createColumn read field.type \|\| 'string', which heads its STRING-family arm and sizes the column from the declared maxLength. All four os generate loops read String(fieldDef.type \|\| 'text'), which heads the TEXT family. Both directions of harm are in row 1: the platform refuses a 101-character value both generated tables accept.

What this does

1. The single point of closure is SchemaRegistry.registerObject. It refuses the WHOLE object declaration with the ADR-0112 envelope (INVALID_METADATA + 422), naming the object, the field and the reason, with the spec's own "did you mean?" for a mis-spelling. All three contributor kinds (own / overlay / extend) are judged — ObjectSchema.fields and ObjectExtensionSchema.fields are both z.record(z.string(), FieldSchema). ⛔ The field is never dropped on its own.
2. loadMetaFromDb's startup policy is revised for this class. 「Registered anyway so it stays serveable and fixable」 no longer applies: the row does not register, and the log states the consequence and the fix once, at error. It is suppressed only for this class, through the door's OWN predicate — the boot log never grows a second opinion about what the registry admits.
3. Downstream guesses become refusals. createColumn refuses a field with no type; all four os generate loops refuse an absent or non-member type and generate nothing for that object. fieldTypeToSql's docblock is rewritten in the same stroke.
4. Changeset carries the BREAKING note and its ADR-0087 disposition.

The shared vocabulary lives in @objectstack/metadata-core (object-field-type.ts) for the ordinary reason: the enforcing door is objectql's and the reporting seam is metadata-protocol's, and objectql depends on metadata-protocol, so the reverse import is a cycle turbo refuses.

The ruling's implementer PRECONDITION — measured, not argued

若 Studio 的元数据列表只从注册表读,被拒的行会从界面消失而无法修 —— 那时停手回报

It does not. getMetaItems ALWAYS consults sys_metadata and merges its rows in; it never serves the registry alone. Pinned in registry-field-type-refused-at-door.test.ts §4: a refused row is still listed, still served with the offending field visible, still accepts a corrected write (which then loads on the next boot), and is still deletable. deleteMetaItem gets more permissive, not less: with nothing registered, isArtifactBacked is false and the DB-only branch applies (object is allowRuntimeCreate: true). No stop condition fired.

Clause-② — RESOLVED: no → yes

INVALID_METADATA is already registered under @objectstack/objectql in ERROR_CODE_LEDGER (4 hits) and this PR touches no ledger file; the driver reuses the standard-catalog VALIDATION_ERROR. ⛔ No new error code is minted, so the ruling's own stated flip condition did not fire.

⭐ The declaration flips for a reason the ruling never anticipated. This PR adds new exported symbols to @objectstack/metadata-core — findUndeclarableFieldType, describeUndeclarableFieldType, isDeclarableFieldType, isObjectFieldTypeRefused, OBJECT_FIELD_TYPE_REFUSED_ERROR_NAME, plus three types — and contract-review's mechanical floor is 「新导出符号…恒 yes」. The dispatching seat re-measured rather than accepting the reading: all five read 0 on origin/main d57611dfd3 with index.ts itself as the firing control. Both conditions had to be checked; only one fired, and it was not the written-down one.

This PR raised it rather than rewriting the declaration, because the declaration is the claiming seat's act. The seat has now corrected it.

@objectstack/objectql's own public surface is deliberately unchanged: the new names are not re-exported from its index, and the error CLASS stays unexported — the #14936 dual-realm convention, where a consumer holding the other realm's copy gets instanceof === false silently, so consumers discriminate on the error's name. ⛔ No changeset regrade is owed: all five moved packages/**/src/** packages are graded minor.

Acceptance

• ✅ The card's two-row PostgreSQL table becomes two refusals — at the registry, so the driver is never reached (registry-field-type-refused-at-door.test.ts §1–2).
• ✅ The in-repo field scan stays green: 1341 fields / 116 objects / 111 modules loaded, 0 undeclarable. Control fired (sys_file.id type='text', sys_file.key type='text', sys_file.name type='text'), so the zero is a reading, not an empty walk. The one module that fails to load is create-objectstack's blank template, which declares through Field.text() / Field.textarea().
• ✅ A seeded typeless sys_metadata row leaves the object out of the registry, is named at error, and stays deletable.
• ✅ Ablation — see below.

Ablation

Fix committed first; mutation proved on disk (git hash-object before/after) and proved to reach dist/ (scripts/ablation-dist-preflight.mjs, marker present in 4 built files); probe imports resolve entirely through package exports.

With the door removed the object reappears and, driven into the driver, row 2 falls back to varchar(255) — the ruling's own predicted ablation, observed. Row 1 is refused by the driver's own defence instead, which is stronger than the ablation predicted; reported as observed rather than as the template's expectation. A second leg ablated the same statement and ran the new suite: 6 of 12 tests go red, the six that do not being the positive controls and the non-throwing seam test.

Restore verified whole-tree, not per path: git status --porcelain empty, git hash-object equals the HEAD blob, --absent preflight exit 0.

Scope — the driver's defence is narrower than the door, deliberately (⛔ not a dropped half)

⭐ First, so the commit title narrow the driver refusal to an absent type cannot be read as half the ruling being dropped: BOTH shapes — absent AND non-member — are refused. They are refused at the REGISTRATION DOOR, for the whole object, which is the single point of closure the ruling asked for and what its acceptance list means by 「驱动永远到不了」. What is narrower is only the driver's own defence-in-depth layer, which the ruling itself describes as 「按构造它们应当不可达,拒绝是防御」.

SqlDriver.createColumn refuses type ABSENCE (the \|\| 'string' default the ruling names), not FieldType MEMBERSHIP. Membership is refused for the whole object at the registration door, which fronts every route into syncSchema — which is what the acceptance list's 「驱动永远到不了」 means. Measured reason for not going further here: driver-sql's own corpus declares 388 non-member spellings across ~100 files ('string' 361, 'integer' 17, 'auto_number' 5, 'varchar' 4, 'object' 1) that drive initObjects directly and never touch the registry, and 'string' is a declared case arm of that switch whose column shape differs from every member's — so closing that half is a corpus migration with column consequences, not a spelling fix. A pin holds the boundary in both directions so it cannot move silently. Control for that census: type: 'text' reads 164 and type: 'datetime' reads 60 in the same corpus.

Verification

pnpm build (whole repo) · pnpm lint in its exact spelling (node --stack-size=4000 … . --no-inline-config) exit 0 · --format json over the same population: 6556 files, 0 errors, 0 warnings, and all 15 changed files are inside it — a whole-tree reading, not a narrowing. All at a05a28520a.

• @objectstack/objectql 4959 passed / 296 files · @objectstack/metadata-protocol 2487 passed · @objectstack/driver-sql 2495 passed · @objectstack/metadata-core 272 passed · @objectstack/cli --project unit 2678 passed (the integration tier is declared to CI: the diff touches no spawn entry point or driver/kernel boot path).
• typecheck green on all five packages, and the test-typecheck-debt ledger shrank — see below.
• 69 of 69 derived gate families run, all green (node scripts/pm/dispatch-gates.mjs --commands, reconciled with --ran: 69 derived, 69 run, 0 NOT-MEASURED, 0 UNRUN). Two needed a whole-repo pnpm build before they could measure at all (check:dual-build-cjs-loads, check:i18n-coverage — both exit 3 = PREREQUISITE NOT MET, never a pass) and are green after it. check:query-options-erasure went red on the new test files and is fixed, not waived. check:type-check-debt needed the CI-shaped heap ceiling; at 4096 MB its own tsc re-measure OOMs and it exits 3.

⭐ The type-check debt ledger shrank, and WHY is the best finding in this round

packages/objectql/test-typecheck-debt.json goes 44 → 40 files / 242 → 234 errors, and the four deletions are not tidying: they are the defect this card closes, seen from the compiler's side.

Those four fixtures declared type: 'longtext' as const (three of them, on a sys_metadata metadata field) and type: 'id' / type: 'string' (the fourth) — five spellings the FieldType enum has never contained. The as const / as casts they needed to get past tsc WERE the recorded errors. The debt was a symptom. Once the registration door refuses such a declaration outright, the fixtures had to be corrected to the members the platform's own sys_metadata object actually uses (Field.textarea / Field.text), the casts stopped straining, and the entries graduated — which the ledger's own header requires be deleted in the same change.

⛔ Nothing was raised to absorb an error: this is the shrink direction throughout. The ledger's _note is amended so its seed counts ("242 errors across 44 files", measured at 2a181174a6) are not read as this file's current totals.

Acceptance notes

Noted, not filed:

• createColumn's case 'string': arm and varcharColumnChars' matching arm are now unreachable from any registry-fronted path — 'string' is not a FieldType member, and [finding] sql-driver.ts twice cites a Field.string builder that has never existed — and the prose demonstrably steered a ruling onto an unauthorable target #12593 already measured that. Dead-code removal, out of scope here.
• sql-driver.ts carries 11 declaration-side 'string' defaults, not the 7 the dispatch measured or the 1 the card implies: \|\| 'string' at :2411 :9976 :10054 :11951 :16189 :16555 and ?? 'string' at :10686 :10891 :14753 :14760 :14818; two further \|\| 'string' at :17726 :17728 default an INTROSPECTED column's type and are a different question. The dispatch's list of 7 missed :17726 and did not separate the ?? spelling. Only :16555 (createColumn) is the ruled default; the rest are comparison classes, coercion-registry fills, candidate sets and error text, all downstream of the same closed door. schema-drift.ts carries 4 more (:549 :1066 :1282 :1297).
• os generate types' asymmetry between the two shapes (a typeless field emitted string, a mis-spelled one unknown) is retired by construction — both now refuse — so the domain:cli seat's earlier note on it needs no card.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XTBcV7zZHmokdyQgXjbyEU

Generated by Claude Code