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 43fb482
Browse filesBrowse the repository at this point in the historyBrowse files
feat(plugin-sharing)!: declared sharing rules, queues and assignment rules resolve on (package, name) (#31728)
<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi99JCJQQzUUHvZbCS5kKcE7Y)_Fixes#31675
Clause-②: no (narrowing)
Metadata-protocol: none
Skills-docs: follow-up #31735
Narrowing: (1) a bare name of a sharing rule, queue or assignment rule
that two packages declare is refused, naming both (first-party: 0 names
held twice); (2) a package item's bare reference whose only holder is an
environment-authored item, D3 (a) (first-party: 0); (3) a package
caller's bare reference whose one holder is a package outside its
declared closure, per the epic seat's reading 6728487836 (first-party:
0). Sibling in the same release artifact: 0. The one package-written
reference these reads carry is a declared sharing rule's queue
recipient, and no first-party package declares a queue recipient or a
queue. (4) The standing grants of a declared sharing rule name two
packages hold are revoked by the boot orphan sweep, reported as that
refusal (#31677 Q1 ruling A); reachable only through a sealed clash from
before phase 1 (first-party: 0).
## 维护者速读
- 改了什么:共享插件里按名字读「声明的共享规则、队列、分配规则」的地方,全部改走 objectql
的同一个包寻址解析器。一个名字只有一个包声明时,答案和以前完全一样;两个包声明同名时,不再悄悄取第一个(`queuesOf`
原来取最后一个),而是拒绝并列出两个包。声明的共享规则把队列当接收方时,从规则所在的包去解析:本包的队列或它声明依赖的包的队列,范围外或只有环境项持有就拒绝并点名。
- 为什么改:专题 #31527 的子卡 E4(ADR-0150
D3/D4)。两个包同名时取哪个取决于注册顺序,授权和派单因此可能落到错误的包上,而且没有任何提示。
- 风险与回滚:只有「已安装两个包声明同名共享规则/队列/分配规则」的部署会看到变化:那个名字不再生效,日志 warn 一次,按名查询返回
409 列出两个包。第一方实测 0 个。组织自建的
`sys_queue`、`sys_sharing_rule`、`sys_assignment_rule` 行行为不变。回滚即 revert 本
PR。
-
先看:`packages/plugins/plugin-sharing/src/package-scoped-declarations.ts`(唯一的入口,读
R 的解析器);`ownership-queue-service.ts` 的 `resolve` / `declaredQueueNamed`
/ `activeDeclaredQueues`;`sharing-rule-service.ts` 的
`assertQueueRecipientReachable`。
- 两分钟验证:`pnpm --filter @objectstack/plugin-sharing exec vitest run
src/package-scoped-declarations.test.ts`,预期 17 个用例全绿。
- 需要你做的:无,席位落地。
## What changes
Every read in `plugin-sharing` that picks a declared sharing rule, queue
or assignment rule by bare name now goes through one module,
`package-scoped-declarations.ts`. That module reads objectql's
`resolvePackageScopedName` (child R) and resolves nothing itself: no
first-registered fallback, no pick.
- **The population is the listing.** The names asked about are the items
`listItems(type)` lists, which hides a disabled package's items, as
every one of these readers did before. One listed item of a name is that
item, so there is nothing to choose. Two or more go to the resolver as a
caller with no package. These reads are the platform enumerating its
declarations and the Setup doors that switch or guard them, and none of
them belongs to a package (ADR-0150 D3). A registry without the
package-scoped slice (the kernel `metadata` service fallback on a
registry-less host) gets no pick either: two holders listed means a
refusal naming them.
- **Declared sharing rules** (`declared-sharing-rules.ts`): `list()`
serves one rule per name through the module. The old one-rule-per-name
skip kept the first holder silently, on the stated premise that the
registry refuses a second holder, which is false for this uncovered
type. A refused name serves nothing and is logged once at `warn`, naming
both packages. Its grants carry the bare name, so serving either holder
would grant on a guess; the grants it already has are revoked by the
boot orphan sweep and reported as that refusal, naming both. New
`lookup(name)` on the source; `SharingRuleService.declaredRuleNamed`
reads it and throws `PackageScopedNameRefusedError` (`409
RESOURCE_CONFLICT`, every candidate named) on a refusal. That covers the
name guard on `sys_sharing_rule` writes (the name stays taken),
`defineRule`, the activation door's lookup, and `getRule` /
`resolveRules` by name (a refusal, never a misleading 404).
- **Queues** (`ownership-queue-service.ts`): `resolve` (so
`resolveQueue`, `expandMembers`, `isMember`), `declaredQueueNamed` (the
activation door's lookup), and `activeDeclaredQueues` (so `queuesOf`,
`hasAnyQueue`, `queuesNaming`) go through the module. A refused name
resolves nowhere for a `nobody` consumer, which denies. For a `refuse`
consumer it rejects with the resolver's refusal, passed through
unwrapped. It stays a declared name, so no `sys_queue` row may take it
(`isDeclaredQueueName` is unchanged: any holder).
- **Assignment rules** (`assignment-rule-hooks.ts`): the
`sys_assignment_rule` save guard asks the module. One holder gives the
same message as before. Two holders still refuse, and the message now
names both packages.
- **A declared rule's queue recipient** (`sharing-rule-service.ts`,
`assertQueueRecipientReachable`): this is the one reference in these
reads that a package writes, so it resolves from the rule's package P
(ADR-0150 D3): P's own queue, else the unique holder in P's declared
closure plus `sys`. A refusal (outside the closure, D3 (a), or ambiguous
in the closure) throws, so each recompute keeps the rule's grants and
warns, as for a failed read. A name no registry item holds passes
through to an organization's `sys_queue` row, unchanged.
- Changeset: patch for `@objectstack/plugin-sharing`, BREAKING
(narrowing), ADR-0087 `not-required (no-migration-prescription)`.
## Tests
New file `src/package-scoped-declarations.test.ts` (17 cases), built on
the real `SchemaRegistry` (packages through `installPackage`, items
under composite slots):
- `one holder` (3): sharing rule list and by-name, queue resolve, expand
and `queuesOf`, and the assignment guard all answer as before.
- `two holders` (9): the resolver names both; the sharing rule is served
by neither path and reported once; by-name gives 409 naming both; the
name guard still refuses; the queue resolves nowhere and gives 409 under
`refuse`; `queuesOf` serves neither; the door lookup gives 409 and the
name stays declared; the assignment guard names both; the orphan sweep
revokes the name's standing grants and reports them once as the refusal
naming both, apart from a vanished rule's orphans.
- `listing without the slice` (1).
- `queue recipient from the rule's package` (4): outside closure
refused; D3 (a) refused; a declared dependency's queue served; own queue
served.
No existing test was edited. Package suite on head: Test Files 72 passed
(72), Tests 1487 passed (1487).
## Acceptance notes
- **Caller package for queues.** The queue service's contract
(`IOwnershipQueueService`, spec) has no caller-package argument, so
after the P-side check it still resolves the name environment-wide. A
name P's closure reaches once but an unrelated package also holds is
therefore refused, where D3 alone would serve P's reach. That is
stricter, never looser. Threading the caller through the contract is a
spec change. Accepted as an interim by the epic seat (6729421618);
carrier: #31734.
- **Organization-authored rows are not registry items.** `sys_queue`,
`sys_sharing_rule` and `sys_assignment_rule` rows are read as before. D3
(a) applies only to environment-authored registry items (the bare slot).
- **The activation door** (runtime `catalog-activation.ts`, outside this
card's surface) answers a thrown lookup with `503`, quoting the refusal,
which names both packages. Carrier: G1 #31691 (the door's `409`); S1
owns the ledger's package column.
- **Grants of a refused sharing-rule name.** Under the maintainer's
ruling on #31677 Q1 (A: a name two packages hold is refused and
declared) a refused rule is served to nobody, so its standing grants
must not keep answering. The boot orphan sweep revokes them, and reports
it as a refusal, not an orphan: one `warn` per name naming every
candidate package and saying the grants come back once the rule is
addressed by package. Only a vanished rule's grants are counted in the
sweep's orphan line. Reachable only through a sealed clash from before
phase 1; first-party count 0.
## Verification
Head `b24fd3bca` (the Q2 change of the epic seat's revised ruling,
merged with main).
- `pnpm --filter @objectstack/plugin-sharing test` (under
`os-verify-lock`): 72 files / 1487 tests passed; new file 17/17.
`typecheck` exit 0; `eslint --no-inline-config src` exit 0.
- `pnpm build` (whole workspace, under the lock): exit 0. A first
attempt failed in `@object-ui/fields` (`Cannot find module
'@objectstack/formula'`), a dependency main added that this worktree had
not linked; `pnpm install --frozen-lockfile` then the build passed.
- `dispatch-gates --ran`: 72 derived, 72 run, 0 NOT-MEASURED, 0 UNRUN,
every one exit 0.
- Dogfood, full battery on `b24fd3bca` under the lock: Test Files 440
passed, 3 skipped (443); Tests 3652 passed, 41 skipped (3693); VERDICT
command-exit 0.
- CI on `b24fd3bca`: every check run success or skipped (50 runs).
- First-party counts (showcase): 2 declared sharing rules, 0 queues, 0
assignment rules. Names held twice: 0. D3 (a): 0. Outside the closure:
0. Sibling in the same release artifact: 0. Pre-phase-1 sealed clash: 0.
<details><summary>Step 0, main at b126c13: two packages declaring one
name, every reader</summary>
Probe on the same fixture (ALPHA then BETA, each declaring sharing rule
`emea_share`, queue `triage`, assignment rule `route_accounts`), source
restored from `b126c130`:
| Reader | main | this PR |
|:--|:--|:--|
| declared sharing rules `list()` | ALPHA's rule only (first) | neither;
one `warn` naming both |
| `declaredRuleNamed` (name guard, door lookup, `defineRule`) | ALPHA's
rule | 409 `RESOURCE_CONFLICT`, both named |
| sharing name guard on insert | 409 (declared) | 409 (refusal naming
both) |
| `resolveQueue` | ALPHA (first) | `null` |
| `expandMembers` | `["u_alpha"]` | `[]` |
| `expandMembers` under `refuse` | `["u_alpha"]` | 409, both named |
| `declaredQueueNamed` (activation door) | ALPHA | 409, both named |
| `queuesOf(u_alpha)` / `queuesOf(u_beta)` | `[]` / `["triage"]` (LAST
holder's members) | `[]` / `[]` |
| assignment guard | refused, no holder named | refused, both named |
</details>
<details><summary>Ablation: four legs, each red, each restored
(scripts/ablation-replace.mjs)</summary>
The tests import plugin-sharing source directly; objectql (dist) is not
mutated. Each leg: anchor 1 to 0, blob changed, run red, restore proved
by blob == HEAD and an empty `git diff HEAD`.
- A1, the resolver's refusal answered as the first listed holder
(`package-scoped-declarations.ts`): 7 red, every `two holders` refusal
pin. The name-guard pin stays green, as a preservation pin should: the
name is refused either way.
- A2, the listing refusal answered as the first holder: 1 red (`a
listing that cannot be asked …`).
- A3, the P-side queue recipient check skipped: 2 red (outside closure;
D3 (a)).
- A4, the orphan sweep's refusal report removed
(`this.reportSweptRefusal(refusal)`): 1 red (the sweep pin).
</details>
<details><summary>ADR-0150's four readings</summary>
- (a) Phase-1 one-holder tests: no phase-1 file is touched
(`bare-name-one-holder.ts`, its tests, the registry). The three types
here are uncovered by phase 1, and their one-holder answers are pinned
unchanged in the `one holder` block.
- (b) Bare-name behaviour for a name with one holder is unchanged on
every read (`one holder` block), and no URL, MCP or SDK shape changes.
The declared narrowings stand in for two holders, for a holder outside
the rule package's closure, and for an environment-only holder.
- (c) No migration in this PR.
- (d) `Clause-②: no (narrowing)`. No protocol change, so no ADR-0087
entry (changeset marker `not-required (no-migration-prescription)`;
`check-adr-0087-registration` exit 0).
</details>
---
_Generated by [Claude
Code](https://claude.ai/code/session_01ADHkmRDzfKpRLg4QnQqPAz)_
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- signed: domain:server#3 · os-steve ·
session_01ADHkmRDzfKpRLg4QnQqPAz -->
---------
Co-authored-by: Claude <noreply@anthropic.com>
feat(plugin-sharing)!: declared sharing rules, queues and assignment rules are read on (package, name), and a name two packages declare is refused, naming both
6
+
7
+
Clause-②: no (narrowing)
8
+
Metadata-protocol: none
9
+
10
+
<!-- adr-0087: not-required (no-migration-prescription) nothing an author writes is renamed, removed or re-shaped; the change is which declared item a bare name reads at runtime, so there is no stored or authored shape for objectstack migrate meta to rewrite -->
11
+
12
+
**BREAKING**, narrowly, for a deployment that already installs two packages declaring a sharing rule, a queue or an assignment rule under the same name. Who is affected: such a deployment only. Measured first-party: none (the showcase declares two sharing rules, no queue and no assignment rule; no two packages share a name).
13
+
14
+
The three declared types are addressed by `(package, name)` (ADR-0150). Every place the sharing plugin reads one of them by bare name now goes through objectql's shared package-scoped resolver:
15
+
16
+
- A name one package declares answers exactly what it answered before.
17
+
- A name two packages declare used to answer the first package registered, or, for a user's queues and the session's queue flag, the last. It is now refused: the declared sharing rule is not served and grants nothing, the queue resolves nowhere (a refusal naming both packages for a caller that asked for one), and a lookup by that name answers `409 RESOURCE_CONFLICT` naming both packages. The name stays taken: no organization's own rule or queue may take it. The refusal is logged once at `warn`, naming every holder. Grants the name already holds stop answering: the boot sweep of orphaned rule grants revokes them and reports it once as that refusal, naming every holder; they come back once the rule is addressed by package.
18
+
- A declared sharing rule's queue recipient is read from the rule's own package: its own queue, or the one queue its declared dependencies hold. A queue only an unrelated package holds, or only an environment-authored registry item holds, is refused, naming the holder, where it used to be served. An organization's own queue (a `sys_queue` row) is served as before.
19
+
20
+
What to do if you see the refusal: keep one of the two packages' items under that name. If a declared rule's queue lives in another package, declare a dependency on that package.
@@ -151,14 +167,27 @@ export async function assignmentRuleRowIssues(
151
167
code: 'invalid_format',
152
168
message: `An assignment rule name is a machine name — lowercase letters, digits and underscores, starting with a letter (got ${JSON.stringify(name)}).`,
0 commit comments