[objectstack-fleet]

Requested by Steve · project thread

Part of #31677

Clause-②: no
Metadata-protocol: none
Narrowing: D3 (a) declared by the card, measured 0 here (no reader in this PR has a caller package; first-party package-caller reads wired: 0, so the closure-outside sub-case of #31527 comment 6728487836 measures 0, sibling-in-the-same-artifact included). Beside it, ruled on #31677 (Q1 letter A, 6729831159): a declared webhook name two packages held from before phase 1 (the cold-boot seal's warn list) is refused like every other two-holder name instead of being dispatched from the first-registered package. First-party count: 0 (HotCRM 6961ab1, ADR-0150's census).

Part of epic #31527 (ADR-0150 child E5), webhooks half. Connectors landed in #31725. The email template half stays open on #31677 until R2 #31716 stops the resolver from counting a dependent's added locale (#28802) as a second holder.

Card thread domain:server#3 · os-steve · session_01ADHkmR4astMzES5UkW47jW; claim 6728454873, file-surface amendments 6728498905 and 6728849524 (Q4: plugin-webhooks/vitest.config.ts).

维护者速读

• 改了什么：声明式 Webhook 的派发和按名读取（激活入口、重投否决、名字守卫）不再按列表顺序取第一个，改为问 R 的共享解析器 resolvePackageScopedName（无包调用方）：先环境自建项，再全环境唯一的包持有者，否则拒绝并列出全部候选。
• 为什么改：ADR-0150 把 Webhook 改为按（软件包, 名称）寻址；以前两个包同名时静默派发先注册的那个。
• 风险与回滚：只影响阶段一之前就已经有两个包同名的部署（启动时已有「Bare-name conflict at boot」警告），按维护者裁决 A，该 Webhook 不再派发，日志点名两个包，按名读取答 409；第一方计数 0。其余名字答案不变。回滚即还原本 PR。
• 先看：packages/plugins/plugin-webhooks/src/declared-webhooks.ts 的 chooseDeclaration、parseDeclared 与 declaredWebhookNamed；dogfood bare-name-one-holder-flow-family.dogfood.test.ts 中改动的两处断言。
• 两分钟验证：pnpm --filter @objectstack/plugin-webhooks exec vitest run src/declared-webhooks.test.ts -t "ADR-0150"，预期 4 条通过，其中两个包同名的用例断言不派发、日志一次点名两个包、按名读取抛 409。
• 需要你做的：无，席位落地。

What changes

Every reader here that turns a declared webhook name into one item now asks the ONE package-scoped resolver (resolvePackageScopedName, @objectstack/objectql, R #31637) and never picks by list order. Each reader is context-free, so it asks as a caller with no package (ADR-0150 D3): the environment's own item, else the unique package holder, else a refusal naming every candidate.

Reader on main, by symbol	Pick today	Caller package	After this PR
DeclaredWebhookSource.parseDeclared → list() (the AutoEnqueuer dispatcher)	first listed item per name	none	resolver item; a refused name is not dispatched and is logged once naming every candidate
declaredWebhookNamed (redelivery veto judgeDeclared, runtime catalog-activation.ts webhook lookup, bindDeclaredWebhookNameGuard)	first listed match	none	same answer; a refused name throws DeclaredWebhookAmbiguousError (409 RESOURCE_CONFLICT, candidates), so no door reads "not declared" for it
metadata-service reader (a host whose registry holds no webhook)	first listed item	none	one item per name serves; a name listed twice is refused the same way

Not touched: readDeclaredWebhookNames (the boot report lists names only, picks no item). The runtime activation door maps the reader's throw to its existing 503 "could not be read" answer, naming the candidates, and writes nothing; mapping it to 409 is the runtime door's (G1 #31691).

@objectstack/objectql moves from devDependencies to dependencies (claim amendment 6728498905). No cycle: objectql's workspace closure (deps, devDeps and peers, 14 packages) does not contain plugin-webhooks.

Forced test change (the ruled narrowing): packages/qa/dogfood/test/bare-name-one-holder-flow-family.dogfood.test.ts pinned declaredWebhookPackage(HOOK) === 'com.qa.bare.alpha' (phase 1's first-registered answer for the clash two AppPlugin packages hold at cold boot) in two tests. Both now pin the refusal instead: the by-name read throws 409 RESOURCE_CONFLICT with candidates com.qa.bare.alpha and com.qa.bare.beta, and the message names both. Nothing else in that file changed.

ADR-0150's four readings

• (a) phase-1 one-holder tests stay green. objectql's four registry-bare-name-one-holder* suites plus package-scoped-resolver.test.ts: 187 passed (untouched by this PR). The four bare-name-one-holder* dogfood files run in the targeted subset below, with the moved pin.
• (b) bare-name behaviour unchanged for every name with one holder. declared-webhooks.test.ts pins the one-holder case on a real SchemaRegistry (dispatches and carries its package), and the package's full suite stays green. The one change is the ruled narrowing above. No URL, MCP or SDK surface moves.
• (c) no migration. Nothing stored is read or written differently.
• (d) Clause-②: no, Metadata-protocol: none; no ADR-0087 entry.

Tests

plugin-webhooks/src/declared-webhooks.test.ts, new describe "a name resolves by (package, name) (ADR-0150 D3)": one holder dispatches; two holders dispatch nothing and warn once naming both; the by-name read throws the 409 naming both and the redelivery veto propagates it; a registry-less double listing a name twice reads as a refusal. vitest.config.ts gains env: { OS_REGISTRY_LOG: 'warn' } (the suite now builds a real SchemaRegistry; check:registry-log-declared).

Ablations (scripts/ablation-replace.mjs, mutation proved on disk, restored to the HEAD blob, git diff HEAD empty after each; the suite imports src, so no dist leg; measured at da3bc28e, whose declared-webhooks.ts / .test.ts are byte-identical to this head):

Ablation	Result
a refused name answers listed[0]	2 failed: "neither is dispatched…", "the by-name read throws the 409…"
registry-less: listed.length >= 1 serves listed[0]	1 failed: expected [ { webhook: … } ] to deeply equal []

The dogfood pin's other side: the same two assertions read com.qa.bare.alpha on main (they were green there), so on main's reader the new refusal assertion is undefined and red.

Verification

Head 7d39171 (on main 1a2361c + f2abd47, after #31725 and #31730):

• @objectstack/plugin-webhooks test exit 0 (25 files, 262 tests), typecheck exit 0, under os-verify-lock (one && command, VERDICT command-exit 0). Root eslint --no-inline-config over packages/plugins/plugin-webhooks and the edited dogfood file: exit 0 (the package has no lint script).
• Targeted dogfood after turbo run build --filter='@objectstack/dogfood^...' (70/70): 19 files (the four phase-1 bare-name families including the moved pin, email template boot/materialization/locale files, connector install/restart/package-ref files, declarative MCP, webhook materialization), 96 tests passed, VERDICT command-exit 0.
• Derived gates: dispatch-gates --commands derived 86 families at 7d39171; 85 exit 0 on the first pass; check:dual-build-cjs-loads exited 3 (its own "Run pnpm build first … nothing was measured": it ran before a package's dist existed) and exit 0 on the rerun ("122 published require entry point(s) across 72 package(s) load"). --ran: "86 derived, 86 run, 0 NOT-MEASURED, 0 UNRUN" (a derived zero). check:registry-log-declared is green with the vitest config change.
• test:repo not run locally (CI's Test Core); this diff touches no repo-project test.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ADHkmR4astMzES5UkW47jW

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-webhooks, touching 13 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/plugins/plugin-webhooks/package.json, packages/plugins/plugin-webhooks/vitest.config.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

27 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 90cea476dedee4bb2586f60b4f469bba67904cf3.

⛔ 11 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/plugins/plugin-webhooks/package.json, packages/plugins/plugin-webhooks/vitest.config.ts) — pages documenting those are invisible to this run
• 4 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 65 of 231 client-bound route-ledger rows — the other 166 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 166: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 59 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 107 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 — 5 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 90cea476dedee4bb2586f60b4f469bba67904cf3 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 90cea476dedee4bb2586f60b4f469bba67904cf3

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

[objectstack-fleet]

epic:#31527#1 · os-steve · session_01ADHkmP7o3uDTti21wLTfPf

Epic red-line review: E5 #31677, webhooks half, head 7d39171 · 2026-11-09T01:51Z

Verdict: PASS.

Red line	Reading
1. Never loosens	The dispatcher and the by-name reads ask resolvePackageScopedName as a caller with no package. A refused name is not dispatched. When the registry is absent, a name listed under two holders is refused and one listed item answers as before. The old "first registration wins" skip is gone.
2. Ambiguity reported, never guessed	The single resolver answers. A refusal is warned once naming every candidate, and the by-name read throws DeclaredWebhookAmbiguousError (409 RESOURCE_CONFLICT, candidates). There is no first-registered fallback.
3. Independently releasable	Per #31677 Q1 Ruled A (6729831159), phase 1's dogfood pin declaredWebhookPackage(HOOK) === alpha moves to the refusal, and the Narrowing: line declares the sealed clash beside D3 (a), first-party 0. The diff against current main touches only plugin-webhooks, the dogfood pin and the changeset; #31725 and #31730 are already on main. Gates 86/86.

The D9 backstop obligation recorded for connectors (6729233545) applies to webhooks as well: when B #31699 narrows phase 1, a composition with no resolver slice must fail closed.

Email stays on R2 #31716 (Q2). Seat 3 accepts and lands this after green CI. It is not a governed surface.

[objectstack-fleet]

domain:server#3 · os-steve · session_01ADHkmQXLfvyB5R53VDm3Ka

席位核对 · ACCEPT · #31744 (Part of #31677, ADR-0150 E5 webhooks) · 2026-11-09T02:16Z

Head-sha: 7d39171db1c4e92ac8f7e877c7ac0cb2eb315d47

• Form: draft to main; first body line Part of #31677; no closing keyword in the body (read). The card stays open for the email half (waits on R2 objectql: the package-scoped resolver takes holders from a source other than SchemaRegistry, so engine functions resolve by their referrer's package (ADR-0150 child R2) #31716).
• Premise measured: the declared-webhook reader asks resolvePackageScopedName as a caller with no package; src is byte-identical to da3bc28e, whose four ablations were each red then restored (report 6728837711); phase 1's dogfood pin declaredWebhookPackage(HOOK) === alpha moved to the refusal (409, candidates alpha and beta), the one forced test edit, named in the body.
• Gates (check-runs on this head): 67 runs, 58 success, 9 skipped, 0 other. check-governed-merges --pr 31744: NOT governed, 325 changed lines. K = 1.
• Dogfood battery (narrowing): full battery on this head under the lock, VERDICT 0, 440 files / 3652 tests passed (report 6730636544).
• Narrowing: D3 (a), and the pre-phase-1 sealed clash ruled on webhooks, connectors, email templates on (package, name) (ADR-0150 child E5) #31677 (Q1 letter A, 6729831159), first-party 0 each.
• Accepted deviations: vitest.config.ts outside src/** (seat answer 6728849524, Q4).
• Epic red-line review: PASS 6730349344 at this head; the missing-slice fail-closed obligation is recorded on B objectql: narrow the phase-1 one-holder refusal from environment to namespace for webhook, connector and email_template (ADR-0150 child B, webhook family) #31699.
• Landing: ready + auto-merge in this stroke. On merge: a landing note on webhooks, connectors, email templates on (package, name) (ADR-0150 child E5) #31677; pm:dispatched stays until the email half lands.