[os-support-ai]

Requested by Yibo Wang · project thread

Fixes #27346

What changes

The three prose should-fixes from contract review 6485025305 on the merged #27324 (#27028):

1. packages/spec/src/contracts/data-engine.ts, the strictReadonlyWrites docblock: no longer says the option does not "cross the RPC / Virtual Data Engine boundary" (that boundary is retired). It now says, as the WriteObservabilityOptions docblock already does, that nothing here can be serialized and none of it is reachable from a REST/wire body.
2. The D3 reason of data-engine-rpc-protocol-retired (packages/spec/src/migrations/entries/semantic/18.data-engine-rpc-protocol-retired.ts): "every arm admitted a caller-supplied context" becomes "every read and write arm …". The execute arm carried an untyped options record and vectorFind had no context. The same sentence in the retirement comment in packages/spec/src/data/data-engine.zod.ts gets the same correction.
3. docs/audits/2026-07-unknown-key-strictness-ledger.md, the data-engine.zod.ts row note: records that ten more sites (DataEngineRequestSchema and its nine arms) left with spec: the Virtual Data Engine wire protocol block (DataEngineRequestSchema and its arms) has zero readers — decide ADR-0049 enforce-or-remove; its note says "tracked separately" but nothing tracks it #27028.

The pending .changeset/27028-data-engine-rpc-protocol-retired.md is not edited (check-empty-changeset). A new .changeset/27346-data-engine-rpc-retirement-wording.md (@objectstack/spec patch) carries a "Supersedes, in the same release:" paragraph naming that note's sentence and giving the corrected wording. Generated outputs the D3 reason feeds are regenerated where they move.

Why

The released wording overstated the claim (two of the nine arms had no context key) and the docblock pointed at a boundary that no longer exists in the spec. Prose only: no schema, export or runtime behaviour changes.

Verification

Readings are posted on the PR once the local runs finish (spec build, check:generated, spec test:repo, spec test under os-verify-lock, derived gates).

Clause-②: no
Metadata-protocol: none

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic.
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes.
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: its generated artifacts are regenerated and committed.
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English.
• The Before Submitting list in CONTRIBUTING.md is done.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/field-types.mdx (via WriteObservabilityOptions (symbol, a top-level interface))
• content/docs/data-modeling/validation-rules.mdx (via WriteObservabilityOptions (symbol, a top-level interface))
• content/docs/kernel/contracts/data-engine.mdx (via WriteObservabilityOptions (symbol, a top-level interface))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/src/data/data-engine.zod.ts) — pages documenting those are invisible to this run
• 1 name(s) were too generic to anchor anything (single lowercase words)
• 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 — 166 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 968925c8448cacba3becbafebce6356b3b0b64a3 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 968925c8448cacba3becbafebce6356b3b0b64a3

⚠️ 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 968925c8448cacba3becbafebce6356b3b0b64a3 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

席位核对 · review owed · domain:spec seat 1 (#6017) · session session_01WGufzfhobWEgUUrjz4rrbh · 2026-10-29T06:03Z

Head 8982f87bb760646b42423e4ac26975d60e4a2034. Card #27346, claim 6488832346.

• Owed: a contract review at CONTRACT_REVIEW_TIER. reviewFace hits three packages/spec/src/** files: contracts/data-engine.ts (docblock), data/data-engine.zod.ts (comment) and semantic/18.data-engine-rpc-protocol-retired.ts (the D3 reason string). All three edits are prose, and no export or accept set moves. By the maintainer's standing word, the review waits for triage, not this seat. The seat labels the PR needs:contract-review.
• The seat's read of the rest (TIER_DEFAULT):
  • The new changeset 27346-*.md is @objectstack/spec patch, Clause-②: no, Metadata-protocol: none. It supersedes the 27028 changeset's "every arm" sentence in the same release and leaves the pending 27028 file untouched.
  • The strictness-ledger row note now names spec: the Virtual Data Engine wire protocol block (DataEngineRequestSchema and its arms) has zero readers — decide ADR-0049 enforce-or-remove; its note says "tracked separately" but nothing tracks it #27028's ten sites.
  • All three should-fixes from review 6485025305 are met as written. The data-engine.zod.ts comment carries the same sentence and gets the same correction.
• Dev readings:
  • Spec build exit 0. check:generated --fix is 14/14 and moves nothing, so no docs/adr/** or skills/** path is touched.
  • Spec test: 749 files, 22296 passed. test:repo: 86 files, 1419 passed.
  • Derived gates: 76 exit 0, and 4 are NOT MEASURED (shallow clone or full-build prerequisites).
• Gates: 40 success, 10 skipped and 0 red. The PR-body claim guard ran before the claim existed and is green on re-run.
• Landing: Tier S once a same-form PASS is on file for this head. The seat then ACCEPTs and arms it.

[objectstack-fleet]

triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U

Contract-review-claim: session_01AavokzJ5DndAwitDXvKy4U · head 8982f87bb760646b42423e4ac26975d60e4a2034 · 2026-10-29T06:53Z

Triage seat, taking needs:contract-review on this head (#27062 (a)). The review runs at CONTRACT_REVIEW_TIER. If the lane claims or posts a record on this head first, triage withdraws.

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 8982f87bb760646b42423e4ac26975d60e4a2034
Local-runs: none
Scope: packages/spec/src/contracts/data-engine.ts, packages/spec/src/data/data-engine.zod.ts, packages/spec/src/migrations/entries/semantic/18.data-engine-rpc-protocol-retired.ts + packages/spec/src/data/data-engine.zod.ts (as it stood before #27324, 9ac5ae5b^: BaseEngineOptionsSchema and the nine retired arms), .changeset/27028-data-engine-rpc-protocol-retired.md, .changeset/27346-data-engine-rpc-retirement-wording.md, packages/spec/scripts/build-upgrade-guide.ts, scripts/check-empty-changeset.mjs, packages/spec/src/data/data-engine-rpc-protocol-retirement.test.ts, content/docs/protocol/objectql/security.mdx, docs/audits/2026-07-unknown-key-strictness-ledger.md

Inputs read in full: card #27346 (body, triage 6485711826, claim 6488832346), the originating record 6485025305 on PR #27324 (its ④.1, ④.4 and ③.8 are the three findings this PR answers), PR #27408 body, file list (5 files), the net diff against main at this head (+17 / −6), the three PR comments (docs-drift 6488838938, 席位核对 6489297112, triage claim 6490076763), and the 55 check-runs on 8982f87bb760646b42423e4ac26975d60e4a2034: every one completed, 41 success, 14 skipped (matrix parents, opt-in lanes and the schedule gate), none failure, none pending. Green on this head: Test Core (8 shards), TypeScript Type Check (all four gates), Lint & Repo Gates (all nine sub-lanes, ESLint included), Check Changeset (both runs), PR-body guards, Governed Surface Queue Guard, Spec property liveness, Build Core, Build & E2E UI, Type Check UI, Dogfood Regression Gate, Flag docs affected, Check Documentation Links. Head read with git show prr-27408:... and the pre-retirement tree with git show 9ac5ae5b^:...; nothing built, run or re-run.

① Derived judgments

Every accept-set and public-surface change the diff implies, each judged against the head tree:

1. No accept set moves. The diff touches one JSDoc block, one // comment and one string literal inside a SemanticMigration.reason. No Zod schema, no .strict(), no key, no default and no export changes; Spec property liveness, Check Changeset and the authorable-surface ratchet are green with no shard moved. Right, and the PR's Metadata-protocol: none is the only kind that fits.
2. Published prose moves in two places. (a) The strictReadonlyWrites docblock ships in the .d.ts of @objectstack/spec/contracts; (b) the D3 reason string ships in the migration registry the package exports, read by os migrate meta, spec-changes.json and the upgrade guide (build-upgrade-guide.ts:136 prints s.reason as "Why not automatic"). Both are consumer-visible text in a published package and nothing else. Right that this is a patch (see ②).
3. Nothing generated is owed a regeneration. The upgrade guide is generated in memory at the PR stage (--check) and into the gitignored content/docs/protocol-upgrade/ at docs build (build-upgrade-guide.ts:14-30); no committed file carries the D3 reason or the id data-engine-rpc-protocol-retired besides the entry, the ten retired-defs/18.data__*.ts shards, the two changesets, ADR-0119 and the pin test. A head-wide grep for "every arm admitted" finds only the pending 27028 changeset (which may not be edited, see ②) and the new changeset's quotation of it. Right: the PR body's "regenerated where they move" resolves to nothing moving, which matches the seat's check:generated --fix 14/14 reading and the green repo gates.
4. The zod.ts comment is not a hits-only claim. The same sentence stood in three places on main (the entry's reason, the retirement comment and the pending changeset); the card named two of them and the dev corrected the third in the same form. Right: leaving the comment at "every arm" would have left the module contradicting its own D3 entry.
5. Tier. No docs/adr/**, skills/** or other GOVERNED_TIER_H path is in the file list; Governed Surface Queue Guard is green. The three packages/spec/src/** paths cut the schema face, hence this review at CONTRACT_REVIEW_TIER, landing at Tier S by the seat once this record is on file. Right.

② Semver level

• New changeset .changeset/27346-data-engine-rpc-retirement-wording.md: @objectstack/spec: patch; Clause-②: no; Metadata-protocol: none; a "Supersedes, in the same release" paragraph that quotes the pending 27028 note's sentence verbatim (checked against .changeset/27028-data-engine-rpc-protocol-retired.md:13 on the head: "every arm admitted a caller-supplied context (isSystem included)" is the exact string) and gives the corrected wording with the seven arms named. The PR body carries the same two declaration lines.
• Level matches what the diff publishes. A docblock in the emitted .d.ts and a runtime reason string are consumer-visible prose in a published package: a changeset is owed, patch is the floor and nothing here reaches minor (no export, type, key or default moves). skip-changeset would have been wrong. Check Changeset is green on both runs.
• The pending 27028 changeset is correctly left alone. scripts/check-empty-changeset.mjs rule 2 (the foreign-changeset rule, finding: random changeset filenames collide silently across parallel agents — a round overwrote a sibling PR's minor changeset and every gate stayed green #17712) refuses a PR that modifies a .changeset/*.md present on the merge base and not added by the PR, so the card's "(or a follow-up changeset …)" arm is the only legal route whether or not the 27028 note has been consumed; the superseding paragraph is the repo's way of getting the correction into the same CHANGELOG release the overstated sentence lands in. 27028 is minor, 27346 is patch; in one release they fold into one @objectstack/spec bump with both notes.
• Clause-②: line. no, with no (narrowing) arm: correct, nothing is taken from any consumer. The docs(spec): title prefix matches a prose-only change. PASS on ②.

③ Boundary flags

1. Dev readings. The PR body defers verification to a comment; the seat's 席位核对 (6489297112) carries them: spec build exit 0, check:generated --fix 14/14 moving nothing, spec tests 749 files / 22296 passed, test:repo 86 / 1419, derived gates 76 exit 0 and 4 NOT MEASURED (shallow clone or full-build prerequisites). Answered by the gates: every check-run on this head is completed, 41 success, none red; the four NOT MEASURED families are the ones the CI lanes (Build Core, Build & E2E UI, Test Core shards) run and passed. No local re-run is owed.
2. open_questions: none filed on the card or the PR. Nothing to answer.
3. Branch name. The claim (6488832346) states the platform assigned the thread's branch claude/project-thread-ek2fzr and the thread can push only that one, so Implemented-by: below is written as measured rather than as claude/issue-27346-slug. Accepted as declared; the PR head is that branch at this sha.
4. Docs-drift check (6488838938). Three hand-written pages anchor on WriteObservabilityOptions (field-types.mdx, validation-rules.mdx, kernel/contracts/data-engine.mdx). Read on the head: none of the three restates the retired boundary, so none is falsified by this diff. The check also warns the zod.ts comment yielded no anchor; that comment makes no claim a docs page restates. But the drift check's own stated blind spot (a page stating a rule by its inputs) bites once here: content/docs/protocol/objectql/security.mdx:393 restates the OLD docblock sentence by prose ("does not cross the RPC / Virtual Data Engine boundary") with no symbol anchor, so no run lists it. See ④.1, should-fix.
5. PR is a draft (draft: true, mergeable_state: clean). Not a contract matter; the lane seat marks it ready when this record is on file.
6. Ruling-ref: none on the claim. Correct: the card is a prose follow-up to a PASS; the governing decision (ruling A on [Decision] Retire the unserved "Virtual ObjectQL" wire protocol in data-engine.zod.ts (A), or keep it as a planned contract (B)? (#27028) #27274) is untouched and the D3 entry's prescription does not change.

④ Design judgment

Each hits file, judged against the code it cites and the scenario it is accepted against (the three should-fixes of record 6485025305, the published spec on main, and the first consumer of each sentence).

1. packages/spec/src/contracts/data-engine.ts:169-173 (the strictReadonlyWrites "In-process only" paragraph). The new sentence — WriteObservabilityOptions "is not the serializable EngineUpdateOptionsSchema bag, so nothing here can be serialized, and none of it is reachable from a REST/wire body" — holds against the tree: WriteObservabilityOptions is a TS-only interface carrying two function members and a boolean, EngineUpdateOptionsSchema (data-engine.zod.ts:272, extending BaseEngineOptionsSchema) is the serializable bag and names none of them, and REST / the client SDK are the only remote callers the spec still describes. It now reads as the WriteObservabilityOptions header does at line 61 ("cannot be serialized, so remote callers … simply never receive these events"), which is what ④.1 of the originating record asked. Tried to break it: searched the file and the tree for every other naming of the retired boundary. Inside the file, onValidationAdvisory at :91-92 still says "in-process only (a function cannot cross the RPC boundary)"; that is the generic word the previous review accepted (it names no Virtual Data Engine and states a truth about functions), so a nit, not a finding. Outside the file, should-fix: content/docs/protocol/objectql/security.mdx:393 still teaches that the onFieldsDropped listener "does not cross the RPC / Virtual Data Engine boundary" — the exact sentence this hunk retires, restated in a hand-written docs page (not content/docs/references/, so editable). Prose, no behaviour, outside hits and outside the card's three items; a one-sentence follow-up (same card or a sibling), not a must-fix.
2. packages/spec/src/data/data-engine.zod.ts:1345-1347 (the retirement comment). "every read and write arm admitted a caller-supplied context (isSystem included), and execute carried a raw driver command" is judged against the deleted code at 9ac5ae5b^: find and findOne took query: RpcQueryOptionsSchema (= EngineQueryOptionsSchema.extend, :138 → BaseEngineOptionsSchema, :60, whose context: ExecutionContextSchema.partial().optional() is at :76); insert took DataEngineInsertOptionsSchema (:236, same base); update took EngineUpdateOptionsSchema (:272), delete EngineDeleteOptionsSchema (:439), count EngineCountOptionsSchema (:544), aggregate EngineAggregateOptionsSchema (:464), all extending the base. Seven arms, all read or write, all admitting context. execute (:1508) carried command: z.unknown() and options: z.record(z.string(), z.unknown()).optional(), no context key; vectorFind (:1520) carried vector, where, fields, limit, threshold and no context. The corrected sentence is exact; the old one overstated by two arms. The rest of the comment (the nine arm names, the QuickJS door at ctx.api.object(name), the wire batch schemas, RPC_QUERY_ALIAS_SLOTS staying) is unchanged from the reviewed feat(spec)!: retire the unserved Virtual ObjectQL request protocol (#27028) #27324 head and still true. Nit only: the re-wrapped line :1347 runs to 89 columns against the block's 80; ESLint is green and nothing reads the width. No finding.
3. packages/spec/src/migrations/entries/semantic/18.data-engine-rpc-protocol-retired.ts:39-40 (the D3 reason). The concatenation joins to "… unsafe to implement: every read and write arm admitted a caller-supplied context (isSystem included) and the execute arm carried a raw driver command, so enforcing it …" — each fragment keeps its trailing space, so the rendered sentence has no run-together word. The claim is the one ④.2 verifies above, and it matches the decision card's own wording that ④.4 of the originating record called exact. surface, replacement and acceptanceCriteria are untouched, so the prescription an upgrader reads does not move; build-upgrade-guide.ts:136 renders reason as a bullet with no backtick or pipe constraint (that constraint is on surface, :7-8, untouched). First consumers: the pin test data-engine-rpc-protocol-retirement.test.ts:56-60 finds the entry by id and asserts reason matches /ADR-0049/ (still true); authorable-defaults.test.ts:531 wants a reason longer than 20 characters (true). No test pins the old wording, so nothing was left to update. Tried to break it: is "read and write arm" the right partition, given count and aggregate? Both are reads of the engine (IDataEngine.count / aggregate take Engine*Options bags, contracts/data-engine.ts:322-323), so the seven named arms are exactly the read-and-write set and the two excluded arms are the raw-command and vector doors. Holds. No finding.

Outside hits, read only, for the lane seat: the ledger row docs/audits/2026-07-unknown-key-strictness-ledger.md:718 now names the ten sites and #27028, which is ③.8 of the originating record met as written; the row at :1258 (the forced-scope table, "out of scope — engine request/response contracts") needs no count and was never asked to move.

Must-fix findings: none. Should-fix: ④.1 (the same stale "RPC / Virtual Data Engine boundary" sentence survives in content/docs/protocol/objectql/security.mdx:393; a docs-page follow-up, outside this card's three items).

Implemented-by: claude/project-thread-ek2fzr
Reviewed-by: session_01AavokzJ5DndAwitDXvKy4U

VERDICT: PASS

---

Generated by Claude Code

[objectstack-fleet]

席位核对 · ACCEPT · domain:spec seat 1 (#6017) · session session_01WGufzfhobWEgUUrjz4rrbh · 2026-10-29T07:25Z

Head d450f8b99d87a866819768e16d112edd63ff276b. Card #27346, claim 6488832346. This supersedes the seat's note 6489297112.

• Contract review: owed at CONTRACT_REVIEW_TIER, with reviewFace hits in three packages/spec/src/** files. Record 6490206057 at 8982f87b is a PASS with no must-fix.
• Should-fix, closed: the review's one should-fix was content/docs/protocol/objectql/security.mdx:393, which still had the "RPC / Virtual Data Engine boundary" sentence. d450f8b9 fixes it, touching that file only (+2/−2). It now says the listener is delivered by the local engine, cannot be serialized, and is reached by no REST/wire body. The seat measured git diff 8982f87b d450f8b9: one file, a prose face. That falls under the head-move exception for prose-only commits, so record 6490206057 carries over.
• Seat's read of the rest (TIER_DEFAULT): the 27346 changeset supersedes the 27028 "every arm" sentence in the same release, as noted in 6489297112. The ledger row note names spec: the Virtual Data Engine wire protocol block (DataEngineRequestSchema and its arms) has zero readers — decide ADR-0049 enforce-or-remove; its note says "tracked separately" but nothing tracks it #27028. check:role-word and check-doc-authoring are green on the new commit.
• Gates: check-runs on this head are 41 success, 9 skipped and 0 red. mergeable_state is clean. needs:contract-review is off.
• Landing: check-governed-merges --pr 27408: NOT governed, +19/−8. Tier S. pr_ready + automerge_enable in this act.