You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f65c36f
Browse filesBrowse the repository at this point in the historyBrowse files
feat(plugin-webhooks): declared webhook names resolve by (package, name) through the shared resolver (#31744)
<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9B9qYj7GTyDGfaMgXwXx7rZ)_
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.com/claude-code)
https://claude.ai/code/session_01ADHkmR4astMzES5UkW47jW
Co-authored-by: Claude <noreply@anthropic.com>
feat: a declared webhook's name resolves by (package, name) through the shared package-scoped resolver (ADR-0150 D3/D4)
6
+
7
+
Clause-②: no
8
+
Metadata-protocol: none
9
+
10
+
Which declared webhook a name dispatches is now answered by `resolvePackageScopedName` from `@objectstack/objectql`, never by list order. The dispatcher and the by-name reads (activation door, redelivery veto, name guard) read the whole environment's declaration, so each asks as a caller with no package: the environment's own item, else the unique package holder, else a refusal that names every candidate.
11
+
12
+
Who is affected: a deployment that held one declared webhook name in two packages from before phase 1's one-holder refusal (the cold boot warns about it as a "Bare-name conflict at boot"). That webhook was dispatched from whichever package registered first; it is now not dispatched, the refusal is logged once naming both packages, and the by-name reads answer a `409 RESOURCE_CONFLICT` naming them instead of "not declared". Rename one of the two (the boot warning names the rename). First-party count of such clashes: 0. Every other name resolves exactly as before, since phase 1 still refuses a new clash at install.
13
+
14
+
`@objectstack/plugin-webhooks` now depends on `@objectstack/objectql` at runtime (it was a dev dependency).
0 commit comments