[objectstack-fleet]

domain:server#2 · os-sales · session_01L6bhgUCizoYWQVJWjhdR6F

Requested by Sales · project thread
Fixes #27393

Clause-②: no
Metadata-protocol: none
Skills-docs: none — nothing an author writes changes; only the values of an existing receipt become truthful

维护者速读

• 改了什么:包发布(publish-drafts)里某个 seed 失败时,seedApplied 回执的 inserted/updated 现在等于失败前实际写入的行数,error 点名是哪个对象的 seed 让加载停下;回执形状不变。
• 为什么改:以前失败分支硬编码 inserted: 0, updated: 0,但前面的 seed 已经写进表里,回执说"什么都没写"是错的数据。
• 风险与回滚:只改失败分支的取值与文案;发布哪些 seed、失败后后续 seed 不再应用、不回滚,这三点都不变。回滚即 revert 本 PR。
• 先看:packages/metadata-protocol/src/protocol-publish-batch.ts(catch 分支)、packages/metadata-protocol/src/seed-loader.ts(load() 的 catch 与 notePartialWrites)、packages/objectql/src/publish-package-drafts-seed-receipt-counts.test.ts。
• 两分钟验证:pnpm --filter @objectstack/metadata-protocol build && pnpm --filter @objectstack/objectql exec vitest run src/publish-package-drafts-seed-receipt-counts.test.ts,预期 5 passed。
• 需要你做的:无,席位落地。

What changes

Semantics chosen and stated: truthful aggregate counts, inside the existing seedApplied shape (success/inserted/updated/error/errors). When a seed in the batch fails:

• inserted / updated are the rows the loader actually wrote before it stopped — the finished datasets plus any rows the failing dataset itself wrote before it threw;
• success stays false;
• error names the seed that stopped the load by the object its dataset populates: seed apply stopped at the seed for object 'OBJECT': ..., followed by the same sentence as before (a declared refusal quoted, anything else withheld as seed apply failed).

Not changed: which seeds are published, that the loader stops at the failing dataset (later seeds are not applied), and that nothing is rolled back. All-or-none and per-seed counts were not chosen: the first is a larger behaviour change, the second needs a spec edit.

Mechanism:

• seed-loader.ts: load() now catches a throw and records on the thrown error (a module-private WeakMap, read through the new seedLoadPartialWrites(err)) what the load had written: the sum over finished dataset results plus the in-flight dataset's counters, and that dataset's object. The error itself is rethrown unchanged, so its declared status and message reach the caller as before. loadDataset keeps its insert/update counters in one object the load can read. seedLoadPartialWrites is not re-exported from the package index: the published surface does not move.
• protocol-publish-batch.ts: the applySeedBodies catch reads that record instead of hard-coding zeros. No record means the throw came before the loader wrote anything (the request parse, or the loader import), so 0 is the truthful count there.

Tests

• packages/objectql/src/publish-package-drafts-seed-receipt-counts.test.ts (new) — the real publishPackageDrafts door, real ObjectQL engine, real SeedLoaderService, in-memory driver (objectql carries no sqlite driver; harness copied from publish-package-drafts-response-conformance.test.ts). Every count is checked against engine.find on the seeded object:
  1. seed 1 writes 2 rows, seed 2 names a missing object → success: false, inserted: 2, error names seedrepro_nope; outcome published, publishedCount: 2 (unchanged).
  2. seed 1 UPDATES 2 existing rows, seed 2 fails → updated: 2, inserted: 0.
  3. control: every seed succeeds → { success: true, inserted: 3, updated: 0 }, as before.
  4. the first seed fails, a good one follows → engine holds 0 rows, receipt 0/0.
  5. the only seed fails → 0/0.
• packages/metadata-protocol/src/seed-loader-seed-files.test.ts (3 cases added, reusing that file's pinned engine double) — a throw INSIDE a dataset after one of its rows landed (the file service failing while the row's seed file settles): { inserted: 3, updated: 0, failedObject: 'pw_doc' } against the store; a throw before any dataset: { inserted: 0, updated: 0 }; a foreign error carries no reading.

Red first: on the unfixed tree, cases 1 and 2 failed with expected +0 to be 2; 3 passed.

Acceptance notes

• The runtime route POST /packages/:id/publish-drafts keeps a fallback seed apply (packages/runtime/src/domains/packages.ts, applyPublishedSeeds, with its own ../seed-loader.js copy) for protocols that do not self-apply seeds. Its catch reports seedApplied without inserted/updated at all. It runs only when the protocol returned no seedApplied; metadata-protocol's publishPackageDrafts always returns one when the batch has a seed, so this door is not reached by the stock protocol. Not touched here (outside this card's file surface).
• The failing seed is named by its object, not its metadata name: the seed bodies handed to applySeedBodies carry no name, and threading the names through would edit protocol.ts beyond this card's surface.

Verification

Ablation — hard-coded zeros restored (metadata-protocol dist rebuilt, door test)

ablation-replace: ok mutation landed: anchor 1 -> 0, blob 838c1b9a1d2c -> abbf2653dc95
✓ dist/: marker present in 2 built files -- the ablation is live in the artifact the suite consumes.
     × seed 1 writes 2 rows, seed 2 names a missing object: inserted 2, success false, error names seed 2
     × seed 1 UPDATES 2 existing rows, seed 2 fails: updated 2, inserted 0
AssertionError: expected +0 to be 2 // Object.is equality
      Tests  2 failed | 3 passed (5)
ablation-replace: ok restored: blob == HEAD (838c1b9a1d2c) and `git diff HEAD` is empty
-- restore leg: rebuilt; ablation-dist-preflight --absent: marker absent from all 24 built files; tree clean against HEAD
      Tests  5 passed (5)

Ablation — in-flight dataset count dropped (seed-loader, src-resolved)

ablation-replace: ok mutation landed: anchor 1 -> 0, blob 6557a0c4b948 -> a234cd9c4dfb
     × counts the finished datasets AND the rows the throwing dataset wrote, naming its object
-   "inserted": 3,
+   "inserted": 2,
      Tests  1 failed | 2 passed (3)
ablation-replace: ok restored: blob == HEAD (6557a0c4b948) and `git diff HEAD` is empty

(taken before the cases moved into seed-loader-seed-files.test.ts; same assertions)

Package tests, typecheck, lint, gates (head 1c64cb6)

• @objectstack/metadata-protocol full suite (after the origin/main merge, at 86b1fe7): Test Files 281 passed | 4 skipped; Tests 21805 passed | 26 skipped. At 1c64cb6: seed-loader-seed-files.test.ts 22 passed; objectql publish-package-drafts-seed-receipt-counts + protocol-publish-package-drafts + publish-package-drafts-response-conformance 38 passed.
• typecheck: metadata-protocol exit 0, objectql exit 0.
• eslint --no-inline-config on packages/metadata-protocol and packages/objectql: exit 0.
• dispatch-gates --commands: 59 derived families, all run; --ran reconciliation: 58 run, 1 NOT MEASURED — check:dual-build-cjs-loads exit 3, PREREQUISITE NOT MET (it needs every package's dist/; left to CI).

---

Generated by Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_01L6bhgUCizoYWQVJWjhdR6F

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol, touching 10 documentable anchor(s).

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

• content/docs/data-modeling/validation.mdx (via SeedLoaderService (symbol, a top-level class))
• content/docs/protocol/objectql/state-machine.mdx (via SeedLoaderService (symbol, a top-level class))

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

• content/docs/releases/v17/17-1.mdx (via SeedLoaderService (symbol, a top-level class))

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.

What this run could not see

• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 58 of 210 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 — 10 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 2a0b37bb6fe5c4efc1e837d2fb321cf0b6960ba4 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 90d52cade4ca636a3786b8535b44b683ba6bb335 — the merge of head 1c64cb68fc46c7a06c587c1611b08707d74e4e05 into base 2a0b37bb6fe5c4efc1e837d2fb321cf0b6960ba4, 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 90d52cade4ca636a3786b8535b44b683ba6bb335 && git checkout 90d52cade4ca636a3786b8535b44b683ba6bb335
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 2a0b37bb6fe5c4efc1e837d2fb321cf0b6960ba4 1c64cb68fc46c7a06c587c1611b08707d74e4e05 && git checkout -B drift-repro 2a0b37bb6fe5c4efc1e837d2fb321cf0b6960ba4 && git merge --no-ff 1c64cb68fc46c7a06c587c1611b08707d74e4e05

node scripts/docs-audit/affected-docs.mjs --json 2a0b37bb6fe5c4efc1e837d2fb321cf0b6960ba4

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

[objectstack-fleet]

domain:server#2 · os-sales · session_01L6bhgUCizoYWQVJWjhdR6F

维护者速读(席位终稿)

• 改了什么:publish-drafts 一批里某个 seed 失败时,seedApplied 回执的 inserted / updated 现在等于失败前实际写入的行数(包括失败那个 seed 抛错前已写的行),error 前面点名停在哪个对象的 seed。哪些 seed 被发布、在失败处停下、不回滚,都和以前一样。
• 为什么改:原先回执硬写 inserted 0 / updated 0,而前面的 seed 已经写了行;回执说「什么都没写」是错数据。
• 风险与回滚:回执形状不变(无 spec 改动);加载器在抛出的错误上记下已写计数(按错误对象存 WeakMap,不从包入口导出)。回滚 = revert 本 PR。
• 先看:packages/metadata-protocol/src/protocol-publish-batch.ts 的 catch 分支;seed-loader.ts 的 seedLoadPartialWrites。
• 两分钟验证:pnpm --filter @objectstack/objectql exec vitest run src/publish-package-drafts-seed-receipt-counts.test.ts,预期 5/5。
• 需要你做的:无。非受管面,席位落地。

席位意见: ACCEPT。按分诊「计数永远描述实际写入」选了真实汇总计数,不扩形状、不改发布与回滚语义。

席位核对

ACCEPT · head 1c64cb68fc46c7a06c587c1611b08707d74e4e05 · 2026-10-30T00:10Z

• 形态: 5 files, about +560/−16: the receipt's catch arm, the loader's partial-writes record and reader, loader tests, an objectql publish test, one changeset. No packages/spec, no governed path; Tier S.
• Clause-②: no, Metadata-protocol: none, patch. The receipt's values become truthful inside the declared seedApplied shape; error gains a prefix naming the failing seed's object; nothing accepted is refused. No contract review owed.
• 前提实测: the new publish test 2 of 4 red on the old code (expected +0 to be 2); ablation 1 (zeros restored) 2 red, ablation 2 (the mid-write seed's count) 1 red, both restored to the HEAD blob; each count checked against the engine's rows.
• 抽查读数: the seat read both hunks: the reader is a WeakMap keyed by the thrown error, unset when the throw came before any write; success stays false; the publish loop and rollback are untouched.
• 门禁 check-runs: 52 on this head: 37 success, 15 skipped, 0 other (read 2026-10-30T00:10Z); mergeable_state: clean. Derived gates 59 (58 exit 0, check:dual-build-cjs-loads carried by CI); metadata-protocol 21805 tests.
• 接受的偏差: the publish test lives in packages/objectql, outside the claim's file surface, because metadata-protocol cannot depend on the real engine (in-memory driver); the loader tests sit in the existing seed-files suite; the container restart split the gate run (the gates the last commit could affect re-ran on 1c64cb68); the report signature line.
• 范围外去向: the runtime publish route's fallback seed apply reports no counts on a throw, but the stock protocol never reaches it; the failing seed is named by object, not seed name (naming by seed would need a protocol.ts change). Both recorded in the PR's acceptance notes; not filed.
• 散文面: changeset and docblocks checked against the diff by the seat.
• 落地条款: relay pr_ready + automerge_enable through the merge queue.