[objectstack-fleet]

domain:server#3 · os-steve · session_01ADHkmQJdgarUjPLNgFBY67

Requested by Steve · project thread
Fixes #29277

Clause-②: yes (widening)
Metadata-protocol: none

维护者速读

• 改了什么：可选的单值选项、引用、文件字段（select / radio / lookup / master_detail / user / tree / image / file / avatar / video / audio）被清空（送来 ''）时，服务端写入口改存 null，唯一与否都一样。哪些类型算在内由 $empty 规则表的 null_only 行加「存一个字符串」推出，不靠手写名单。唯一字段上第二条清空的记录不再被 409 UNIQUE_VIOLATION 拒绝，清空的记录也能被「为空」筛选到。
• 种子重放：服务端把空白存成 null 的规则（三条：record write door: '' skips every type check, so a number, boolean, date, datetime or time column stores an empty string — normalise it to null at the door (seam from objectui#10813) #20308 类型列、data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176 唯一文本、本卡单值列）移到 @objectstack/core 一处（blankAsNullColumns / blankStorageForm），写入口和种子加载器的重放比较都读它。种子里写 '' 的行重放时不再每次被当作变更重写（主干上三条都会这样空转，已实测）。core 新增导出，所以声明改为 Clause-②: yes (widening)。
• 为什么改：维护者裁决 [Decision] records: a cleared single select or lookup is stored as '' by API / import / flow writers. Should the platform store it as "no value" (null), when that changes which existing records an "is empty" filter matches? #29346 选 B（记录 6579813296）。'' 既不是选项值，也不是记录 id，本来就不该算一个值；$empty 规则表在这些类型上只认 null 为空，规则表不动。
• 风险与回滚：这些字段清空后读回的是 null 而不是 ''，按 = '' 查询的条件对新清空的记录不再命中。必填字段照旧拒收 ''，multiple: true 字段不动，已存的 '' 不迁移（迁移另立卡）。回滚 = revert 本 PR。
• 先看：packages/core/src/utils/blank-storage-form.ts（规则本体）；packages/metadata-protocol/src/seed-loader.ts 的 ReplayComparands.blankAsNull 与 isNoOpReplay；packages/objectql/src/validation/record-validator.ts 的 normalizeBlankTypedValues；packages/rest/src/rest-data-single-value-blank.test.ts；.changeset/29277-single-value-blank-null.md。
• 两分钟验证：pnpm --filter @objectstack/rest exec vitest run src/rest-data-single-value-blank.test.ts，预期 11 个测试全绿（主干上第二次清空是 409，$empty 查不到清空的记录）；pnpm --filter @objectstack/runtime exec vitest run src/seed-blank-as-null-replay.integration.test.ts，预期 2 个全绿（主干上重放 totalUpdated 为 4）。
• 需要你做的：无，席位落地。

What changes

• The ruling. Maintainer ruling B on [Decision] records: a cleared single select or lookup is stored as '' by API / import / flow writers. Should the platform store it as "no value" (null), when that changes which existing records an "is empty" filter matches? #29346 (record 6579813296): the write door stores '' as null on every optional column whose type sits on the $empty table's null_only row and is string-stored single-value. The $empty table is unchanged; required keeps refusing ''; a blank on insert takes a declared defaultValue; cleaning stored '' is a separate migrate-lane card.
• The seam. normalizeBlankTypedValues (packages/objectql/src/validation/record-validator.ts), the engine's existing blank write door: ObjectQL.insert() / insertMany() / update() (by id and by predicate) and the dry run validate() apply it before anything else reads the payload, and every REST, batch, upsert and import door reaches the engine through those methods. engine.ts is not touched.
• The new arm. The door's blank-as-null rule is now ONE function in @objectstack/core (packages/core/src/utils/blank-storage-form.ts): blankAsNullColumns(objectSchema) maps each column to its reach, 'blank' (any isMissing blank: the record write door: '' skips every type check, so a number, boolean, date, datetime or time column stores an empty string — normalise it to null at the door (seam from objectui#10813) #20308 typed arm, NON_TEXT_STORED_VALUE_TYPES, unchanged) or 'empty' (exactly ''), and blankStorageForm(value, reach) gives the stored form. An 'empty' column is not required: true, not a lifecycle column the engine owns (ENGINE_LIFECYCLE_COLUMNS, which the validator's SKIP_FIELDS now reads), and EITHER text-like and unique-covered (data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176, unchanged) OR on the $empty table's null_only row (expandEmptyOperator(def).arm, read first, so a multiple: true column, the multi_value row of objectql: a multi-value unique column (multiselect, or lookup with multiple: true) cleared to [] on two records refuses the second with 409 UNIQUE_VIOLATION #29343, is out) AND storing one string (ONE_STRING_STORED_TYPES). normalizeBlankTypedValues consumes it and keeps no arm logic of its own.
• The seed replay (round 3). isNoOpReplay (packages/metadata-protocol/src/seed-loader.ts) compared a seed '' literally with the stored null, so every seed row writing '' on a blank-as-null column read as changed and was rewritten on each replay. A new replay comparand ReplayComparands.blankAsNull (built once per dataset from the definition by blankAsNullColumns, beside temporal and masked) puts the SEED side in its stored form before seedValueEquals. There is no blanket '' == null: on a column the door keeps '' (plain text), a seed '' against a stored null is still a change (pinned). Pre-existing on main: measured on head 071872b7 (where the record write door: '' skips every type check, so a number, boolean, date, datetime or time column stores an empty string — normalise it to null at the door (seam from objectui#10813) #20308 and data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176 arm code and the seed loader are byte-identical to origin/main), a replay of one '' per arm rewrote 4 of 4 rows: the number, date and unique-text rows churned before this PR, and the select row is this PR's arm. All three arms are now pinned.
• The storage-shape set. The spec has no predicate for "stores one string", so ONE_STRING_STORED_TYPES is stated once, in core, from the spec's classes: SINGLE_OPTION_TYPES (an option code), REFERENCE_VALUE_TYPES (a record id), FILE_REFERENCE_TYPES (an opaque sys_file id). A pin ties it to the table: every FieldType whose expansion is null_only and that the typed arm does not own must sit in exactly one of that set, STRUCTURED_JSON_TYPES or COMPUTED_VALUE_TYPES, so a type that joins the row unclassified turns the pin red.
• Left out, measured on SQLite through the engine (non-blank value, then '' twice, on a unique column): json, composite, record, location, address, repeater, vector store an object or an array ({"a":1}, [0.1,0.2]), so '' is not a blank of their shape; formula is never stored; autonumber is issued by the engine on insert whatever the caller sent (A-1, A-2, A-3 for a value, '', ''). The file references stored one string id (JSON-encoded on SQL: "img_1") and a second '' was refused DUPLICATE_RECORD, so they join.
• Edges. Exactly '': whitespace stays a value (on a reference column the referential-integrity check refuses it, before and after). Lifecycle columns (created_by, updated_by) are never rewritten. owner_id (an injected optional lookup) is in the set; the security middleware already reads owner_id '' and null as one (security-plugin-authz-middleware.ts, the row.owner_id == null || row.owner_id === '' checks), so its answer does not move.
• New export (Clause-② widening). @objectstack/core exports blankAsNullColumns, blankStorageForm, ENGINE_LIFECYCLE_COLUMNS and the types BlankAsNullReach / BlankAsNullFieldDef. The changeset adds @objectstack/core and @objectstack/metadata-protocol patch entries. No spec edit.
• The fence. Neither the BOUNDED_STRING_FIELD_TYPES string arm (records: a number or a boolean written to a text-family field is admitted on its string reading but stored as the raw number/boolean, so a text column hands back 42, not "42" #29241) nor the select value-shape check (records: a free-form select field (no options) admits a plain object or an array on create and stores it as-is, although a select's stored value is a scalar option value #29244) is touched.
• Pending changeset corrected. .changeset/29176-optional-unique-blank-null.md (unreleased) said select / lookup columns keep storing ''. This PR makes that false in the same release, so the sentence now says text columns keep '' and points at this change. That is a deliberate correction of another PR's pending changeset, so check-empty-changeset reports it (see Verification).

Why

'' is neither an option code nor a record id. Stored as sent, it was a value to SQL UNIQUE (the second cleared record on a unique column was refused 409) and not empty to $empty, whose ruled table reads only null as empty on these types. The formula matcher, having and CEL isBlank already read '' as empty, so the SQL face now agrees with them for every newly cleared row.

Tests

New files:

• packages/objectql/src/validation/record-validator.single-value-blank.test.ts (8 tests): the population derived from FieldType and the table, with every untyped null_only type classified into exactly one storage class; the joined set (11 types) and the left-out set (9 types) pinned; the left-out types keep ''; '' becomes null on every optional member, unique or not; required (with and without a defaultValue) keeps ''; multiple: true is the multi_value row and keeps ''; lifecycle columns untouched; whitespace and non-blank values untouched; purity.
• packages/core/src/utils/blank-storage-form.test.ts (7 tests): each arm's reach (typed incl. required and lifecycle created_at; unique text by field and by index, plain text and password out; one-string select / lookup / image in, required / multiple: true / json / autonumber / created_by out); the lifecycle list; an unresolvable definition declares none; blankStorageForm per reach.
• packages/runtime/src/seed-blank-as-null-replay.integration.test.ts (2 tests), real ObjectQL + SQLite SqlDriver + SeedLoaderService: one seed '' per arm (number, date, unique text, select) lands null and a replay skips all four (totalUpdated: 0, totalSkipped: 4); control: a plain text column stored null and reseeded '' is still updated and stores ''.
• packages/rest/src/rest-data-single-value-blank.test.ts (11 tests), real ObjectQL + SQLite SqlDriver + RestServer routes, physical column read past the engine: POST '' on all eleven joined types stores NULL; PATCH clear on all eleven; unique select + lookup created '' twice and cleared by PATCH twice both land; a unique image created '' twice both land; a declared unique-index member; batch create and createMany; a real duplicate still 409 UNIQUE_VIOLATION; required select / lookup still 400 VALIDATION_FAILED / required (one with a defaultValue); a blank on insert takes the declared defaultValue exactly as null does; the $empty pin: on a row written '' past the engine, $empty: true answers only the newly cleared row, $empty: false answers the legacy '' row and the valued row, = '' answers only the legacy row.

Forced edits to existing tests (each pinned that a select / lookup '' stays '', which the ruling reverses):

• packages/objectql/src/validation/record-validator.blank-typed-value.test.ts: the string-stored control list drops the option and reference types (they keep their "not typed" assertion).
• packages/objectql/src/validation/record-validator.optional-unique-blank.test.ts: the "other string-stored" control is now autonumber only.
• packages/objectql/src/engine-optional-unique-blank-door.test.ts: the unique pick (select) / ref (lookup) columns move from the kept-'' set to the covered-null set.
• packages/objectql/src/engine-blank-typed-value-door.test.ts and packages/rest/src/rest-data-blank-typed-value.test.ts: the c_lookup / c_select controls now expect null; c_text still ''.

Round 3 forced edits (no expectation changed):

• packages/runtime/src/seed-blank-reference-real-driver.integration.test.ts: the comment at the loan-empty assertion said the insert door "does not null" a blank lookup; it now says an optional lookup's '' is stored as null since objectql: a cleared optional unique lookup or select still stores '' and the second cleared record is refused 409 UNIQUE_VIOLATION #29277 and the replay compares it in that form. Its expectations (totalUpdated: 0, totalSkipped: 6) are unchanged and now pass.
• packages/objectql/src/federated-injected-column-readers.test.ts: four VOCABULARY rows (validation/record-validator.ts#<module> :: created_at / created_by / updated_at / updated_by) deleted, as the census asks when a seam use leaves the source: the lifecycle names moved to core's ENGINE_LIFECYCLE_COLUMNS.

Red on main, green on head

The two new files were committed first (0acdf485) and run against origin/main 96fb7b5d's objectql build: rest Tests 9 failed | 2 passed (11) (POST stored ''; unique [201, 409] on create, [200, 409] on PATCH and the index member; batch [true, false]; defaults not applied; $empty: true answered []), unit Tests 2 failed | 5 passed (7). Two of those rest reds were my own fixture faults (a tree value naming no record of its object, a whitespace lookup id the referential-integrity check refuses), fixed in a71af048; the whitespace case moved to the unit file. On head: rest 11/11, unit 8/8.

Ablations

Made with scripts/ablation-replace.mjs (anchor hit once), objectql rebuilt, marker proven in dist by scripts/ablation-dist-preflight.mjs ("marker present in 4 built files"), each restored with git checkout HEAD, blob hash equal to HEAD, then a final rebuild with the marker absent from all 8 built files and the rest file green (10/10 round 1, 11/11 round 2).

Ablation	Red
L1: the new arm off (isSingleValueCodeColumn never true)	rest Tests 8 failed | 2 passed (10) (every positive case, including the $empty pin), unit 2 failed
L2: the table-row check removed (a multiple: true column joins)	unit a multiple: true column is the multi_value row, not this arm
L3 (round 2): FILE_REFERENCE_TYPES dropped from the one-string set	rest Tests 3 failed | 8 passed (11) (POST, PATCH, unique image), unit "" on every optional member becomes null
L4 (round 2): STRUCTURED_JSON_TYPES added to the one-string set	unit the left-out types keep ""
L5 (round 3): the replay comparand off (isNoOpReplay compares the raw seed value), metadata-protocol rebuilt	runtime Tests 2 failed | 2 passed (4): seed-blank-as-null-replay (replay totalUpdated 4) and seed-blank-reference-real-driver :161 (1), the CI red; the plain-text control and the required case stay green. Restored from a copy, blob hash equal, rebuilt, both green.

The required / lifecycle / whitespace exclusions are the #29176 lines, ablated on PR #29271; the required and default pins here pass on base and head, as they must.

Acceptance notes

• Clause-②: yes (widening). @objectstack/core gains exports (round 3, the seat's ruling 6582252856). Measured: no door refuses anything it accepted. '' on every ruled type was accepted (201 / 200) on base and is on head; required refusals are identical on both. A second unique clear moves from 409 to 201, the same direction data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176 declared no.
• Read shape. A field cleared from now on reads null, not '', and matches $empty: true, $null: true and = null; it no longer matches = '' (the changeset says so). Stored '' rows are not migrated and keep their old answers; the migrate-lane card cleans them.
• File reference types join (seat 3's round-2 reading of ruling B, comment 6581612131: the rule is stated by the table plus the storage shape). A multiple: true file or image column is the multi_value row and stays out (objectql: a multi-value unique column (multiselect, or lookup with multiple: true) cleared to [] on two records refuses the second with 409 UNIQUE_VIOLATION #29343).
• Not measured: PostgreSQL, MySQL (same knex path), MongoDB (the mongod download is 403 in this container).

Verification

Head 22a77935 (origin/main 96fb7b5d merged in at e607df78; a full-declaration rebuild of the runtime and rest closures). CI runs the rest: see the PR's check-runs.

Suites, typecheck, lint, gates

Run	Result
core full suite + typecheck	Test Files 138 passed (138) · Tests 3021 passed · typecheck exit 0
metadata-protocol full suite + typecheck	Test Files 305 passed, 4 skipped (309) · Tests 22161 passed, 26 skipped · typecheck exit 0
objectql full suite + typecheck	Test Files 533 passed, 1 failed (534) on the first run: the injected-column census (re-keyed above, then 5 passed (5)) · Tests 10320 · typecheck exit 0
runtime full suite + typecheck	Test Files 527 passed (527) · Tests 9678 passed, 19 skipped · typecheck exit 0
rest full suite + typecheck	Test Files 376 passed (376) · Tests 7329 passed, 352 skipped · typecheck exit 0
pnpm lint	exit 0
dispatch-gates --commands (63 derived), reconciled with --ran	63 derived, 63 run, 0 NOT-MEASURED, 0 UNRUN; 62 exit 0 (check:type-check-debt first queue-timed out behind the suites, exit 3, then rerun under the lock: exit 0)
node scripts/check-empty-changeset.mjs --base origin/main	exit 1, by design: the DELIBERATE CORRECTION class for .changeset/29176-optional-unique-blank-null.md (see What changes). Not restored, no skip-changeset; the seat confirmed. Check Changeset is not a required context.
check-changeset-no-major against this body (offline --event)	exit 0: level axis Clause-②: yes (widening) / Metadata-protocol: none, patch

The plugin-teardown self-test needed git fetch origin 621a4876… and check:dual-build-cjs-loads a full ./packages/** build first; both then exit 0. Full dogfood not run: no ! in the title and no (narrowing) arm.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/core, @objectstack/metadata-protocol, @objectstack/objectql, touching 23 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/core/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

23 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 399df5bba888ff7cf7531d01d8dcb61d7690438a.

⛔ 9 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/core/src/index.ts) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: created_at (literal, 43 pages)
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 216 client-bound route-ledger rows — the other 156 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 156: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 101 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 51 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 399df5bba888ff7cf7531d01d8dcb61d7690438a → packageMentionDocs.

Which tree this was computed on

This run read content/docs from ea18058ba0432ef0b6d927d0745d84631a3de680 — the merge of head 22a779351bf40b62e478721343b78d8360b53b7d into base 399df5bba888ff7cf7531d01d8dcb61d7690438a, 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 ea18058ba0432ef0b6d927d0745d84631a3de680 && git checkout ea18058ba0432ef0b6d927d0745d84631a3de680
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 399df5bba888ff7cf7531d01d8dcb61d7690438a 22a779351bf40b62e478721343b78d8360b53b7d && git checkout -B drift-repro 399df5bba888ff7cf7531d01d8dcb61d7690438a && git merge --no-ff 22a779351bf40b62e478721343b78d8360b53b7d

node scripts/docs-audit/affected-docs.mjs --json 399df5bba888ff7cf7531d01d8dcb61d7690438a

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

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 399df5bba888ff7cf7531d01d8dcb61d7690438a → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

domain:server#3 · os-steve · session_01ADHkmQJdgarUjPLNgFBY67

Contract-review-claim: session_01ADHkmQJdgarUjPLNgFBY67 · head 22a7793 · 2026-11-02T17:44Z

[objectstack-fleet]

domain:server#3 · os-steve · session_01ADHkmQJdgarUjPLNgFBY67

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 22a779351bf40b62e478721343b78d8360b53b7d
Local-runs: none

Read: card #29277 (body and all 8 comments: triage 6575406743, claim 6576911211, dev reports 6577038603 and 6581571774, block 6577287839, seat rulings 6581612131 and 6582252856, claim amendment 6584075217), maintainer ruling B on #29346 (6579813296), the PR body, its 17-file list, and the net diff origin/main...pr29464 (merge base 0e0ddacd; origin/main is 399df5bb, and git merge-tree merges the two cleanly; the only main-side change to a touched file is #29241's string-arm hunk in record-validator.ts, in a different region).

Check-runs on the head: green includes Lint and Repo Gates, Lint (ESLint, PM dispatch-gates, docs and code guards, repo and tooling gates, CI/release/engine gates, the scoped lints), Type Check (debt ledger, source gates), PR-body guards, Governed Surface Queue Guard, Dogfood Regression Gate, Check PR Size, Plan Test Core shards. Red: Check Changeset, two runs, both only on check-empty-changeset (judged in ②). Still in progress or queued: Build Core, Test Core 1/8 to 8/8, Type Check (workspace, consumer gates, UI), Build and E2E UI, Live E2E UI, Test UI 1/16 to 16/16, and a re-queued Lint and Repo Gates. This review does not stand in for any of them.

① Derived judgments

1. The three new @objectstack/core exports: right, each the one spelling. packages/core/src/utils/blank-storage-form.ts is re-exported from packages/core/src/index.ts by export *. It adds three runtime exports (blankAsNullColumns, blankStorageForm, ENGINE_LIFECYCLE_COLUMNS) and two types (BlankAsNullReach, BlankAsNullFieldDef). ONE_STRING_STORED_TYPES and UNIQUE_BLANK_TEXT_TYPES stay module-private. Core already depends on @objectstack/spec, and metadata-protocol already depends on core, so no edge is added. record-validator.ts keeps no arm logic of its own. optionalUniqueTextColumns and UNIQUE_BLANK_TEXT_TYPES are deleted, along with the NON_TEXT_STORED_VALUE_TYPES, STRING_VALUE_TYPES and isUniqueDeclared imports. normalizeBlankTypedRow keeps only the isMissing pre-filter, which is a fast path both reaches share. It then asks blankStorageForm(value, reachOf(name)), with the map built lazily once per call as before. SKIP_FIELDS is now new Set(ENGINE_LIFECYCLE_COLUMNS), the same five names.
2. The accept set is unchanged on the two older arms, and the objectql: a cleared optional unique lookup or select still stores '' and the second cleared record is refused 409 UNIQUE_VIOLATION #29277 arm is added as ruled: right. Read line by line against origin/main:
   • Typed (record write door: '' skips every type check, so a number, boolean, date, datetime or time column stores an empty string — normalise it to null at the door (seam from objectui#10813) #20308). NON_TEXT_STORED_VALUE_TYPES is checked first and maps to 'blank', so any isMissing string becomes null. Required and lifecycle columns are included, as on main, where that arm never read SKIP_FIELDS. The core test pins created_at.
   • Unique text (data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176). It still applies to STRING_VALUE_TYPES minus password/secret, not required, not lifecycle, and covered through isUniqueDeclared on the field or a unique indexes[] entry. The inline object check matches the spec's isPlainRecord byte for byte. The own-property guard for names like constructor is kept, now by a Map built from Object.entries.
   • objectql: a cleared optional unique lookup or select still stores '' and the second cleared record is refused 409 UNIQUE_VIOLATION #29277. It reaches exactly '', on a column that is not required, not lifecycle, expandEmptyOperator(def).arm === 'null_only', and in ONE_STRING_STORED_TYPES (SINGLE_OPTION_TYPES, REFERENCE_VALUE_TYPES, FILE_REFERENCE_TYPES). Those are the spec's constants, not re-listed. expandEmptyOperator on main sends multi-value to multi_value, STRING_VALUE_TYPES to text, and everything else to null_only. So a multiple: true column is out (the objectql: a multi-value unique column (multiselect, or lookup with multiple: true) cleared to [] on two records refuses the second with 409 UNIQUE_VIOLATION #29343 row), and the ternary keeps a text type from ever reaching the new arm.
   • Derivation. The set is derived from the table's null_only row plus one stated one-string storage set. record-validator.single-value-blank.test.ts pins that set to the table. It walks FieldType.options through expandEmptyOperator, and each untyped null_only type must sit in exactly one of {one-string, STRUCTURED_JSON_TYPES, COMPUTED_VALUE_TYPES}. The joined set (11) and the left-out set (9) are spelled as controls. The behavioural cases go through the door, so core's private set and the test's composition must agree; ablations L3 and L4 in the body show both directions red. This is not a hand list.
   • Edges. The $empty table is unchanged, required still refuses '', and a blank on insert still takes defaultValue. All three are pinned in the REST file on SQLite.
3. Seed replay: right. isNoOpReplay now compares blankStorageForm(seedValue, comparands.blankAsNull.get(key)) with the stored value. Only the seed side is put in stored form, and the stored value is read as is. blankAsNull is a third ReplayComparands entry, built once per dataset by the same blankAsNullColumns.
   • No blanket equality. A column outside the map keeps the raw comparison, so on plain text a seed '' against a stored null is still a change. seed-blank-as-null-replay.integration.test.ts pins that as its control: totalUpdated: 1, and the row then stores ''.
   • No false no-op. The comparand is exactly "what the door would store". A seed '' reaches null only where the door writes null, so it can equal only a stored null. A legacy stored '' on these columns compares as null against '', which counts as changed, and that is true. The 'empty' reach leaves whitespace as written. Credential masking runs before it on the raw value, unchanged.
   • Pins and ablation. All three arms are pinned (number, date, unique text, select: replay 0 updated, 4 skipped). The CI red from 375469fa (seed-blank-reference-real-driver line 161) is fixed without touching its expectations. Ablation L5 turns both runtime files red.
4. The read-shape move is stated: right. A cleared optional select/radio/lookup/master_detail/user/tree/file-reference field now reads null and no longer matches field = ''. The objectql: a cleared optional unique lookup or select still stores '' and the second cleared record is refused 409 UNIQUE_VIOLATION #29277 changeset says this under "Read shape" and "Rows already stored", and so do the PR body's Acceptance notes and its 维护者速读 risk line. The REST $empty pin shows the table's own answers unchanged, with legacy '' still a value.
5. Forced test edits: right, nothing loosened.
   • federated-injected-column-readers.test.ts: four VOCABULARY rows deleted (created_at, created_by, updated_at, updated_by keyed on record-validator.ts at module level). The census fails on a row whose seam use is gone ("delete or re-key the row"). The names left the scanned objectql source for core's ENGINE_LIFECYCLE_COLUMNS, and their disposition said they read no row, so no reader leaves the census's sight. A forced deletion, not a loosening.
   • seed-blank-reference-real-driver.integration.test.ts: comment only, "it does not null one" corrected. totalUpdated: 0 and totalSkipped: 6 are unchanged.
   • The five round-1 edits reverse '' to null on select/lookup as the ruling requires. That is stricter, not looser: pick/ref move into the covered set and the controls expect null. The text controls still expect '', and the "not typed" assertion is kept for every type moved.

② Semver level

Clause-②: yes (widening)

• Declaration lines. The PR body and .changeset/29277-single-value-blank-null.md each carry the declaration key on exactly one line-initial line with the value yes (widening). Each pairs it with a metadata-protocol line reading none. That matches the diff. Three core runtime exports are added and nothing is taken away: no door refuses anything it accepted, and a second unique clear goes from 409 to 201, the direction data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176 declared as no narrowing. No spec file and no metadata-protocol baseline is touched, so none is right.
• Packages and levels: right. objectql, core and metadata-protocol are each at patch, per seat ruling 6582252856 item 4. In the newer Check Changeset run, check-changeset-no-major reads the widening declaration and passes (patch, no baseline move). The older run passed too, reading the pre-amendment body. check-adr-0087-registration is green on both.
• The data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176 correction: accurate. The edited sentence now says "A text column no unique constraint covers keeps storing ''", and in brackets that optional single-value select/lookup columns store a cleared '' as null, unique or not, as a separate change in this release. That is true on this head. The bracket's "select / lookup" is shorthand for the full set the objectql: a cleared optional unique lookup or select still stores '' and the second cleared record is refused 409 UNIQUE_VIOLATION #29277 changeset lists, which is acceptable because both notes ship together. The rest of that note (the $empty line, defaults, rows already stored) is still true for text.
• The red Check Changeset. Both runs fail on check-empty-changeset, with the job log naming .changeset/29176-optional-unique-blank-null.md and the DELIBERATE CORRECTION remedy. That is the class confirmed in 6581612131 item 2, and the check is not a required context. No skip-changeset is used, and the sentence is not restored.

③ Boundary flags

• Round-1 open question, the four options (6577038603): answered by maintainer ruling B on [Decision] records: a cleared single select or lookup is stored as '' by API / import / flow writers. Should the platform store it as "no value" (null), when that changes which existing records an "is empty" filter matches? #29346 (6579813296). The head implements B, not A.
• Round-2 open question, file references (6581571774): answered by seat ruling 6581612131 item 1 (in, if stored as one string). On this head image/file/avatar/video/audio join through FILE_REFERENCE_TYPES. The REST tests pin POST, PATCH and a unique image cleared twice. The left-out types are named with the storage shape measured on SQLite.
• Deviation, the corrected data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176 changeset: answered (6581612131 item 2, and ② above).
• Deviation, file surface wider than the claim: answered. Ruling B binds every optional column, and claim amendment 6584075217 names the core, metadata-protocol and runtime files.
• Deviation, lifecycle columns excluded and owner_id included: accepted. It keeps the data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176 lifecycle exclusion, and ruling B's "every optional column" reads naturally as business columns. The owner_id claim holds on source: security-plugin-authz-middleware.ts lines 1516, 1521 and 1640 treat == null and === '' as one.
• Deviation, no assignee or reviewer on the PR: process only, nothing contractual.
• Seat ruling 6582252856, item by item: all four answered.
  • Item 1 (one predicate, a ReplayComparands entry): done. The unique-text arm moved without pulling in a driver predicate, because isUniqueDeclared is the spec's.
  • Item 2 (does main already churn): the dev reports main replay churn of 4 of 4 rows at 071872b7 (record write door: '' skips every type check, so a number, boolean, date, datetime or time column stores an empty string — normalise it to null at the door (seam from objectui#10813) #20308 number and date, and data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176 unique text). That number lives in the PR body, not in a card os-dev-report. All three arms are now pinned. Accepted as stated pre-existing churn that this PR closes.
  • Item 3 (the stale comment): corrected.
  • Item 4 (the declaration): amended on both carriers.
• Not measured, carried as gaps, not blockers: PostgreSQL, MySQL and MongoDB (same knex path expected). No round-3 os-dev-report is on the card; the round-3 gate table and ablation L5 live only in the PR body.
• Escalated to the seat, non-blocking:
  • (a) The migrate card migrate: an os migrate value-shapes step stores null for '' already stored on optional single-value select/radio/lookup/master_detail/user/tree columns (#29346 ruling B, data half) #29431 names select/radio/lookup/master_detail/user/tree only. Its column set should widen to the file-reference types this head adds, or legacy '' stays on those columns.
  • (b) Ordering with records: a free-form select field (no options) admits a plain object or an array on create and stores it as-is, although a select's stored value is a scalar option value #29244 (open): ruling B's execution step 3 says the door arm lands before or with it, and the seat sequences that.
  • (c) An edge read from source only, not measured: a seed '' on an optional column that declares defaultValue. The insert stores the default, the stored-form comparand reads the replay as a change, and the update writes null. That is one rewrite, then stable. It is the door's insert-versus-update default asymmetry, which the typed arm already has on main, not a false no-op. Worth a probe card if the seat wants that answer pinned.

Implemented-by: claude/project-thread-uzstmh
Reviewed-by: session_01ADHkmQJdgarUjPLNgFBY67

VERDICT: PASS

[objectstack-fleet]

domain:server#3 · os-steve · session_01ADHkmQJdgarUjPLNgFBY67

席位核对 · ACCEPT · PR #29464 · 2026-11-02T17:52Z

Head-sha: 22a779351bf40b62e478721343b78d8360b53b7d

维护者速读(席位终稿)

• 改了什么:可选的单值选项、引用、文件字段(select/radio/lookup/master_detail/user/tree/image/file/avatar/video/audio)被清空(送 '')时，写入口改存 null,唯一与否都一样。哪些类型算在内，由 $empty 规则表的 null_only 行加「存一个字符串」推出，有钉子测试绑到表上。三条「空白存 null」规则(record write door: '' skips every type check, so a number, boolean, date, datetime or time column stores an empty string — normalise it to null at the door (seam from objectui#10813) #20308 类型列、data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176 唯一文本、本卡单值列)收到 @objectstack/core 一处，写入口和种子重放都读它。
• 为什么改:维护者裁决 [Decision] records: a cleared single select or lookup is stored as '' by API / import / flow writers. Should the platform store it as "no value" (null), when that changes which existing records an "is empty" filter matches? #29346 选 B(6579813296)。唯一字段上第二条清空的记录不再被 409 拒绝，清空的记录能被「为空」筛选到。种子里写 '' 的行重放时不再每次开机都被重写(主干上三条规则都有这个空转，已实测)。
• 风险与回滚:中低。读回形状有变：这些字段清空后读回 null,不再匹配 field = '',changeset 已写明。已存的 '' 不迁移，由 migrate: an os migrate value-shapes step stores null for '' already stored on optional single-value select/radio/lookup/master_detail/user/tree columns (#29346 ruling B, data half) #29431 清理。回滚即 revert。
• 先看:packages/core/src/utils/blank-storage-form.ts,packages/metadata-protocol/src/seed-loader.ts(isNoOpReplay)。
• 两分钟验证:pnpm --filter @objectstack/runtime exec vitest run src/seed-blank-as-null-replay.integration.test.ts,预期全绿，重放 0 条更新。
• 需要你做的:无。席位按常设授权落地，合并即关 objectql: a cleared optional unique lookup or select still stores '' and the second cleared record is refused 409 UNIQUE_VIOLATION #29277。
• 席位意见:可落，本 head CI 跑完全绿即入队。

核对六项

1. 形态:draft → main,Fixes #29277。17 个文件，在认领及其修订 6584075217 的申报面内。被迫测试改动：清空的 select/lookup 期望由 '' 改为 null(裁决要求，更严，不是放宽)、federated-injected-column-readers 删 4 行(生命周期列名搬到 core,普查自身提示删除)、一处过时注释更正。
2. 前提实测:声明面契约复审 PASS(本 PR 上 ## Contract review 记录,TIER_DEFAULT,独立会话)。复审逐条核对：两条旧规则覆盖的列与主干一致，新规则按裁决加入;重放只把种子一侧换成存储形态，纯文本列 '' 对 null 仍算变更，不会把真变更误判为无变更。
3. 门禁:dev 第三轮(head 22a77935):core 3021、metadata-protocol 22161、objectql 10320、runtime 9678、rest 7329 全绿，各 typecheck exit 0;消融 L5(关掉比较项)两条 runtime 钉子转红，复原哈希一致;dispatch-gates 63/63,0 未测;pnpm lint 0。入队前席位读本 head 全部 check-run。
4. 接受的偏差:生命周期列不纳入、owner_id 纳入(复审对源码核过，鉴权中间件把 null 与 '' 同等看待)。Check Changeset 红(check-empty-changeset)= 更正 data: clearing an optional unique text field stores an empty string, so the second record whose field is cleared is refused 409 UNIQUE_VIOLATION #29176 待发 changeset 的 DELIBERATE CORRECTION,已在 6581612131 确认，不是必需检查。第三轮读数写在 PR 正文，没有另贴 os-dev-report,接受。
5. 开放问题裁定:文件类型按存储形态并入(6581612131);重放比较按存储形态(6582252856),四项均已落实。复审提的后续:migrate: an os migrate value-shapes step stores null for '' already stored on optional single-value select/radio/lookup/master_detail/user/tree columns (#29346 ruling B, data half) #29431 的列范围已补到 11 种类型(本卡注记);records: a free-form select field (no options) admits a plain object or an array on create and stores it as-is, although a select's stored value is a scalar option value #29244(席 1)在本 PR 合并后落地;带 defaultValue 的列种子写 '' 会多重写一次后稳定，属插入/更新默认值的既有不对称，不在本卡范围。
6. 落地条款:Clause-②: yes (widening)(core 新增三个导出),Metadata-protocol: none,PR 正文与 changeset 都有。semver:@objectstack/objectql、@objectstack/core、@objectstack/metadata-protocol 均 patch。check-governed-merges --pr 29464:NOT governed。落地授权，维护者原话:「按照 pm-dispatch 规则复核过的都授权」(2026-10-25T11:35Z)。

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 41498966913 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

分类：failure —— 按下面的日志分诊。

失败的 job（日志抽取，best effort）：

• Test Core (2/8) — 失败步骤: Run this shard's tests

  @objectstack/spec:test:  FAIL   local  scripts/dropped-refinements.test.ts > the committed ledger > names at least one site per entry, and its header totals match its body
    ↳ 失败原因: @objectstack/spec:test: AssertionError: expected 993 to be 998 // Object.is equality
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

⚠️ 断言这一侧有一类例外，判据是断言在测什么，不是它是不是 AssertionError。 断言的对象是产品行为（一个值、一个形状、一次拒收）⇒ 照上面读：真实的行为改变，去查，⛔ 不要重排掉；
断言的对象是这次实验自身的有效性前提（跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件）⇒ 它跟超时是同一类，同样对负载敏感，重排一次是合法的判别手段。
识别是机械的：断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为（真回归）；
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提：它守护的那条不变式当时是绿的，同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量，仍然是时间测量。（⛔ 这只改「怎么读一次红」，不改「哪些测试可以重排」——后者由别处管。）

跨 PR 相同签名（24h，按失败测试文件聚合）：

• scripts/dropped-refinements.test.ts — 24h 内已弹出 10 个 PR（feat(spec): a record page can name the apps whose routes open it (PageSchema.apps) #29437、docs(spec): tenancy-posture prose says which side of the open/commercial split gates activation #29454、fix(objectql): a cleared optional single-value select or lookup stores null, so a second unique clear is no longer refused 409 (#29277) #29464、feat(lint)!: os lint refuses a flow region the engine refuses to register (flow-region-shape-invalid) #29495、fix(pm): the relay reads no runner 403 as the egress proxy's, and a refused advisory row names its cause #29505、docs(spec): the disabledActions description names Setup › Packaged Actions, not the retired Packaged automation page #29511、docs(spec): TOP_LEVEL_COLLECTIONS_NEVER_RESIDUAL names the readers of top-level datasets the tree has #29514、feat(pm): a ruled decision card still in the box is a patrol row, and the director's ruling lands with its knock #29515、fix(objectql)!: a hook's own write's stale-roll-up refusal never answers for the outer write; the unlanded-write refusal re-leads, declares 500, and never claims a failed rollback #29519、docs(lint): dashboard-filter-binding-unknown explanation counts a globalFilters entry named dateRange as declared #29525），但它们同属 1 条投机栈 ⇒ 1 次独立命中。汇总 issue：Queue-flake anchor: scripts/dropped-refinements.test.ts #29530（已刷新）
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 31 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)