[objectstack-fleet]

Fixes #20963
Clause-②: no

The hint on a driver's NOT NULL refusal no longer asserts that the schema has drifted. It first says the column requires a value (provide it, or declare the field required), then names drift in one sentence that is conditional on the object declaring neither required nor storage: { notNull: true }. Prose only, in the one branch of the driver-string classifier in packages/rest/src/error-response.ts; the branch's comment gets the same correction (ADR-0113 D1 / D2). The status, code, error, fields and object are unchanged, no key is added, no registry is read, and the import row is untouched (PR #20956 pins its key set).

Repro (hint, same answer on both doors)

Object proj_notnull_hint_20963 declares must: { type: 'text', storage: { notNull: true } } with no required. POST /api/v1/data/:object with must omitted, and PATCH /api/v1/data/:object/:id writing must: null, over a real ObjectQL + SQLite :memory: (the pin's harness). Both answer 400 VALIDATION_FAILED, error: "must is required", fields: [{ field: 'must', code: 'required', message: 'must is required' }], object.

• Before (origin/main 05be352, the pin run red on it): "If 'must' is optional in your object metadata, the database column is still NOT NULL — the physical schema has drifted from metadata. Run 'os migrate' to reconcile (or reset the dev database)."
• After: "The database column for 'must' requires a value: provide it, or declare the field required in the object metadata. If the object declares neither required nor storage: { notNull: true } for 'must', the physical schema has drifted from metadata instead: run 'os migrate' to reconcile (or reset the dev database)."

What is pinned

packages/rest/src/data-not-null-hint-20963.test.ts, three tests, by kind and not by wording:

• the fixture is the ADR-0113 posture: the engine's own insert is refused by the database for the missing value, and the field declares no required;
• the control, on both doors: status 400, code, error, the required finding and object as before, and the body's key set is exactly code, error, fields, hint, object;
• the hint: its first sentence says the column requires a value, tells the caller to provide it or declare required, and names no drift; drift appears in exactly one later sentence, which begins with a condition naming storage and notNull; the update door answers the create door's hint byte for byte.

Not pinned: telling the two cases apart. That needs a registry read, a wider change than this card asks.

Verification (head 5920691)

• Red on the old text, green on the new. The pin on origin/main before the edit: 2 failed, 1 passed (the fixture test). With the fix: 3 passed.
• Ablation. With the fix committed (cf4bd61, before the rebase onto 7fa67da), scripts/ablation-replace.mjs put the old hint text back (anchor hit 1 time, blob 0b1a39350 to 3197ecfe1; the mutated file resolves by relative source import from the test, so no rebuild applies) and the pin went red: 2 failed, 1 passed (the control and fixture held; the hint tests failed). The restore proved blob == HEAD and an empty git diff HEAD. Direction: turned red, the usual one.
• Package. pnpm --filter @objectstack/rest typecheck exit 0 (tsc --noEmit, and check:test-typecheck over tsconfig.test.json: 0 files, 0 errors; the new test is in that program). vitest run --project local on @objectstack/rest: 250 files passed, 4964 tests passed, 114 skipped. The ten files that read this mapper, this file included, were also run alone: 10 passed, 567 tests.
• Gates. dispatch-gates --commands derived 61 commands at this head; all 61 were run with exit codes recorded and --ran reconciled: 61 derived, 59 run, 2 NOT MEASURED, 0 unrun. The two NOT MEASURED exited 3, PREREQUISITE NOT MET: check:dual-build-cjs-loads and check:type-check-debt read every package's built output and need the full-repo build, which was not run on the shared box; Build Core and Lint & Repo Gates cover them in CI. The diff adds no package, no export and no ledger entry, and the package's own test-layer typecheck holds 0 debt.
• Lint. pnpm lint (eslint over the whole repo, --no-inline-config) exit 0 at this head, no narrowing.

Acceptance notes

Noted, not filed (no defect, polish only):

• packages/rest/src/rest.test.ts (the test "maps SQLite NOT NULL constraint → 400 VALIDATION_FAILED with required field", about :2514) keeps a comment that says reaching this branch means the metadata did not require the field, so it is physical-schema drift. Its assertions still hold (the hint keeps os migrate and "drifted from metadata" in the conditional sentence), so only the comment restates the corrected reading. It sits outside this claim's file surface, so it is untouched.
• packages/rest/src/error-response.ts :176 lists "not-null drift" as a label for the branch in a docblock about a different branch. A name, not a claim about the hint.
• Branch note: rebased once onto origin/main 7fa67da (only scripts/pm/fleet-write/ moved) with --force-with-lease, before any PR existed, so the dispatch-gates families were derived from a current tree.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 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; 97 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 — 15 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 8d329f02eeb571170bba3b275df3c2fc3cb749b3 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 928a24d445a78dbd5765cef7490bc86c00490d97 — the merge of head 592069136c016aec922b78fd9b977c80f870b062 into base 8d329f02eeb571170bba3b275df3c2fc3cb749b3, 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 928a24d445a78dbd5765cef7490bc86c00490d97 && git checkout 928a24d445a78dbd5765cef7490bc86c00490d97
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 8d329f02eeb571170bba3b275df3c2fc3cb749b3 592069136c016aec922b78fd9b977c80f870b062 && git checkout -B drift-repro 8d329f02eeb571170bba3b275df3c2fc3cb749b3 && git merge --no-ff 592069136c016aec922b78fd9b977c80f870b062

node scripts/docs-audit/affected-docs.mjs --json 8d329f02eeb571170bba3b275df3c2fc3cb749b3

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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 592069136c016aec922b78fd9b977c80f870b062
Local-runs: none

Inputs read: card #20963 body and its three comments (governing: triage's direction 5921865209, the seat's claim 5922265892, the newest os-dev-report 5922713698); the seat's serial note 5922376322 on #20919 and, since it answers it, the cross-lane note 5922173894 on #6024 that names the move; ADR-0113 (D1, D2, D3, D5, Q1) at origin/main; PR #20956's record 5921191584, ③ item 2; PR #21001 body, file list (3 files) and the net diff 7fa67dada3..592069136c (+201/−7, one commit); the check-runs on the head, polled to convergence. Source premises (error-response.ts at the head and at origin/main 315888d660, import-runner.ts, import-row-schema-drift-20701.test.ts, rest.test.ts, rest-server.ts, record-validator.ts, packages/rest/package.json, the repo-wide git grep for the old hint text and for notNull reads) were read by git show / git grep; nothing was built, run, checked out or re-run.

① Derived judgments

(a) The not-null branch of mapDataError (classifyDataError, error-response.ts:1813-1845 at the head).

• Leads with the remedy, drift as a condition: the hint is two sentences. First: "The database column for 'FIELD' requires a value: provide it, or declare the field required in the object metadata." Second: "If the object declares neither required nor storage: { notNull: true } for 'FIELD', the physical schema has drifted from metadata instead: run 'os migrate' to reconcile (or reset the dev database)." Triage's direction (5921865209) and the card's shape are met literally.
• True in both cases. Declared storage.notNull without required: the first sentence is true (the column requires a value by declaration; D2 makes that the author's own DDL, D3 says a NOT NULL column over storage.notNull: true is no drift), and the second is a conditional whose condition is false, so it asserts nothing about this column. Genuinely drifted (column NOT NULL, metadata declares neither): the first sentence is true (the database refused; either remedy stops the refusal reaching the driver), and the second is true (D3/D5: a column stricter than its declaration is drift, needs_confirm, and os migrate is the door that reports and reconciles it; the remedy words are the old hint's own and the same sentence the unknown-column branch above it uses). The branch's reachable inputs partition into those two cases: the third cell, required: true over a NOT NULL column (D5's silent pre-17 case), cannot reach the branch, since record-validator.ts:908 refuses a missing or null required value before any driver runs (D1). One residue outside the card's two cases, pre-existing and unchanged in kind: Q1's engine-populated storage.notNull-only column (an audit or tenant column such as organization_id, the very fixture rest.test.ts:2505 uses) reaches this branch when the engine failed to populate it, and "provide it" is then not the caller's remedy; the old hint was no better there, and it is not a claim of this card. Not a verdict mover.
• No implied registry read or server check: the drift sentence is addressed to the reader as a condition to evaluate against the declaration ("If the object declares neither..."); the branch asserts nothing about what the object declares, which matches the branch's actual inputs (error, object). ⛔ No registry read was added (the diff touches no import and no lookup).
• Byte-unchanged envelope: the hunk removes five comment lines and the two old hint lines only; status: 400, error, code: 'VALIDATION_FAILED', fields: [{ field, code: 'required', message }] and ...(object ? { object } : {}) are context lines, and no key is added. The three dialect regexes above the branch are untouched. Verified on the diff, and pinned by the exact key set (below).
• The branch comment is accurate against ADR-0113: "judges required only; nothing before the driver reads storage.notNull" holds at origin/main (the only non-test notNull reads outside driver-sql and spec are cli/generate.ts DDL emission, generated form labels, a plugin-sharing comment and rest's own two regex sites; record-validator.ts reads required and requiredWhen); "D1 / D2 keep the write contract and the column constraint apart on purpose" is D2 plus Q1's orthogonality argument; "lands here on a healthy schema, and os migrate changes nothing for it" is D3; "Drift (Schema sync is additive-only: non-additive metadata changes (required→optional, type, drop, rename) silently diverge from existing DBs; need drift detection + os migrate #2186) is the other way in: the column is NOT NULL and the metadata declares neither" is D3/D5. The retained #2186 is in a code comment, not a runtime string, and was there before; the hint carries no tracker number.

(b) The pin packages/rest/src/data-not-null-hint-20963.test.ts (three tests).

• Real door, real driver: RestServer.registerRoutes() (rest-server.ts:4357) with the handlers taken from getRoutes() (:13766) and invoked for POST /api/v1/data/:object and PATCH /api/v1/data/:object/:id, over a real ObjectQL + SqlDriver (better-sqlite3 :memory:, syncSchemas) + ObjectStackProtocolImplementation; the same harness as import-row-schema-drift-20701.test.ts (169 rest tests use getRoutes()), and every import is a declared devDependency of @objectstack/rest. No cross-package file read, no clocked window.
• The fixture test proves the ADR-0113 posture rather than assuming it: must carries storage.notNull and no required, and engine.insert without it rejects on /not null/i, so the refusal is the database's, after the validator.
• Asserts the correction by kind: the first sentence matches requires a value, provide, contains the literal backticked required and does not match drift|os migrate; exactly one sentence matches drift|os migrate, it begins with If, names storage, notNull and os migrate, and is not the first; the PATCH door's hint equals the POST door's byte for byte.
• Holds the control: status 400, code, error, the exact required finding, object, and the body's key set exactly code, error, fields, hint, object on both doors.
• Would red on the old hint, derived from the text rather than taken from the report: the old string splits on the pin's sentence rule into "If 'must' is optional ... has drifted from metadata." and "Run 'os migrate' ... database).", so sentences[0] fails requires a value and the drift-sentence count is 2, not 1; both hint tests red, the fixture test green, which is the 2-failed / 1-passed shape the dev's ablation reports (scripts/ablation-replace.mjs exists at origin/main). The pin's one fragility is cosmetic: its sentence splitter is a period followed by whitespace, so an abbreviation added to the hint later would need the pin adjusted; not a defect.

(c) Confined to the claim's surface. Three paths. error-response.ts moves only inside the not-null branch; the unknown-column branch, the unique-violation arm, the sandbox doors and the terminals are untouched. import-runner.ts is not in the diff, and the import row cannot inherit the change: adoptDoorVerdict copies only code, field and the sentence, and the ROW_KEYS pin (import-row-schema-drift-20701.test.ts:186) holds the row's key set without hint, so PR #20956's key set stands. Grep of origin/main for the old text ("optional in your object metadata", "is still NOT NULL", "has drifted from metadata. Run"): only error-response.ts:1829-1831, the lines this PR replaces. Every other consumer of the hint: rest.test.ts:2518-2519 asserts /os migrate/ and /drifted from metadata/, both of which the new second sentence still satisfies, so it stays green; rest-unclassified-fault-status.test.ts:250 asserts status only. No page under content/docs, docs/ or skills/ quotes the hint (cli.mdx:764 and cli/migrate/plan.ts:67 use "drifted from metadata" for os migrate plan; .changeset/20701-import-row-schema-drift-door-answer.md:13 quotes the unknown-column sentence). Nothing reds; one comment goes stale (③).

(d) The changeset 20963-not-null-hint-declared-column.md (@objectstack/rest patch) is accurate. Its quoted "now reads" text is the code's string with 'FIELD' for the interpolation; "the first sentence holds for every NOT NULL refusal" holds for the two cases the card names (with the engine-populated residue in (a)); the two doors it names are the two the pin drives; "status, code, error, fields and object unchanged, no key added" is pinned exact; "the import row is untouched: it does not carry a hint" is the ROW_KEYS pin; "nothing reads the field map" is the diff. Clause-②: no is a bare line at the start of a line, the spelling check-changeset-no-major.mjs reads. The title carries the card number in the form every changeset here uses. It claims nothing undelivered. Check Changeset is success.

② Semver level

Clause-②: no with patch is right. No packages/spec/src/** in the file list; no route, parameter, key or code is added or removed; the envelope's key set is unchanged (pinned exact); hint is guidance prose, never a declared vocabulary (ADR-0112's ledger governs code, which does not move); no request moves between accepted and refused. A bug fix in a released package takes patch, never none (AGENTS.md Post-Task Checklist 3), and the note needs no ADR-0087 marker. The claim's own reading (5922265892, Clause-②: no) agrees.

③ Boundary flags

Dev deviations, each answered:

1. One rebase onto 7fa67dada3 and a push with --force-with-lease, before any PR existed. AGENTS.md Multi-agent discipline 3's five conditions, checked: ① the branch is claude/issue-20963-notnull-hint; ② the claim names the worktree objectstack-issue-20963 that created it; ③ the author and committer set of 7fa67dada3..592069136c is the one agent identity, one commit; ④ the PR was created at 01:10:49Z, after the push, so it carried no reviewer or approval; ⑤ the lease was spelled branch:cf4bd61490... with the sha. The merge base of the head with origin/main is 7fa67dada3, consistent with the stated target. Accepted.
2. check:dual-build-cjs-loads and check:type-check-debt NOT MEASURED (prerequisite not met on the shared box): Build Core and Type Check · debt ledger are success on the head. Accepted.
3. Local builds limited to the rest closure: CI builds the repo. Accepted.
4. The pin is a new file, not an edit of rest.test.ts: that is the claim's "one pin under packages/rest/src/", and it leaves the existing test and its comment outside the surface by design. Accepted.
5. Commit trailers: verified on 592069136c, the model-free pair (Claude-Session: https://claude.ai/code/session_01VvcEokUG1tvVxkceYfR5XB and the Co-authored-by: Claude line); no model identifier in the title, body, changeset, test or code. Accepted.
6. The filing seat, the claim and the run share one session id, and the newest Claim: (5922265892) names the PR's branch; The card this PR closes must claim this branch is success. Accepted; this record is signed by that same session, the shared-account blind spot AGENTS.md names, not a verdict matter.

Dev out_of_scope_findings, each answered:

1. rest.test.ts:2514-2516: the comment above the SQLite NOT NULL test still says reaching the branch means the metadata did not require the field, so it is drift. Its assertions (/os migrate/, /drifted from metadata/) hold against the new second sentence, so nothing reds, and the comment is now the reading the branch retired. Triage said "prose only, in that one file" and the claim's surface is the branch plus one new pin, so touching rest.test.ts would have breached the claim; "carrier: none" (an acceptance note, Prime Directive 10) is right. For the seat: the next PR that edits that test block, or connector sync, stage ② of #20281: an executor in service-automation pulls a mapping whose connectorSource names a rest/openapi connector and writes through the import runner's upsert-by-match-key #20919's move (which relocates the classification this test reads), restates the comment and, ideally, pins the two sentences of the hint the way this pin does.
2. error-response.ts:176: "not-null drift" as a label in UNCLASSIFIED_FAULT's docblock list of the 4xx branches above it. A name, in another branch's docblock, outside the claimed branch; "carrier: none" is right. Not a verdict mover.

Serial interaction with #20919: the cross-lane note 5922173894 (00:24Z) states that #20919's build moves the classification half of error-response.ts to types with rest re-exporting every moved name, as one PR sent no earlier than an hour after it; the seat's serial note 5922376322 (00:41Z) declares the serialization (whichever lands second carries or re-applies the corrected comment and hint). At convergence, #20919 has no closing PR and no issue-20919 remote head, and No other open PR may claim the same single-writer path is success, so this PR has no live conflict. If the build lands first, the rebase of this PR re-applies the two strings at the moved location; the pin imports RestServer from ./rest-server, not mapDataError, so it is unaffected by the move. The landing seat reads origin/main for the move before queueing. Not a verdict mover.

File list: three paths, none a governed surface (Governed Surface Queue Guard success); head repo is the base repo; the PR is a draft, per the dispatch; first line Fixes #20963 and the card lists #21001 as its closing PR; +201/−7, one commit, size/m. The Docs Drift Check comment on the PR lists nothing (one derived anchor, no page names it); the grep in ①(c) covers the hand re-read it prescribes.

Check-runs on 592069136c (converged 2026-10-01T01:24:02Z; 34 runs, collapsed to latest-per-name, 34 names): 31 success, 3 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke (opt-in)), 0 failure, 0 in progress. The seven required contexts are all success: Lint & Repo Gates, TypeScript Type Check (with Type Check · consumer gates, debt ledger, source gates, workspace), Test Core (rollup and shards 1-6), Dogfood Regression Gate (rollup and 1-3), Build Core, Temporal Conformance (live PG + MySQL), Governed Surface Queue Guard. Test Core green on the head is also the first run of the new pin outside the dev's box.

Implemented-by: claude/issue-20963-notnull-hint
Reviewed-by: session_01VvcEokUG1tvVxkceYfR5XB

VERDICT: PASS

---

Generated by Claude Code