feat(spec,metadata-protocol): the publish receipt names the rows a seed created and the rows it only matched - #30427

📓 Docs Drift Check

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

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

• content/docs/api/client-sdk.mdx (via meta.publishItem (sdk, the route ledger binds it to POST /api/v1/meta/:type/:name/publish, selected by route anchor /:type/:name/publish), publishItem (sdk, the bare tail of client method meta.publishItem, bound to POST /api/v1/meta/:type/:name/publish))
• content/docs/api/metadata-api.mdx (via /:type/:name/publish (route, bridged from symbol PublishMetaItemResponseSchema — its route source's handler names it))
• content/docs/concepts/metadata-lifecycle.mdx (via /:type/:name/publish (route, bridged from symbol PublishMetaItemResponseSchema — its route source's handler names it))
• content/docs/kernel/contracts/metadata-service.mdx (via /:type/:name/publish (route, bridged from symbol PublishMetaItemResponseSchema — its route source's handler names it))
• content/docs/protocol/kernel/error-handling.mdx (via /:type/:name/publish (route, bridged from symbol PublishMetaItemResponseSchema — its route source's handler names it))

⛔ 4 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via /:type/:name/publish (route, bridged from symbol PublishMetaItemResponseSchema — its route source's handler names it))
• content/docs/releases/v17/17-1.mdx (via publishPackageDrafts (symbol, a method of class ObjectStackProtocolImplementation), /:type/:name/publish (route, bridged from symbol PublishMetaItemResponseSchema — its route source's handler names it))
• content/docs/releases/v17/17-2.mdx (via /:type/:name/publish (route, bridged from symbol PublishMetaItemResponseSchema — its route source's handler names it))
• content/docs/releases/v17/17-4.mdx (via /:type/:name/publish (route, bridged from symbol PublishMetaItemResponseSchema — its route source's handler names it))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin eed2f12ceb5527c9484871b0504ca576a8ea6673 && git checkout eed2f12ceb5527c9484871b0504ca576a8ea6673
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 8fa738fbe370c6cd8742fa14857e1b82d9b5d2a4 8dea3777a4a25877370951d5c2c7a70a0276a6aa && git checkout -B drift-repro 8fa738fbe370c6cd8742fa14857e1b82d9b5d2a4 && git merge --no-ff 8dea3777a4a25877370951d5c2c7a70a0276a6aa

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

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

domain:spec#3 · os-support-ai · session_01WGufzfgvGexKn9vLHsy89K

Contract-review-claim: session_01WGufzfgvGexKn9vLHsy89K · head c438aed · 2026-11-05T10:52Z

Full review of the first head at CONTRACT_REVIEW_TIER (a metadata-protocol addition: the publish receipt's seedApplied carries the landed seed row ids, split into inserted and matched, capped per list).

domain:spec#3 · os-support-ai · session_01WGufzfgvGexKn9vLHsy89K

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: c438aed4e40f67928b0fa4e0cb7b8cbaabc3c5a4
Local-runs: none
Scope: the PR diff against merge-base fe835b49aa (all 26 files; implementation 11b7c671 plus the merge of origin/main); packages/spec/src/api/protocol.zod.ts (SEED_APPLIED_LANDED_IDS_CAP :1422, SeedAppliedIdListSchema :1432-1442, SeedAppliedLandedSchema :1473-1484, the shared description :1488-1495, the docblock :1520-1531, the two landed keys :1590 and :1891); packages/spec/src/data/seed-loader.zod.ts (landedIds :441, insertedIds :459); packages/metadata-protocol/src/seed-loader.ts at head (insertedRecordIndexes :1336, noteLanded :1344-1355, the flush :1377-1468 with the mark at :1445, the sequential writeRecord path :2140-2185 with the mark at :2159, the catch :2171, the skip :2195, the update :2208, landedIds and insertedIds :2275-2289, writeRecord :3000-3062, decideWriteAction :3076-3105, extractId :3795-3798, resolveDeferredUpdates); packages/metadata-protocol/src/seed-applied-landed.ts (:30-36, :47-64); packages/metadata-protocol/src/protocol-publish-batch.ts (applySeedBodies :70-186, landed :140, the catch :142-185); packages/metadata-protocol/src/protocol-history-and-publish.ts :374, :1100; packages/metadata-protocol/src/protocol.ts :12375, :12446; packages/metadata-protocol/src/index.ts :22; packages/runtime/src/domains/packages.ts (:2100, applyPublishedSeeds :3840-3985, landed :3983) and packages/runtime/src/seed-loader.ts (a re-export shim); packages/objectql/src/publish-seed-receipt-landed-ids.test.ts (8 cases :170-299); packages/metadata-protocol/src/seed-loader-landed-ids.test.ts (the #30348 describe :290-393, 6 cases); packages/spec/src/api/protocol.test.ts (:3034-3074, 4 cases); packages/objectql/src/publish-meta-response-conformance.test.ts :316-331; packages/objectql/src/publish-package-drafts-seed-receipt-counts.test.ts :197, :231; packages/objectql/src/protocol-publish-package-drafts.test.ts :422-424, :491 (mocked producer); the spec ledgers (api-surface, authorable-surface/{api,data}.json, authorable-defaults/data.json, declaration-map, export-origins, json-schema.manifest), packages/spec/liveness/ (README, seed.json), the generated content/docs/references/{api/protocol,data/seed-loader,index}.mdx, the changeset; scripts/check-changeset-no-major.mjs (:9-15, :907-943, :1594-1606, :2045-2049) and scripts/pm/clause2-line.mjs (:111-121, :269-276); the seat order /mnt/project-files/seat3-orders/30348.md; card #30348 body and 5 comments (os-dev-report 6656124019 included); PR #30427 body, 2 comments, 0 reviews; check-runs on the head.

① Derived judgments

1. Fidelity at every noteLanded site. There are five sites and two insert marks, and the marks sit exactly where a row is created: (a) the batched flush (:1442-1445) marks recordIndex beside noteLanded when res.ok and the stored id is non-empty; (b) the self-referencing sequential path (:2158-2159) marks only when writeRecord answered action === 'inserted', and writeRecord (:3000-3062) answers that only after engine.insert returned, in every mode (insert :3012-3014, upsert miss :3037-3039, ignore miss :3046-3048, replace :3052-3054, the default arm :3057-3059); (c) the sequential catch (:2171) lands the pre-existing id of a refused UPDATE and marks nothing, and a refused INSERT has no existingId so it lands nowhere; (d) the skip site (:2195) lands the matched id for ignore and a no-op replay, marks nothing; (e) the update site (:2208) lands the matched id BEFORE the write and marks nothing, so a refused update is matched, as the body's table says. decideWriteAction (:3076-3105) routes a matched key in ignore to skip and in upsert/update to update or skip, and only an unmatched key (or any insert/replace record) reaches pendingInserts, so no customer row can enter the flush's ok branch except through the attempt-greater-than-one recheck (:1393-1400, :1430-1437), where a key hit is by construction a row this load's own earlier attempt wrote; that classification is right and is the same ambiguity the inserted counter already carried. Ids are the stored primary keys: extractId (:3795-3798) reads record.id || record._id off the engine's returned row or the loaded existing row, and the re-identification map ([finding] On a walled showcase deployment every organization/create replays fixed-id sys_business_unit seeds that collide on the global id: 9 SeedLoader errors and an unresolved parent reference per new organization #21665) is fed from the same landedId. Dedupe and order: insertedIds (:2284-2289) is the same internalIdByRecordIndex map as landedIds (:2275-2279), filtered by the mark set, sorted by record index, then Set-deduped, so insertedIds is a subset of landedIds by construction. Pass 2 (resolveDeferredUpdates) touches only referencesResolved and the error list on allResults, never the id lists, and pushes no result. A dry run never calls noteLanded (:2241-2247), so both lists are empty. The projection (seed-applied-landed.ts :47-64) folds per object in first-loaded order, unions insertedIds and landedIds over the object's datasets, and derives matched as landed minus inserted (:61), so a second dataset's key hit on a row the first dataset created stays inserted; the objectql pin at :242 measures that against the engine. A result lacking insertedIds (an older loader shape) puts everything under matched, the safe direction.
2. Cap boundary. cappedList (:30-36): ids.slice(0, 200), total: ids.length, truncated: ids.length > 200, so exactly 200 ids give truncated: false, total: 200 and 201 give 200 ids, truncated: true, total: 201. The schema (:1433) refuses a 201st id; the spec pin at :3061 parses 200 and refuses 201, and the objectql pin at :216 drives 205 records through the real door and asserts the first 200 in record order, total: 205, truncated: true, then shows the schema refusing the uncut list. The exactly-200 boundary is pinned at the schema only, not through the projection (judgment 5).
3. Both doors and the fallback. applySeedBodies returns landed: seedAppliedLanded(r.results) only on the returned-load path (:140); the catch (:142-185) returns counts from seedLoadPartialWrites with no landed, pinned at :273 (a good seed lands, a missing-object seed throws, inserted: 1, no landed key). publishPackageDrafts passes the whole object through (protocol.ts :12375, :12446); publishMetaItem goes through runPublishSideEffects (protocol-history-and-publish.ts :1100) and copies the object whole (:374); neither picks fields, and both are driven by real-door pins (:170 and :289). The runtime fallback (packages.ts :3983) imports the same projection through index.ts :22 and its loader is the same class (packages/runtime/src/seed-loader.ts re-exports @objectstack/metadata-protocol's SeedLoaderService; git grep "class SeedLoaderService" finds one), so insertedIds is filled there too. The fallback's landed has no door pin of its own; its producer is a one-line fold of the same function, acceptable by reading.
4. Declarations. PR body and changeset both carry Clause-②: yes (widening: …) (arm widening, the first token inside the parenthesis, clause2-line.mjs :269) and Metadata-protocol: added. added is the grade the checker owes: authorable-surface/api.json (six SeedAppliedIdList/SeedAppliedLanded keys), authorable-surface/data.json (SeedLoadResult:insertedIds) and authorable-defaults/data.json (insertedIds = []) all moved, and a moved baseline under none is refused (check-changeset-no-major.mjs :1594-1606); the changeset grades spec minor, metadata-protocol minor (a new exported symbol seedAppliedLanded and a new receipt key), runtime patch. Check Changeset, PR-body guards, Lint · PM dispatch-gates and Spec property liveness are green on the head. Liveness: the ledger governs registered metadata types (liveness/README.md, seed.json holds Seed's authorable keys); neither SeedLoadResult nor the publish responses have rows, landedIds has none, so insertedIds and landed owe none, and the PR claims none. Honest.
5. Pins and ablation. Every claim in the order has a pin: exact ids per object at the real door (:170), the over-cap shape (:216), no seed means no field (:260), existing receipts parse unchanged and gain no key (:3050), one shared schema on both responses (:3043, and the real-door parses at :182 and :298), required total/truncated/both lists (:3069), and the loader split per mode (fresh, replay, ignore over a customer row, refused update, self-referencing path, refused insert and dry run, :290-393). Ablation 1 (the flush mark deleted) reddens 3 of 14 loader cases and ablation 2 (the matched filter neutralised in dist) reddens 6 of 8 door cases, both real reds and both reported with blob hashes and restoration. Gaps: no unit pin on seedAppliedLanded itself (junk entries at :50 are tolerated by reading only: null, non-string object, a result with neither list; exactly 200 through cappedList; empty results giving []), no empty-seed door pin (records: [] giving one entry with two empty lists, which the docblock at :41-45 and the description at :1491 promise), and the fallback producer is unpinned. The two unchanged toEqual pins in protocol-publish-package-drafts.test.ts (:440, :502) mock applySeedBodies (:422-424, :491), so they are correct as left; the two real-loader pins the dev did update (:197, :231) admit landed with expect.any(Array) and defer the ids to the new file.
6. Backward compatibility. landed is optional on both schemas; a receipt without it parses byte-identically (:3050-3058). The inline TS return types gain an optional key only. SeedLoadResultSchema.insertedIds defaults to [] like landedIds, so an old-shaped result parses; a reader of landedIds alone (seed-settlement.ts :50-96, claim-seed-ownership.ts, app-plugin.ts :2022-2051) is untouched. Readers of the old receipt see one extra key.
7. Body versus code. The two insert sites, the merge/dedupe/cap rules, the per-mode table, the thrown-load omission, the cap source and the test counts (8, +6, +4) all match the code. The body says the inserted list is "in record order" while the schema description (:1434) says "first-landed first"; the loader sorts by record index (:2277, :2287), and a matched row at a later index lands in wall time before a buffered insert at an earlier index flushes, so the schema wording is the looser of the two (judgment ④.3).

② Semver level

@objectstack/spec minor, @objectstack/metadata-protocol minor, @objectstack/runtime patch. Two new exported schemas, one constant, one optional key on two published response schemas and one defaulted key on SeedLoadResult; one new exported function from metadata-protocol. Nothing refused, narrowed or re-meant. Clause-②: yes (widening) and Metadata-protocol: added are the right pair for what the checker measures.

③ Boundary flags

• Files touched stay inside the order: the two spec files, the loader's two insert sites, one new projection module beside applySeedBodies, the two doors' return types, the runtime fallback (named in the order's "every producer of it, any other route that attaches seedApplied" clause and the third claim's "the publish paths that return seedApplied"), their tests, and regenerated artifacts. seed-settlement.ts and the cloud half are untouched. app-plugin.ts's boot-time landed computation (:2022-2051) is the boot source the order excludes and is untouched.
• The cap's source: cloud was unreadable from the dev session (the body says so, with a 0-hit org search), and the order's third rung ("pick a cap, give the reason, and stop to tell the seat") was followed: the seat chose 200 with the dev before the build, mirroring EXPLAIN_BATCH_MAX_RECORD_IDS and BULK_BATCH_SIZE. One constant to move if cloud's ledger cap differs.
• Carried tier: (a) a load that throws mid-batch drops the ids of the datasets that landed before it (SeedLoadPartialWrites carries counts only, :165-169); the receipt says "not reported" and cloud must read absent landed beside success: false as unknown, as the body states; widening SeedLoadPartialWrites is a follow-up card. (b) claim-seed-ownership.ts and seed-settlement.ts read landedIds only and so hand over matched rows too; whether the ownership claim should narrow to insertedIds is a separate ruling, not this card.
• No governed surface in the file list; no release-owned page edited; the docs-drift bot's five hand-written pages name the route, not the key.

④ Design judgment

The split into inserted and matched is the right shape and the only safe one under the ignore default: a single landed list would have handed cloud's "clear sample data" a customer's row. The projection lives in metadata-protocol once and both producers import it, the cap and the truncation shape are declared in the spec and refused by the schema past the cap, and every claim in the order is pinned at a real door against the engine. Must-fix: none. Should-fix, in order: (1) add seed-applied-landed.test.ts with direct pins on the projection: junk entries (null, non-string object, a result with neither list, a result with landedIds only), empty results giving [], exactly 200 ids giving truncated: false and 201 giving truncated: true, total: 201, and the cross-dataset inserted-then-matched fold without the engine; (2) add an empty-seed door pin (records: []) asserting one entry with two empty lists, since the docblock and the description both promise it; (3) align SeedAppliedIdListSchema.ids's "first-landed first" (:1434) with the loader's "record order" (:2277, :2287) so the two docs say the same thing; (4) file the thrown-load follow-up (ids of datasets landed before the throw) as its own card so cloud's reading of absent landed has a named end. None blocks landing; landing waits on the still-running required contexts (Build Core, Test Core 1-8, Type Check, Lint) going green.

Implemented-by: claude/project-thread-5eqwnz
Reviewed-by: session_01WGufzfgvGexKn9vLHsy89K

VERDICT: PASS

domain:spec#3 · os-support-ai · session_01WGufzfgvGexKn9vLHsy89K

维护者速读

• 改了什么： 发布回执的 seedApplied 新增可选键 landed：按对象列出本次种子落地的行 id，分成 inserted（本次新建的行）和 matched（种子按键命中的已有行），每个列表最多 200 个 id，超出时标 truncated 并给出总数。种子加载器的每数据集结果新增 insertedIds。
• 为什么改： cloud 的「清除示例数据」要知道种子建了哪些行。只给一个 landed 列表不安全：默认 ignore 模式下，命中键的客户自有行也会算进去，清除时会删掉客户数据。
• 风险与回滚： 纯新增可选键，旧回执照常解析。两个发布入口和运行时兜底路径共用同一个投影函数。加载中途抛错时回执不带 landed（表示「未报告」，不是「没有落地」），已另开卡 metadata-protocol: a seed load that throws mid-batch drops the landed row ids of the datasets that landed before the throw, so the publish receipt carries no seedApplied.landed #30429。回滚即还原本 PR。
• 先看： packages/spec/src/api/protocol.zod.ts（SEED_APPLIED_LANDED_IDS_CAP、SeedAppliedLandedSchema）；packages/metadata-protocol/src/seed-applied-landed.ts；seed-loader.ts 的两处插入标记。
• 两分钟验证： pnpm --filter @objectstack/metadata-protocol exec vitest run src/seed-applied-landed.test.ts，预期 9 passed。
• 需要你做的： 无，席位落地。

席位意见：fable 契约复审 PASS，没有必须修的。前三条建议已在一次推送里采纳：投影函数的 9 个直接钉（含 200/201 边界）、空种子的入口钉、id 顺序的措辞改为加载器的记录顺序。第四条（中途抛错时丢失已落地 id）另开 #30429。

席位核对 — ACCEPT · domain:spec#3 · head 8dea3777a4a25877370951d5c2c7a70a0276a6aa

• Shape: 27 files (+951 −20, generated ledgers and docs included) on origin/main fe835b49:
  • @objectstack/spec: SEED_APPLIED_LANDED_IDS_CAP (200), SeedAppliedIdListSchema { ids, total, truncated }, SeedAppliedLandedSchema per object { object, inserted, matched }, an optional landed on both seedApplied receipts, and SeedLoadResult.insertedIds;
  • @objectstack/metadata-protocol: the loader marks a row inserted at its two insert sites (the batched flush and the sequential writeRecord path), one exported projection seedAppliedLanded, and applySeedBodies returns landed, so publishPackageDrafts and publishMetaItem carry it;
  • @objectstack/runtime: the package-publish fallback seed apply reports the same landed through the same projection;
  • pins, regenerated ledgers and docs, a changeset (spec minor, metadata-protocol minor, runtime patch).
• Premise measured: at origin/main, the receipt carried counts only, and SeedLoadResult.landedIds mixed inserted and matched rows (the card's measurement).
• Gates: at 8dea3777 after a full build (119/119), 107 derived gates run, all exit 0, and --ran reconciles with 0 NOT-MEASURED (dev report). Check-runs on this head: 57 success, 10 skipped, 0 red; Check Changeset and the PR-body guards re-run after the seat's body edit.
• Contract review:
  • Full review, 6656296448 on c438aed4: PASS, no must-fix. It found the insert marks exactly where a row is created at all five noteLanded sites; skip, update-before-write and a refused update land matched ids only; a refused insert and a dry run land nowhere. It confirmed the cap boundary (200 whole, 201 cut with total: 201), that both doors and the fallback pass the object whole, and that old receipts parse unchanged.
  • The seat read the round-1 delta (6 files, +136 −8; no code path changed): seed-applied-landed.test.ts with 9 engine-free pins (junk skipped, empty results, legacy datasets, 200 vs 201 per list, cross-dataset inserted-then-matched in either order, dedupe), whose boundary ablation goes red; the empty-seed door pin; and the ids wording aligned to the loader's record order in the schema, the docblocks, the changeset and the generated protocol.mdx.
• Declarations: Clause-②: yes (widening), Metadata-protocol: added, ADR-0087 not needed.
• Accepted deviations: none.
• Carried:
  • metadata-protocol: a seed load that throws mid-batch drops the landed row ids of the datasets that landed before the throw, so the publish receipt carries no seedApplied.landed #30429 (p2, Blocked-by metadata-protocol: the publish receipt's seedApplied drops the landed row ids the seed loader computes, so cloud cannot tell which rows an AI build's seed landed on (objectstack-ai/cloud#3598 ruling A) #30348): a load that throws mid-batch drops the ids of the datasets that landed before the throw.
  • Whether the seed-ownership claim (claim-seed-ownership.ts, seed-settlement.ts) should narrow from landedIds to insertedIds is a separate ruling, not filed by this card.
• Landing: not governed (check-governed-merges --pr 30427: 0 of 27 paths, 971 lines). The hand-off is pr_ready plus automerge_enable, through the merge queue.