docs(kernel): align data-engine contract page with the shipped engine seam (#7057)

[os-help]

Fixes#7057

Docs-only. Three measured divergences on content/docs/kernel/contracts/data-engine.mdx, each re-derived against origin/main (@ 5087ac6) rather than against the issue's line anchors — the file moved twice on 2026-08-09 (#7125, then the tree advanced again during this task).

1 + 2. EngineQueryOptions.cursor and query-level distinct — retired by #4286

Both were still listed as live members of the interface. They are not merely gone from the schema: packages/spec/src/data/data-engine.zod.ts keeps a retiredKey() tombstone for each, so a query carrying one is rejected by name. The page was telling readers to write a key the engine refuses — copy-the-docs-and-fail, exactly the class the triage ruling named.

Both lines are removed from the code block and replaced by a Removed in protocol 17 subsection carrying each tombstone's own migration prescription:

• cursor — express the keyset as an ordinary where predicate on your sort key with the matching orderBy; QueryBuilder.cursor() went with it.
• distinct — distinct(object, field) on the SQL/memory drivers, groupBy for unique combinations, the count_distinct aggregation for a deduplicated count.

The prose follows this file's own house style for a removal (the AggregationNode.distinct note added by PR #7051 sits ~200 lines below).

3. WriteObservabilityOptions — stopped at #3407

The PM's dispatch table called this row "partly overtaken by #7125". Measured, that is right for the code block and wrong for the prose, so the repair is larger than the table implies:

Sub-divergence	State found on origin/main
reason enum missing primary_key	already repaired by #7125 — left alone
strictReadonlyWrites absent from the code block	still absent (#5126)
"The write still succeeds" unconditional	still unconditional — false under strict
Prose strip list names only the two author-declared strips	still stale — #7125 repaired the enum in the code block but not the sentence above it, so the runtime-owned strip (#5503) and the primary-key strip (#6437) were still unmentioned in prose

Rewritten against packages/spec/src/contracts/data-engine.ts (read-only for this card):

• a strip table — strip / reason / verbs / writers it skips — covering all four legal strips and the fact that the runtime-owned one reports under the readonly arm rather than adding a new one;
• strictReadonlyWrites in the code block and a section of its own: refuses before the driver is touched, nothing written, coverage DERIVED from what onFieldsDropped reports, ReadonlyFieldRejectedError / ERR_READONLY_FIELD_REJECTED carrying the full field list, caught by code not instanceof;
• the two options stated as alternative outputs of one seam — onFieldsDropped does not fire on a write strict refuses;
• the INSERT rule: author-declared strips are insert-exempt at this seam (feat(automation): update_record/create_record 步骤对被静默剥离的写入字段挂 warning(#3407) #3413), so an insert refusal can only be a runtime-owned value, and the two exempt writers are isSystem and the preserveAudit historical import (data import: a "historical" import can't preserve original timestamps / audit fields — updated_at is stamped now, readonly fields stripped on upsert (#3479 follow-up) #3493);
• the in-process-only Callout widened from onFieldsDropped to the whole bag, because a client toggling write-refusal on a security-adjacent path is the specific thing the [决策] readonly 剥离的 strict/reject 模式落在哪一层 —— B(WriteObservabilityOptions)推荐,A/C/D 各有代价(#4903 后续) #5126 ruling excluded.

The layering claim was verified, not relayed. The issue thread suggested carrying over the engine-seam vs DataProtocol-ingress distinction (#3043 / #6640). packages/metadata-protocol/src/protocol.tsstripReadonlyForInsert confirms it in code: the ingress enforces its own author-declared readonly policy on create, knows only isSystem, deliberately does not read preserveAudit (#6640), and leaves runtime-owned types to the engine strip (#5503). That is what the new Callout says, and it says nothing wider.

Verification

Premise confirmed at the schema level, then reverse-verified by parsing (a probe run against EngineQueryOptionsSchema, not committed):

cursor => success: false msg: `query.cursor` was removed in @objectstack/spec 17 (#4286, ADR-0049) — no driver ever implemented keyset pagination...
distinct => success: false msg: `query.distinct` was removed in @objectstack/spec 17 (#4286, ADR-0049 / ADR-0078) — no driver ever rendered SELECT DISTINCT...
control (no retired key) => success: true

Gates run locally (docs-facing families for this surface; the full farm is CI's):

• pnpm check:doc-authoring — green, 374 files clean
• pnpm check:docs-audit-scope — green, 179 hand-written docs in sync
• pnpm --filter @objectstack/lint run check:doc-formula-expressions — green, 22 examples across 387 files
• pnpm --filter @objectstack/spec run check:skill-examples — green, 209 prose examples type-check; the edited block is in the checked set (content/docs/kernel/contracts/data-engine.mdx:311), since the WriteObservabilityOptions fence carries the os:check marker
• node scripts/check-nul-bytes.mjs — green

Scope notes

• No changeset: docs-only, nothing in a published package changes, and AGENTS.md asks for a changeset on feature work. skip-changeset is the PM's to apply at acceptance.
• content/docs/releases/ untouched. This page is hand-written and not routed to merge=os-regen, so it is edited directly and never regenerated.
• Out of scope, filed instead: docs: data-engine.mdxEngineQueryOptions block omits searchFields, declared on the schema since #4371 #7170 — the same EngineQueryOptions block omits searchFields, a declared member since [P2] A direct engine call silently drops sort/select/skip/populate — declared query contract, zero enforcement #4371. Different class (an omission, not a retired key still documented), so it was left for triage rather than ridden in here.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 10, 2026 1:46am