Merge remote-tracking branch 'origin/main' into claude/issue-13457-plugin-permission-load-gate

Author: claude

.changeset/analytics-row-scope-bridge-three-way.md

@@ -0,0 +1,30 @@
+---
+"@objectstack/service-analytics": minor
+---
+
+fix(service-analytics): the ROW-SCOPE bridge to the `security` service tells the same three resolutions apart as the object-level one — a broken security service refuses the query instead of running it with no row policy (#16918)
+
+`AnalyticsServicePlugin` bridges to the `security` service twice: once for the OBJECT-level read grant (`admitObjectRead` → `canReadObject`, #16645) and once for the ROW-level read scope (`getReadScope` → `getReadFilter`, ADR-0021 D-C). The object-level bridge tells three resolutions apart — ABSENT admits, THROWING and METHOD-LESS deny at `error`. The row-scope bridge collapsed all three into one:
+
+```ts
+const trySecurity = () => {
+  try {
+    const svc = ctx.getService<SecurityReadFilter>('security');
+    return svc && typeof svc.getReadFilter === 'function' ? svc : undefined;
+  } catch { return undefined; }
+};
+getReadScope = (object, context) => trySecurity()?.getReadFilter(object, context);
+```
+
+A throwing resolver and a registered service without `getReadFilter` both produced `undefined` — the same value an absent security service produces, and the value `ISecurityService.getReadFilter` reserves for one meaning only: *"this caller has no row restriction on this object"*. So on a deployment whose security service was wired but broken (a boot-order fault, a mis-registered plugin, a failing dependency, a provider that is not the contract it claims to be) analytics queries ran with **no row-level policy at all**, and nothing said so. One door of the file failed closed on a throwing resolver and its neighbour failed open — and the neighbour is the one carrying row-level policy.
+
+**What changes.** The bridge now resolves the same explicit three-way, at the same reporting level:
+
+- **ABSENT** — no `security` service resolved: **unchanged**. No row-scope provider on this deployment, which is a legitimate configuration (a single-tenant kernel that ships no `plugin-security`, where `/data` carries no row-level policy either) and is already reported loudly at init. ⛔ Deliberately not tightened: refusing here would break every such deployment.
+- **THROWING** resolver, or a registered service with **no `getReadFilter`** — the query is **REFUSED**, and the reason is reported at `error` naming the object and which of the two states it was. The refusal is a throw, which `AnalyticsService.resolveReadScopes` — fail-closed since ADR-0021 D-C — already turns into "deny the whole query rather than emit SQL with that object unscoped". A log over an `undefined` would not have been a refusal.
+
+**This change only NARROWS what analytics serves, and only in a state where the security service is broken.** No deployment with a working `security` service, and no deployment with none, changes behaviour by so much as a byte. Nothing that was refused becomes admitted.
+
+**No published-surface delta.** No new error code (the refusal rides the seam's existing fail-closed error), no exported symbol, no key on `AnalyticsServicePluginOptions` or any payload, and no documented envelope changes shape. Graded `minor` rather than `patch` because it is a behaviour narrowing on a published package's read path, matching how its object-level sibling was graded in the same lockstep window.
+
+⚠️ Deliberately **not** answered here: which tenant wall the platform's is (plugin-security's posture-gated Layer 0, or driver-sql's posture-independent auto-scope) — the escalated maintainer decision of triage condition 5. Refusing to serve is neutral between them: it answers *"should we serve at all"*, never *"what shape is the wall"*.

.changeset/error-code-ledger-boot-refusal-prose.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/spec": patch
+---
+
+The error-code ledger's TSDoc stops naming a retired verdict as a live mechanism, and states the published-face rule it is actually held to.
+
+`packages/spec` ships `src/**/*.zod.ts`, so `api/error-code-ledger.zod.ts`'s header is published prose — a consumer reads these sentences out of the tarball. Two of them stopped being true when `check-dispatcher-error-vocabulary`'s face refusal widened from `packages/spec/src/**` to every published package's `src/` and the dispatcher vocabulary's `boot-refusal` verdict retired with it (#16649).
+
+The first said the `boot-refusal` verdict **records** reachability for codes not yet registered, and pointed at the module the verdict was being deleted from. That is a claim about where a live mechanism lives, not about a case that can no longer arise, so a reader following the pointer would have found nothing. It now records the retirement and names what replaced it: a `door: 'none'` code has no resting place short of a row in the ledger.
+
+The second opened `packages/spec/src/** is held to this mechanically`. True before the widening and an understatement after it — a reader would conclude only the spec tree is guarded, which is the "guarded a part" / "guarded it" confusion this whole class of gate exists to remove. It now states the published face, the stricter spec sub-face where `pending-registration` has no allowance, and the named, dated allowance outside it owed to #8846, with both finding kinds named.
+
+No schema, accept set, default or refusal moves. `ERROR_CODE_LEDGER` holds the same members before and after, and the generated reference page is regenerated from this prose rather than hand-edited.

.claude/skills/pm-dispatch/SKILL.md

@@ -86,7 +86,8 @@ PM 的工作是循环:选卡 → 认领 → 派发 → 收集 → 复核 → 报
 - 收班简报是前任不再写的显式声明,是释放标记不是锁:简报即最新事件 ⇒ 立即坐席。
 - 滞后标题是进场顺手修的半状态,⛔ 不是阻塞;简报点名的留守尾巴作围栏。
 - 维护者明示召唤是仲裁:有简报径直坐席;无简报才走保守确认,确认终止即坐席。
-- 互斥清 ⇒ 先在座位贴留一行开轮标记(session ID + fire 时刻)再跑轮。
+- 互斥清 ⇒ fetch 后读三章程文件(本文、core-rules、本席章程)在 `origin/main` 的最新触碰 sha。
+- 异于上一开轮标记即先重读;留开轮标记(session ID + fire 时刻 + 该触碰,注明重读)再跑轮。
 
 ## 全体座位的不变量
 
@@ -283,7 +284,6 @@ PM 的工作是循环:选卡 → 认领 → 派发 → 收集 → 复核 → 报
 - 平台事实变化 → references 事实表改一行。
 - 三类以 `finding` 入 skills 车道由该席分诊;三类之外默认关 not planned。
 - 经验教训散文不再入技能文本;交接按收尾清单逐步走完,并 `list_triggers` 清点自设定时器。
-- 归档自己派出的会话是不可移交的义务。
 - 四段模板、状态词表、接管/退场收尾清单细则见 `references/seat-post-protocol.md`。
 - epic 委托不入座位贴体系;`packages/spec` 恒归 spec 座位。
 

.claude/skills/pm-dispatch/references/core-rules.md

@@ -17,7 +17,7 @@
 - 自设定时器只定下次唤醒、不定轮长;新 fire 到时上一轮未清空即接续,⛔ 不重开不重排。
 - 分诊席跑普通直连会话,达档职责改派显式传档位的子代理;自排下次唤醒不超过 55 分钟。
 - 开轮互斥读四个读数:收班简报、开轮标记、本车道最新他会话认领、最新关闭卡的认领。
-- 未收班活动任一未满一轮即自退,总监席除外;有收班简报即坐席,坐席后先写开轮标记。
+- 未收班活动任一未满一轮即自退,总监席除外;有简报即坐席,坐席后核章程再写开轮标记。
 ## 全体座位的不变量
 - 状态住 GitHub 标签、assignee、正文行与座位贴;⛔ 本地零状态;循环须能从新会话恢复。
 - PM ⛔ 不写文件也不写代码,唯一例外是维护者逐 PR 明示授权的 `.claude/` 内部工具 PR。

content/docs/references/api/error-code-ledger.mdx

@@ -110,22 +110,32 @@ question.
 ONE shape, no second list: a `door: 'none'` code is a row like any other —
 the string under the package that stamps it, and a comment that states its
 `status` and the reachability reading ("no HTTP door on this tree; the
-thrown value is the boundary"). The dispatcher vocabulary's `boot-refusal`
-verdict (`packages/runtime/src/dispatcher-error-vocabulary.ts`) records
-that same reachability for the codes NOT yet registered, and a row here
-ratchets its vocabulary row out exactly as a `pending-registration`
-registration does. What registration changes for such a code is the face,
+thrown value is the boundary"). Until #16649 the dispatcher vocabulary
+(`packages/runtime/src/dispatcher-error-vocabulary.ts`) carried a
+`boot-refusal` verdict that recorded that same reachability for the codes
+NOT yet registered; it is RETIRED, because the gate below now refuses it —
+and every verdict like it — under any published package's `src/`. The one
+verdict that still parks a site there is `pending-registration`, and only
+outside `packages/spec/src/**`, under the dated allowance spelled out below.
+So a `door: 'none'` code has no resting place short of a row here, and the
+ratchet is the one `pending-registration` already had: a row here makes the
+site vanish from that scan. What registration changes
+for such a code is the face,
 not the wire: nothing demotes today, and if a door ever does answer with
 it, `error.code` carries the specific code instead of the status-derived
 member plus `declaredCode`. The `declaredCode` demotion (#9106) stays for
 genuinely unknown / third-party spellings only.
 
-`packages/spec/src/**` is held to this mechanically:
-`check:dispatcher-error-vocabulary` refuses to classify a stamp site under
-that tree as anything but `foreign-vocabulary` (a different vocabulary that
-merely spells itself `code`) or `runtime-pinned` — a `boot-refusal` or
-`pending-registration` row for a spec site is a finding
-(`spec-face-unregistered`), and the only way out is the row here.
+EVERY published package's `src/**` is held to this mechanically — #16649
+widened the rule from `packages/spec/src/**` alone, which is all #16449
+could afford to measure. `check:dispatcher-error-vocabulary` refuses to
+classify a stamp site under one as anything but `foreign-vocabulary` (a
+different vocabulary that merely spells itself `code`) or `runtime-pinned`,
+and the only way out is the row here. Under `packages/spec/src/**` that is
+the whole rule, so a `pending-registration` row for a spec site is a finding
+(`spec-face-unregistered`); outside it, a `pending-registration` row keeps a
+named, dated allowance owed to #8846 and any OTHER verdict is a finding
+(`published-face-unregistered`).
 
 A code emitted by several packages is listed once per emitting package —
 the union dedupes; the per-package rows are provenance, not identity.

packages/runtime/src/dispatcher-error-vocabulary.ts

@@ -186,6 +186,27 @@ export type CodeStampShape =
  */
 export type CodeDoor = 'dispatcher' | 'rest' | 'plugin-route' | 'none';
 
+/**
+ * [#16649] `'boot-refusal'` was HERE, and is retired. It named a refusal raised
+ * before any HTTP boundary exists — the CLI rethrows it and aborts — and until
+ * #16404 the ledger ratified that class as not owed a row
+ * (`MONGODB_MULTI_TENANT_UNSUPPORTED` was UNregistered by #8035 on "host boot
+ * matching is not wire vocabulary"). #16404 deleted the exemption (the ledger
+ * is the published face, door or no door), which left the verdict meaning only
+ * "a registration this tree still owes" — #16449 discharged nine of those,
+ * #16649's first half the remaining fourteen, and the second half widened
+ * `check-dispatcher-error-vocabulary`'s face refusal from `packages/spec/src/`
+ * to every published package's `src/`, which is what makes the verdict
+ * unwritable: a row carrying it inside that face is now a
+ * `published-face-unregistered` finding, and the whole scan population lives
+ * inside it. A union member no site can legally carry is a place to park work,
+ * so it comes out with the widening that closed it.
+ *
+ * ⛔ Do not reintroduce it for the next pre-HTTP producer the scan finds. Its
+ * answer under #16404 is the ledger row, and the gate's `unclassified-site`
+ * text says so. REACHABILITY is still recorded — on the ledger row, as the
+ * `door: 'none'` reading each of the twenty-three registrations carries.
+ */
 export type CodeVerdict =
     /**
      * Reaches a wire and the ledger does not know it. Since #9106 the door
@@ -209,28 +230,6 @@ export type CodeVerdict =
      * draw the same line for field-level and diagnostic codes).
      */
     | 'foreign-vocabulary'
-    /**
-     * A refusal raised before any HTTP boundary exists — the CLI rethrows it
-     * and aborts. Until #16404 the ledger's own note ratified this class as
-     * NOT owed a row (`MONGODB_MULTI_TENANT_UNSUPPORTED` was UNregistered by
-     * #8035 on "host boot matching is not wire vocabulary").
-     *
-     * [#16404] That exemption is gone: the published face is the ledger, and
-     * every code that ships in `dist` is registered there, door or no door.
-     * This verdict now records REACHABILITY only — no door answers with the
-     * code, so registering it changes no HTTP body — and a row carrying it is
-     * a registration OWED, exactly like `pending-registration`: the row
-     * ratchets out when the ledger row lands (#16449 took the nine measured on
-     * that card's tree; #16649 took the fourteen that remained, so on this
-     * tree no row carries this verdict — it stays declared for the next
-     * pre-HTTP producer the scan finds, until the gate's spec-face refusal is
-     * widened to every published package and this verdict retires with it;
-     * see the running log below). ⛔ Under `packages/spec/src/**` the gate refuses
-     * this verdict outright (`spec-face-unregistered`): a spec stamp site is a
-     * ledger member, a foreign vocabulary or a runtime-pinned template —
-     * nothing between.
-     */
-    | 'boot-refusal'
     /**
      * [#9223] The site builds its code by INTERPOLATION, so no source scan can
      * say which codes it produces or whether they are registered — and a named
@@ -320,10 +319,21 @@ export const UNREGISTERED_CODE_SITES: readonly UnregisteredCodeSite[] = [
     // `WALLED_MEMBERSHIP_POLICY_UNDECLARED` (`@objectstack/organizations`) —
     // were registered under their stamping packages and ratcheted out
     // (`stale-row`), the reachability each row recorded now carried on its
-    // ledger row. On this tree NO row carries the `boot-refusal` verdict; a
-    // future pre-HTTP producer the scan finds still lands here as an
-    // `unclassified-site` and takes one, then a registration, then comes out
-    // again. ──
+    // ledger row.
+    //
+    // ── [#16649, second half] The class is now closed MECHANICALLY rather than
+    // by having been emptied once. `check-dispatcher-error-vocabulary`'s face
+    // refusal, which #16449 could only afford over `packages/spec/src/`, covers
+    // every published package's `src/` — the whole of this scan's population on
+    // this tree (52 sites: 47 published-face, 5 spec-face) — so a site here is
+    // a ledger member, a `foreign-vocabulary` or a `runtime-pinned` template
+    // and nothing else, and the `boot-refusal` verdict that used to park one
+    // between is retired from `CodeVerdict` above. The single carve-out is
+    // `pending-registration` outside `packages/spec/src/`, granted 2026-09-08
+    // and owed to #8846; the gate's header dates it and every run prints how
+    // many rows still stand on it. A future pre-HTTP producer the scan finds
+    // lands here as an `unclassified-site` and its way out is the ledger row,
+    // not a row here. ──
 
     // ── runtime-pinned: an interpolated family, checked where it can be ─────
     {

packages/services/service-analytics/src/__tests__/admission-bridge-resolution.test.ts

@@ -113,6 +113,21 @@ async function bootAnalytics(security?: () => unknown) {
   return { service: registered.analytics as AnalyticsService, reads, error };
 }
 
+/**
+ * A working security service's ROW-SCOPE half, carried by every double below
+ * that is meant to represent one.
+ *
+ * `getReadFilter` is a REQUIRED member of `ISecurityService`, and since #16918
+ * the ROW-SCOPE bridge in the same `plugin.ts` refuses the query when the
+ * registered service does not expose it — the sibling three-way of the one
+ * this file measures. `undefined` is that method's documented answer for "no
+ * row restriction on this object", so a double carrying it stays minimal AND
+ * conforming, and every object-level verdict asserted below is reached exactly
+ * as it was before. The deny-path doubles need none: the object-level gate runs
+ * first and refuses before the row half is ever asked.
+ */
+const rowScopeOpen = { getReadFilter: async () => undefined };
+
 const runProbe = (service: AnalyticsService) =>
   service.queryDataset(probe as never, { measures: ['cnt'] } as never, CALLER);
 
@@ -170,7 +185,7 @@ describe('analytics admission bridge — resolving the "security" service', () =
 
   it('asks canReadObject when the service has it, and serves an ADMITTED caller', async () => {
     const canReadObject = vi.fn(() => true);
-    const { service, reads } = await bootAnalytics(() => ({ canReadObject }));
+    const { service, reads } = await bootAnalytics(() => ({ ...rowScopeOpen, canReadObject }));
 
     const result = await runProbe(service);
     expect(result.rows).toEqual([{ cnt: 24 }]);
@@ -190,6 +205,7 @@ describe('analytics admission bridge — resolving the "security" service', () =
 
   it('falls back to explain for a service that predates canReadObject — both verdicts', async () => {
     const admitted = await bootAnalytics(() => ({
+      ...rowScopeOpen,
       explain: async () => ({ allowed: true }),
     }));
     expect((await runProbe(admitted.service)).rows).toEqual([{ cnt: 24 }]);