@sema-agent/server 1.322.0 → 2.0.0

package/dist/security.js

@@ -1,16 +1,47 @@
 import { uuidv7 } from "@sema-agent/core";
 import { PROJECT_ID_REGEX } from "@sema-agent/registry-core";
+// design/158 A4: the env→key-set decoders (parseApprovalHmacKeys / parsePrincipalJwks + their row types) moved to
+// the leaf ./auth-keys.js so config.ts's env-load no longer value-imports this whole auth module (lens2 §F). The
+// verifiers that consume the parsed key-sets now live in ./approval-hmac.js / ./principal-jwt.js (design/158 A13);
+// the four names are RE-EXPORTED for compat.
 export { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js";
-import { memoryScopeFor } from "./memory-scope.js";
+import { memoryScopeFor } from "./memory-scope.js"; // design/158 N17: see re-export block below (moved to ./memory-scope.js)
+// design/158 A13: the approval-envelope HMAC (integrity) group and the principal-JWT/direct-door (identity)
+// group moved VERBATIM to ./approval-hmac.js and ./principal-jwt.js respectively — this file's own
+// `verifiedPrincipal` still calls verifyPrincipalJwt for the direct-door branch (value import below); every
+// symbol from both groups is re-exported near the bottom of this file so existing importers keep working.
 import { verifyPrincipalJwt } from "./principal-jwt.js";
+/** The shape core's `uuidv7()` mints: canonical 8-4-4-4-12 lowercase hex with version nibble `7` and the RFC-4122
+ *  variant (`8`/`9`/`a`/`b`). Used to shape-validate a caller-supplied session id on the §0.5 fork/delete routes so
+ *  a crafted id (LIKE metacharacters, over-long, non-canonical) is rejected up front — a SECOND layer behind the
+ *  tool-result LIKE-escape, not the only one. NB: deliberately NOT enforced on the task-submission `body.sessionId`
+ *  path (the authorizer) — historical callers/tests pass arbitrary short ids there, and the LIKE-escape +
+ *  VARCHAR(64) column already neutralize the metacharacter risk; tightening that path is a separate, breaking change.
+ *  ASYMMETRY (GAP #15, INTENTIONAL): a client MAY create a session via submit with an arbitrary id (e.g. run-local
+ *  `--session foo`, dev anonymous-share ids) yet then CANNOT fork/delete it (those routes 400 a non-uuidv7 id). This
+ *  is by design — the wire contract types sessionId as an opaque string, so submit stays permissive; fork/delete add
+ *  the uuidv7 gate only as defense-in-depth for store ops on a caller-supplied `:id`. Do NOT add a uuidv7 check to
+ *  submit (breaks the contract + run-local + single-tenant dev). The ONE submit-side guard that IS safe and present
+ *  is a LENGTH cap (≤64, the column width) in prepareSpec — see server.ts `body.sessionId` check — which prevents a
+ *  500/truncation at the INSERT without constraining the id shape. */
 const UUIDV7_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+/** True iff `s` matches the canonical uuidv7 shape core mints (see {@link UUIDV7_RE}). */
 export function isUuidV7(s) {
     return UUIDV7_RE.test(s);
 }
+/** Canonical uuid of ANY version (v4 legacy shell sessions included) — the SYNC
+ *  face's shape gate. Sync stays stricter than submit (arbitrary ≤64 ids) because it is a bulk write
+ *  face: the shape still shuts out crafted ids (LIKE metacharacters, over-long), but no longer strands a
+ *  v4-keyed legacy session as unsyncable (it was CREATABLE via the lenient submit yet REJECTED by the v7-only
+ *  sync gate — a real contradiction). fork/purge/policy keep the v7-only gate (ids we mint ourselves). */
 const UUID_ANY_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 export function isUuidShape(s) {
     return UUID_ANY_RE.test(s);
 }
+/** An HTTP error the server maps to a status code (instead of a generic 500). `code` (optional) is a stable
+ *  machine-readable identifier the HTTP layer echoes as `{code}` beside the human `{error}` message — the
+ *  "typed rejection" posture (structured code on the wire, prose stays with the shell/web).
+ *  `extra` (optional) is folded into the error body verbatim (e.g. the scenario allowlist on a reject). */
 export class HttpError extends Error {
     status;
     code;
@@ -25,12 +56,37 @@ export class HttpError extends Error {
             this.extra = opts.extra;
     }
 }
+/**
+ * S6 — close the "sessionId / scope are bearer capabilities" hole.
+ *
+ * The principal is read from a trusted header set by the authenticated caller (e.g. the OA backend
+ * that already holds the service token). It is NOT taken from the request body, so a caller cannot
+ * forge identity by passing `scope`/`sessionId` for another tenant.
+ *
+ * Then:
+ *   - a supplied `sessionId` is ownership-checked against `session_meta.owner` (403 on mismatch);
+ *     an unknown id is claimed for this principal; a missing id mints a fresh owned session;
+ *   - the memory scope is derived from the principal.
+ *
+ * Returns a function shaped for `ServiceDeps.authorize`. When `sessionStore` is not the TiDB store
+ * (e.g. in-memory dev backend) ownership can't be enforced, so it only derives principal + sessionId.
+ */
 export function createAuthorizer(config, sessionStore) {
     return async ({ req, body }) => {
+        // F-fix (direct-door principal spoofing, core-steered): the authoritative identity for governance + cost +
+        // ownership + memory + checkpoint scope is the VERIFIED principal, never the spoofable header. This swap covers
+        // every consumer that flows THROUGH the authorizer (spec.principal + cost/owner/memory/checkpoint scope); the
+        // non-authorizer owner/cost sites (runOwnerOk / quotaExceeded / leader / idemKey / the run-route + worker-global
+        // presence gates) call `gatedPrincipal` directly, same invariant. BFF/gated = unchanged (no-op there).
         const principal = verifiedPrincipal(req, config);
         if (config.requirePrincipal && !principal) {
             throw new HttpError(401, `missing principal header '${config.principalHeader}'`);
         }
+        // 142-S4 projectId 线程化(design/142 §2 行为面):body.projectId 是「哪个项目」的选择器,不是身份 —
+        // scope 的 tenant 段永远来自 verified principal(上面),所以它过 SHAPE 门即可(PROJECT_ID_REGEX,
+        // registry-core 0.10.0 与 center 登记簿同一词法;generic lowercase UUID)。不合形状 = 422 typed
+        // fail-loud(注入串/大小写/任意路径段绝不进 scope 键或 config.projects 查表)。RESUME 腿不过此门
+        // (checkpoint 重建 auth 不跑 authorizer)— 持久化 body 在原始提交时已验过,形状不变。
         let projectId;
         if (body.projectId !== undefined) {
             if (typeof body.projectId !== "string" || !PROJECT_ID_REGEX.test(body.projectId)) {
@@ -38,6 +94,16 @@ export function createAuthorizer(config, sessionStore) {
             }
             projectId = body.projectId;
         }
+        // design/114 Phase3 (reuse-path warm-resume): the caller requires the session to ALREADY exist. The authorizer
+        // must NOT claim-create a missing id — that would materialize an empty session_meta row and DEFEAT core's
+        // acquire({requireExisting}) fail-loud, silently turning a resume of a PURGED/EXPIRED session into a fresh empty
+        // run (the exact "looks warm, actually fresh" bug the flag prevents). So with it set: a missing requested id
+        // FAILS LOUD with a clean 404 HERE (eager — before any SSE headers, so BOTH the sync and stream legs get a real
+        // status, not an SSE-buried error) and is NEVER claim-created; a request with NO sessionId is a caller error (the
+        // authorizer would otherwise mint a fresh id — there is no existing session to resume). This is the SERVICE-side
+        // complement to core's store-level fail-loud (which still covers run-local / no-ownerOf backends / direct core):
+        // without it the store never SEES a missing session (the authorizer pre-registers it), so store honoring alone is
+        // inert on the HTTP path.
         const requireExisting = body.requireExistingSession === true;
         const ownerOf = sessionStore.ownerOf?.bind(sessionStore);
         const register = sessionStore.register?.bind(sessionStore);
@@ -48,11 +114,26 @@ export function createAuthorizer(config, sessionStore) {
                 let owner = await ownerOf(requested);
                 if (owner === undefined) {
                     if (requireExisting) {
+                        // design/114 Phase3: the session is genuinely missing (no owner row) AND the caller requires it to
+                        // EXIST → FAIL LOUD with a clean HTTP 404 on BOTH the sync AND the streaming leg. The authorizer runs
+                        // (in prepareSpec) BEFORE any SSE headers are committed, so the stream leg gets a real status code — not
+                        // a `resume.session_not_found` buried in an SSE `done` payload, which a 200-committed stream cannot
+                        // upgrade. We must NOT claim-create it either (that would defeat the fail-loud). The durable stores ALSO
+                        // honor `{requireExisting}` (run-local / a no-ownerOf memory backend / direct core), so the fail-loud
+                        // still holds on the paths that never reach this authorizer.
                         throw new HttpError(404, "requireExistingSession: session does not exist (resume.session_not_found)");
                     }
-                    await register(requested, principal ?? null);
+                    await register(requested, principal ?? null); // unknown id → claim for this principal
+                    // Re-read the authoritative stored owner: register is an idempotent upsert that keeps the
+                    // FIRST owner, so a concurrent first-claim of the same id by another principal could have won
+                    // the race. Without this re-check the loser would silently attach to the winner's session.
                     owner = await ownerOf(requested);
                 }
+                // Enforce ownership whenever the session HAS an owner — including against callers that present
+                // no principal (audit B, security.ts:77): with the old `principal &&` guard, a caller that
+                // omitted the header under requirePrincipal=false could attach to ANY owned session by id.
+                // Anonymous callers may still attach to anonymous (owner=null) sessions, so single-tenant dev
+                // (no principals anywhere) is unaffected; flipping the requirePrincipal default is NOT needed.
                 if (owner != null && owner !== principal) {
                     throw principal
                         ? new HttpError(403, "session does not belong to this principal")
@@ -62,6 +143,8 @@ export function createAuthorizer(config, sessionStore) {
             sessionId = requested;
         }
         else {
+            // design/114 Phase3 (M2 parity): requireExistingSession with NO sessionId is a caller error — the authorizer
+            // mints a fresh id otherwise, so core's own no-sessionId M2 check can never fire on the service path.
             if (requireExisting) {
                 throw new HttpError(422, "requireExistingSession requires a sessionId — there is no existing session to resume (resume.session_not_found)");
             }
@@ -72,27 +155,66 @@ export function createAuthorizer(config, sessionStore) {
         return { principal, sessionId, memoryScope: memoryScopeFor(config, principal, projectId), resolvedProjectId: projectId };
     };
 }
+/** F1/F3 (codex scope-ledger audit 2026-07-14) — the auth-boundary principal SHAPE gate, applied to every
+ *  verified identity source (trusted header, SSO-bridge sub, direct-door JWT sub) so no downstream consumer
+ *  ever sees an ambiguous or over-wide principal:
+ *   - RESERVED internal identifiers are REJECTED (修1, 三路复审 A 组 HIGH — see {@link RESERVED_PRINCIPALS} /
+ *     {@link RESERVED_PRINCIPAL_PREFIXES} below): a REAL tenant whose principal string-equals an internal scope
+ *     sentinel would pass the plain string-compare owner/scope gates downstream and merge with internal rows —
+ *     e.g. `"_"` merges with the anonymous scope family (the checkpoint scope column `auth?.principal ?? "_"`
+ *     at suspend, and the decide owner-gate treats `cp.scope === "_"` as anonymous-OPEN, server.ts ~L3710; the
+ *     SendUserFile ledger scope + the /v1/sendfile-links fleet-wide default; the resource-suspend isolation
+ *     key), `"_leader"` merges with the leader durable-approval owner scope (a tenant so named could list/
+ *     decide internal leader approvals), `"_leader-…"` with the leader resource-suspend scope family, and
+ *     `"__none__"` with the missing-principal placeholder scope on the decide/pending gates.
+ *   - length > 190 is REJECTED: every scope/owner column the principal lands in VERBATIM is VARCHAR(190)
+ *     (sendfile_link.scope, approval.owner/scope, memory-engine scope, rate-limit keys, …) — an over-long
+ *     principal would truncate/500 at the INSERT and split one identity into two.
+ *  Throws a typed 400 `HttpError` (the HTTP layer maps it); the message names the rule (a reserved identifier /
+ *  the length cap), never a secret and never the internal scope's semantics. */
 export const PRINCIPAL_MAX_LENGTH = 190;
+/** 修1 — the SINGLE registry of internal sentinel/scope identifiers a tenant principal must never equal.
+ *  🔴 新增内部 sentinel scope 必须在此登记(精确值加 RESERVED_PRINCIPALS,前缀族加
+ *  RESERVED_PRINCIPAL_PREFIXES),否则 assertPrincipalShape 会放行同名租户 = 与内部 scope 行合流的越权面。
+ *  Current entries (where each is minted): `"_"` = single-user/anonymous sentinel (checkpoint/sendfile/
+ *  resource-suspend scope family); `"__none__"` = missing-principal placeholder on the decide/pending gates
+ *  (http/server.ts `principal ?? "__none__"`); `"_leader"` = leader durable-approval scope
+ *  (src/leader/wire.ts); prefix `"_leader-"` = the leader resource-suspend scope family
+ *  (`_leader-resource-<workerId>`, src/leader/wire.ts). NB the prefix REQUIRES the hyphen — a tenant named
+ *  `_leaderX` collides with nothing internal and stays valid (boundary pinned by test). */
 export const RESERVED_PRINCIPALS = ["_", "__none__", "_leader"];
 export const RESERVED_PRINCIPAL_PREFIXES = ["_leader-"];
 export function assertPrincipalShape(principal) {
     if (RESERVED_PRINCIPALS.includes(principal) || RESERVED_PRINCIPAL_PREFIXES.some((p) => principal.startsWith(p))) {
+        // Wording deliberately names the RULE (reserved internal scope sentinel), not what the sentinel does.
         throw new HttpError(400, `principal ${JSON.stringify(principal)} is reserved (an internal scope sentinel) — authenticate with a real tenant identifier`, { code: "principal_reserved" });
     }
     if (principal.length > PRINCIPAL_MAX_LENGTH) {
         throw new HttpError(400, `principal exceeds ${PRINCIPAL_MAX_LENGTH} characters (the scope-column width every store pins, e.g. sendfile_link.scope VARCHAR(190)); got ${principal.length}`, { code: "principal_too_long" });
     }
 }
+/** Read the authenticated principal from the trusted header. Never from the body. */
 export function principalFrom(req, config) {
     if (!config.principalHeader)
-        return undefined;
+        return undefined; // no header configured → no principal (defensive; real config always sets it)
     const raw = req.headers[config.principalHeader.toLowerCase()];
     const principal = (Array.isArray(raw) ? raw[0] : raw)?.trim() || undefined;
     if (principal !== undefined)
-        assertPrincipalShape(principal);
+        assertPrincipalShape(principal); // F1/F3: reserved-sentinel + length gate at the boundary
     return principal;
 }
+/** Header carrying the crypto-verified principal JWT on a direct-door worker (the issuer signs it; the worker only
+ *  verifies). The trusted twin of `config.principalHeader` (the latter is client-spoofable on a direct door). */
 export const PRINCIPAL_TOKEN_HEADER = "x-approval-principal-token";
+/** The DIRECT-DOOR-SAFE principal — the VERIFIED identity for governance + cost + isolation. On a BFF/gated deployment
+ *  the header is already verified upstream (return it); on a direct-door worker the `principalHeader` is client-
+ *  spoofable, so identity comes from the crypto-verified `x-approval-principal-token` JWT (the issuer's private key
+ *  never lives on a worker). `spec.principal` MUST be this, NEVER `principalFrom` — keying a gate or a bill on a
+ *  spoofable header is a multi-tenant governance/cost bypass (core's TaskSpec.principal contract). Single source for
+ *  `createAuthorizer` AND every `gatedPrincipal` call site (F-fix: direct-door principal spoofing, core-steered). */
+/** 鉴权桥:请求入口 async 预认证把验过的 registry-JWT principal 挂在这个 symbol 上——它是
+ *  request-local 真源(来自签名,非自报头),优先于任何头读取。setSsoPrincipal 在 server.ts 的入口块设,
+ *  verifiedPrincipal 在此读。 */
 const SSO_PRINCIPAL = Symbol.for("sema.ssoVerifiedPrincipal");
 export function setSsoPrincipal(req, principal) {
     req[SSO_PRINCIPAL] = principal;
@@ -101,6 +223,9 @@ export function ssoVerifiedPrincipal(req) {
     const v = req[SSO_PRINCIPAL];
     return typeof v === "string" && v.length > 0 ? v : undefined;
 }
+/** 鉴权桥 scope 透传:registry-JWT 的 `scope` claim(多租户活动租户,registry-core 0.3.0+
+ *  `VerifiedIdentity.scope`)也挂 request-local——与 principal 同真源(来自签名,非自报头)。用途=可观测/审计
+ *  归因,以及未来 scope 级 quota/过滤的读取地基(单一真源)。ABSENT = pre-scope/默认 token,语义"global"。 */
 const SSO_SCOPE = Symbol.for("sema.ssoVerifiedScope");
 export function setSsoScope(req, scope) {
     req[SSO_SCOPE] = scope;
@@ -110,13 +235,15 @@ export function ssoVerifiedScope(req) {
     return typeof v === "string" && v.length > 0 ? v : undefined;
 }
 export function verifiedPrincipal(req, config) {
+    // 鉴权桥优先:registry-JWT 验过的 principal 来自签名,在 directDoor 与 BFF/gated 两种部署都胜出
+    // (directDoor 下原走 x-approval-principal-token,SSO principal 在其之前返回,成为下游的可信身份)。
     const sso = ssoVerifiedPrincipal(req);
     if (sso) {
-        assertPrincipalShape(sso);
+        assertPrincipalShape(sso); // F1/F3: the SSO-bridge sub is a verified identity source too — same boundary gate
         return sso;
     }
     if (!config.directDoorActive)
-        return principalFrom(req, config);
+        return principalFrom(req, config); // BFF/gated: the header is already verified upstream
     const h = req.headers[PRINCIPAL_TOKEN_HEADER];
     const token = (Array.isArray(h) ? h[0] : h) ?? "";
     const sub = verifyPrincipalJwt(token, config.principalJwtPubkeys, {
@@ -124,11 +251,23 @@ export function verifiedPrincipal(req, config) {
         aud: config.principalJwtAud ?? "\0",
         maxTtlSec: config.principalJwtMaxTtlSec,
     })?.sub;
+    // F1/F3: gate the direct-door JWT sub as well — a typed 400 naming the rule beats a silent-null 401 (the
+    // minter must not be able to issue a "_"-sub token that merges with the anonymous scope family downstream).
     if (sub !== undefined)
         assertPrincipalShape(sub);
     return sub;
 }
+// design/158 N17: memoryScopeFor / memoryEngineRemoteLanePosture / memoryEngineBackendFor / memorySpecForRequest
+// moved VERBATIM to the leaf ./memory-scope.js (security.ts's name says auth; these four resolve memory-plane
+// config, unrelated). Re-exported here so existing importers (main.ts, config.ts, http/server.ts, run-local.ts,
+// index.ts, tests) keep working untouched — this file's own createAuthorizer below still calls memoryScopeFor.
 export { memoryScopeFor, memoryEngineRemoteLanePosture, memoryEngineBackendFor, memorySpecForRequest } from "./memory-scope.js";
+// design/158 A13: approval-envelope HMAC (integrity, {@link verifyApprovalHmac}/{@link approvalHmacMessage}/
+// MAX_APPROVAL_REASON_CHARS) and principal-JWT/direct-door proof (identity, {@link verifyPrincipalJwt}/
+// approvalBnd/verifyDirectDoorProof) moved VERBATIM to ./approval-hmac.js and ./principal-jwt.js — this file
+// keeps only the authenticator/principal-shape/SSO-mount group (createAuthorizer, verifiedPrincipal,
+// assertPrincipalShape, principalFrom, setSsoPrincipal/setSsoScope) plus this re-export so existing
+// importers of the moved names keep working unchanged.
 export { approvalHmacMessage, MAX_APPROVAL_REASON_CHARS, verifyApprovalHmac } from "./approval-hmac.js";
 export { verifyPrincipalJwt, approvalBnd, verifyDirectDoorProof } from "./principal-jwt.js";
 //# sourceMappingURL=security.js.map

package/dist/sema-registry.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Sema-registry adapter — pull the effective config from sema-registry and apply it OVER the
+ * env-derived defaults (env = fallback, center = override). Follows the "universal internal
+ * schema → translate at the boundary" pattern, with our security boundary kept:
+ *
+ *   - the CENTER owns the LOGICAL config: the model roster (names/capabilities/tier), the role map,
+ *     and team templates;
+ *   - the SERVICE env still owns the SECRETS: API keys stay in env (the center never stores a secret);
+ *     keys are per-model via `apiKeyEnv` → `config.modelApiKeyEnv` → the spec's `getApiKeyAndHeaders`
+ *     (core 1.45), so each model/cascade-rung authenticates with its own upstream key.
+ *
+ * Per-model `baseUrl` IS transported (a catalog model may live on a different gateway;
+ * core brain honors model.baseUrl, absent = "" = boot-env endpoint). TODO remaining: hot-reload
+ * of models/roles needs Runner support — today teams hot-reload via the registry, while a models/roles
+ * change is logged as "restart to apply".
+ *
+ * (design/158 A13, internal-lossless) This module is now a FACADE: the implementation lives in
+ * `src/config-center/` split by responsibility group (HTTP client / EffectiveConfig application /
+ * restart-signal detection / skills+MCP consumption). Every symbol below is re-exported UNCHANGED —
+ * existing `from "./sema-registry.js"` / `from "../sema-registry.js"` imports need zero changes.
+ */
 export { fetchEffective, fetchPrincipalCaps, ConfigCenterHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./config-center/http-client.js";
 export { mutateInPlace, applyEffective, applyRuntimeGates, applyRuntimeHot, resolveDefaultModelName, logEffectiveDiff, runtimeHasActiveGate, } from "./config-center/apply-effective.js";
 export { restartReasons, planeHasActiveTiers, modelPlaneChanged, type RestartSlice, type RestartSignal, } from "./config-center/restart-signal.js";

package/dist/sema-registry.js

@@ -1,3 +1,24 @@
+/**
+ * Sema-registry adapter — pull the effective config from sema-registry and apply it OVER the
+ * env-derived defaults (env = fallback, center = override). Follows the "universal internal
+ * schema → translate at the boundary" pattern, with our security boundary kept:
+ *
+ *   - the CENTER owns the LOGICAL config: the model roster (names/capabilities/tier), the role map,
+ *     and team templates;
+ *   - the SERVICE env still owns the SECRETS: API keys stay in env (the center never stores a secret);
+ *     keys are per-model via `apiKeyEnv` → `config.modelApiKeyEnv` → the spec's `getApiKeyAndHeaders`
+ *     (core 1.45), so each model/cascade-rung authenticates with its own upstream key.
+ *
+ * Per-model `baseUrl` IS transported (a catalog model may live on a different gateway;
+ * core brain honors model.baseUrl, absent = "" = boot-env endpoint). TODO remaining: hot-reload
+ * of models/roles needs Runner support — today teams hot-reload via the registry, while a models/roles
+ * change is logged as "restart to apply".
+ *
+ * (design/158 A13, internal-lossless) This module is now a FACADE: the implementation lives in
+ * `src/config-center/` split by responsibility group (HTTP client / EffectiveConfig application /
+ * restart-signal detection / skills+MCP consumption). Every symbol below is re-exported UNCHANGED —
+ * existing `from "./sema-registry.js"` / `from "../sema-registry.js"` imports need zero changes.
+ */
 export { fetchEffective, fetchPrincipalCaps, ConfigCenterHttpError, fetchSkillContent, fetchPromptArtifact, fetchPromptBlob, } from "./config-center/http-client.js";
 export { mutateInPlace, applyEffective, applyRuntimeGates, applyRuntimeHot, resolveDefaultModelName, logEffectiveDiff, runtimeHasActiveGate, } from "./config-center/apply-effective.js";
 export { restartReasons, planeHasActiveTiers, modelPlaneChanged, } from "./config-center/restart-signal.js";

package/dist/session-leaf-bus.d.ts

@@ -1,5 +1,36 @@
+/**
+ * Session leaf-advance bus — the S2 fast path of the session-level SSE subscription
+ * ([1196]/[1208]③: an append that lands on THIS replica fans out to watchers synchronously,
+ * zero latency on single-replica deployments; cross-replica watchers still ride the probe lane).
+ *
+ * Deliberately a REPLICA-LOCAL singleton (module state), not a constructor-threaded dependency:
+ * the leaf write sits at the bottom of the per-session storage stack (TiDB/Pg `persist()` — a
+ * static-factory + N-arg constructor chain away from main.ts), while the one consumer
+ * (SessionWatchRegistry.notifyLocal) is replica-local by design. A bus keeps the wiring one line
+ * per write site and one line in main; anything smarter re-plumbs four layers for the same effect.
+ *
+ * Contract:
+ *  - `emitLeafAdvance` MUST be fire-and-forget from the writer's perspective: it never throws
+ *    (listener errors are swallowed) and does no async work — a broken watcher must not fail or
+ *    slow a session write.
+ *  - Emit AFTER the storage commit succeeds (a rolled-back CAS must not fan out a leaf that never
+ *    became durable).
+ *  - Owner IS carried and MUST be the COMMIT-TIME row owner (codex two rounds: without owner the
+ *    generation fence is skipped; a wake-time snapshot is worse — stale-A over a reclaimed row false-
+ *    matches an old A entry and leaks the new tenant's leaf into the old stream). Zero-cost source:
+ *    the persist transaction's own leaf_seq SELECT carries the owner column — the emitted owner is the
+ *    row's tenant at the moment the write committed.
+ *  - `leafSeq`(the row's committed leaf_seq)rides every emit: DB commits serialize, but the
+ *    post-commit continuations don't — without an ordering token a delayed leaf-N delivery after
+ *    leaf-N+1 would walk the registry BACKWARD (and a stale notification could false-drop a newer
+ *    generation on owner mismatch). The registry keeps the highest accepted seq and ignores lower.
+ *  - The local (file/in-mem) lane does not emit: those sessions persist inside core's storage
+ *    backend with no server-side write hook; the probe lane covers them at its normal cadence.
+ */
 type LeafListener = (sessionId: string, leafId: string | null, owner: string | null | undefined, leafSeq: number) => void;
+/** main.ts wires this once at boot (→ SessionWatchRegistry.notifyLocal). Last write wins; tests reset with undefined. */
 export declare function setLeafAdvanceListener(fn: LeafListener | undefined): void;
+/** Called by the SQL session-storage write sites post-commit. Never throws, never awaits. */
 export declare function emitLeafAdvance(sessionId: string, leafId: string | null, owner: string | null | undefined, leafSeq: number): void;
 export {};
 //# sourceMappingURL=session-leaf-bus.d.ts.map

package/dist/session-leaf-bus.js

@@ -1,12 +1,44 @@
+/**
+ * Session leaf-advance bus — the S2 fast path of the session-level SSE subscription
+ * ([1196]/[1208]③: an append that lands on THIS replica fans out to watchers synchronously,
+ * zero latency on single-replica deployments; cross-replica watchers still ride the probe lane).
+ *
+ * Deliberately a REPLICA-LOCAL singleton (module state), not a constructor-threaded dependency:
+ * the leaf write sits at the bottom of the per-session storage stack (TiDB/Pg `persist()` — a
+ * static-factory + N-arg constructor chain away from main.ts), while the one consumer
+ * (SessionWatchRegistry.notifyLocal) is replica-local by design. A bus keeps the wiring one line
+ * per write site and one line in main; anything smarter re-plumbs four layers for the same effect.
+ *
+ * Contract:
+ *  - `emitLeafAdvance` MUST be fire-and-forget from the writer's perspective: it never throws
+ *    (listener errors are swallowed) and does no async work — a broken watcher must not fail or
+ *    slow a session write.
+ *  - Emit AFTER the storage commit succeeds (a rolled-back CAS must not fan out a leaf that never
+ *    became durable).
+ *  - Owner IS carried and MUST be the COMMIT-TIME row owner (codex two rounds: without owner the
+ *    generation fence is skipped; a wake-time snapshot is worse — stale-A over a reclaimed row false-
+ *    matches an old A entry and leaks the new tenant's leaf into the old stream). Zero-cost source:
+ *    the persist transaction's own leaf_seq SELECT carries the owner column — the emitted owner is the
+ *    row's tenant at the moment the write committed.
+ *  - `leafSeq`(the row's committed leaf_seq)rides every emit: DB commits serialize, but the
+ *    post-commit continuations don't — without an ordering token a delayed leaf-N delivery after
+ *    leaf-N+1 would walk the registry BACKWARD (and a stale notification could false-drop a newer
+ *    generation on owner mismatch). The registry keeps the highest accepted seq and ignores lower.
+ *  - The local (file/in-mem) lane does not emit: those sessions persist inside core's storage
+ *    backend with no server-side write hook; the probe lane covers them at its normal cadence.
+ */
 let listener;
+/** main.ts wires this once at boot (→ SessionWatchRegistry.notifyLocal). Last write wins; tests reset with undefined. */
 export function setLeafAdvanceListener(fn) {
     listener = fn;
 }
+/** Called by the SQL session-storage write sites post-commit. Never throws, never awaits. */
 export function emitLeafAdvance(sessionId, leafId, owner, leafSeq) {
     try {
         listener?.(sessionId, leafId, owner, leafSeq);
     }
     catch {
+        /* a broken watcher must never fail a session write */
     }
 }
 //# sourceMappingURL=session-leaf-bus.js.map

package/dist/session-sync-content.d.ts

@@ -1,3 +1,49 @@
+/**
+ * session-sync 的**内容判据**——回答一个 id-集合分类器回答不了的问题:
+ * 「两条 entry id 集合相等的日志,**内容**是否也相同?」
+ *
+ * ── 为什么需要它(深挖第一轮 + 2026-07-26 顺着往下查出的第二半)────────────────────────────────────
+ * §7 的 `classifySyncRelationshipByIds` 只比 **id 集合**,而 entry id 是 uuidv7、**不是内容寻址** ⇒
+ * 「同 id、异载荷」结构上完全可能(wire 本身就收调用方给的 entries)。第一半的后果已知:Phase A 判 `identical`
+ * ⇒ 整段跳过、调用方拿 200 而目的端仍是自己那份内容(真 HTTP 复现过)。
+ *
+ * 🔴 **第二半是我一开始判错的地方**:我在黑板 [1701] 说「server 单方面修不了」。那句只对 **Phase A** 成立
+ * (那时 server 手上没有源端内容,必须靠调用方送摘要)。但 **commit 时 server 同时握着两份日志**
+ * (staged + dst),所以内容比较**根本不需要调用方配合** —— 而 4 处 commit/import 路径当时都写着
+ * 「`relation === "identical"` ⇒ 跳过 entries 写入」,把「id 集合相等」当成了「内容相同」。
+ * 后果:一个**已经把整条日志上传完**的调用方(没送摘要、或送了但不可比),在 commit 处仍然拿到 no-op。
+ * ⇒ 两半都要修:Phase A 需要调用方的 `logDigest`(省掉无谓上传),commit 这一半是 server 自己的活。
+ *
+ * ── 判据来源:core 1.414 导出的 `sessionLogDigest` ──────────────────────────────────────────────────
+ * 覆盖每条 entry 的**全部字段**(id / parentId / type / timestamp / 载荷)且**顺序显著**,逐条带长度前缀
+ * (所以两份日志不可能被重新切分成同样的字节)。core 明确它可以两端各算 —— 与 `boundInputHash` 不同,
+ * 因为这里**分叉的代价是多同步一趟,不是错答案、也不是拒绝**(审批路径上分叉会拒掉一个合法的人类决定,
+ * 方向相反)。
+ *
+ * ── ⚠️ v1 摘要下本判据的**退化行为**(core 黑板 [1709];1.415.0 已修,现行下限已远高于此 ——
+ *     承重下限与理由见 `test/core-dependency-floor.test.ts`,别在这里记版本号)────────────────
+ * v1 的摘要区分 `{a: undefined}` 与 `{}`,而 core 自己成规模产 own-key=undefined 的 entry ⇒ 同一份日志的
+ * 内存形与 JSON 往返形摘要必然不同。本函数在 commit 处比的是 **staged**(刚从 wire 解析,JSON 形)与 **dst**
+ * (从存储读回,也是 JSON 形)—— 两侧同形,所以**这一处**不受那条影响;但若某个后端把 staged 留在内存形,
+ * 判据会退化成「恒不相等 ⇒ 恒改写」。
+ * 🔴 那个退化方向是**安全**的(多写一遍,不会丢数据),这是刻意选的:判据不确定时**宁可改写**,
+ * 因为反方向的错(误判"内容相同"而跳过写入)正是本函数要修的那个缺陷。
+ * ⇒ 所以这里**不加 scheme 门**。(Phase A 那条路曾加过 scheme **名字门**,后被 tsc 判恒真并撤掉,
+ *   换成「依赖下限 + 行为门」—— 名字门只认识旧名字,守不住这条性质;见 server.ts Phase A 段注释与
+ *   `test/sync-content-digest.test.ts`。)
+ *
+ * ⚠️ 抽成共享函数而不是在 4 处各写一遍:core [1689] RB-74 的教训(宣布"同族类修完成"而三个实现只落了一个),
+ * 本仓今天也刚在 33 处 exec→FileError 包装上吃过同款。判据收成一处,才谈得上机器看守。
+ */
 import { type SessionTreeEntry } from "@sema-agent/core";
+/**
+ * id 集合已判 `identical` 的两条日志,**内容是否真的相同**。
+ *
+ * `true`  ⇒ 内容也相同,跳过 entries 写入是**对的**(只需 owner 重戳)。
+ * `false` ⇒ **同 id 异内容**:必须真正改写目的端,否则调用方拿到的是一句"已同步"的谎。
+ *
+ * 🔴 这里**不抛错、不拒绝**:core 定的消费口径是「digest 不符永远不得变成 error / 409 / 拒绝同步」——
+ * 不符只意味着"多干一趟活",而不是"这次同步非法"。
+ */
 export declare function identicalIdsAlsoIdenticalContent(staged: readonly SessionTreeEntry[], dst: readonly SessionTreeEntry[] | null): boolean;
 //# sourceMappingURL=session-sync-content.d.ts.map

package/dist/session-sync-content.js

@@ -1,7 +1,53 @@
+/**
+ * session-sync 的**内容判据**——回答一个 id-集合分类器回答不了的问题:
+ * 「两条 entry id 集合相等的日志,**内容**是否也相同?」
+ *
+ * ── 为什么需要它(深挖第一轮 + 2026-07-26 顺着往下查出的第二半)────────────────────────────────────
+ * §7 的 `classifySyncRelationshipByIds` 只比 **id 集合**,而 entry id 是 uuidv7、**不是内容寻址** ⇒
+ * 「同 id、异载荷」结构上完全可能(wire 本身就收调用方给的 entries)。第一半的后果已知:Phase A 判 `identical`
+ * ⇒ 整段跳过、调用方拿 200 而目的端仍是自己那份内容(真 HTTP 复现过)。
+ *
+ * 🔴 **第二半是我一开始判错的地方**:我在黑板 [1701] 说「server 单方面修不了」。那句只对 **Phase A** 成立
+ * (那时 server 手上没有源端内容,必须靠调用方送摘要)。但 **commit 时 server 同时握着两份日志**
+ * (staged + dst),所以内容比较**根本不需要调用方配合** —— 而 4 处 commit/import 路径当时都写着
+ * 「`relation === "identical"` ⇒ 跳过 entries 写入」,把「id 集合相等」当成了「内容相同」。
+ * 后果:一个**已经把整条日志上传完**的调用方(没送摘要、或送了但不可比),在 commit 处仍然拿到 no-op。
+ * ⇒ 两半都要修:Phase A 需要调用方的 `logDigest`(省掉无谓上传),commit 这一半是 server 自己的活。
+ *
+ * ── 判据来源:core 1.414 导出的 `sessionLogDigest` ──────────────────────────────────────────────────
+ * 覆盖每条 entry 的**全部字段**(id / parentId / type / timestamp / 载荷)且**顺序显著**,逐条带长度前缀
+ * (所以两份日志不可能被重新切分成同样的字节)。core 明确它可以两端各算 —— 与 `boundInputHash` 不同,
+ * 因为这里**分叉的代价是多同步一趟,不是错答案、也不是拒绝**(审批路径上分叉会拒掉一个合法的人类决定,
+ * 方向相反)。
+ *
+ * ── ⚠️ v1 摘要下本判据的**退化行为**(core 黑板 [1709];1.415.0 已修,现行下限已远高于此 ——
+ *     承重下限与理由见 `test/core-dependency-floor.test.ts`,别在这里记版本号)────────────────
+ * v1 的摘要区分 `{a: undefined}` 与 `{}`,而 core 自己成规模产 own-key=undefined 的 entry ⇒ 同一份日志的
+ * 内存形与 JSON 往返形摘要必然不同。本函数在 commit 处比的是 **staged**(刚从 wire 解析,JSON 形)与 **dst**
+ * (从存储读回,也是 JSON 形)—— 两侧同形,所以**这一处**不受那条影响;但若某个后端把 staged 留在内存形,
+ * 判据会退化成「恒不相等 ⇒ 恒改写」。
+ * 🔴 那个退化方向是**安全**的(多写一遍,不会丢数据),这是刻意选的:判据不确定时**宁可改写**,
+ * 因为反方向的错(误判"内容相同"而跳过写入)正是本函数要修的那个缺陷。
+ * ⇒ 所以这里**不加 scheme 门**。(Phase A 那条路曾加过 scheme **名字门**,后被 tsc 判恒真并撤掉,
+ *   换成「依赖下限 + 行为门」—— 名字门只认识旧名字,守不住这条性质;见 server.ts Phase A 段注释与
+ *   `test/sync-content-digest.test.ts`。)
+ *
+ * ⚠️ 抽成共享函数而不是在 4 处各写一遍:core [1689] RB-74 的教训(宣布"同族类修完成"而三个实现只落了一个),
+ * 本仓今天也刚在 33 处 exec→FileError 包装上吃过同款。判据收成一处,才谈得上机器看守。
+ */
 import { sessionLogDigest } from "@sema-agent/core";
+/**
+ * id 集合已判 `identical` 的两条日志,**内容是否真的相同**。
+ *
+ * `true`  ⇒ 内容也相同,跳过 entries 写入是**对的**(只需 owner 重戳)。
+ * `false` ⇒ **同 id 异内容**:必须真正改写目的端,否则调用方拿到的是一句"已同步"的谎。
+ *
+ * 🔴 这里**不抛错、不拒绝**:core 定的消费口径是「digest 不符永远不得变成 error / 409 / 拒绝同步」——
+ * 不符只意味着"多干一趟活",而不是"这次同步非法"。
+ */
 export function identicalIdsAlsoIdenticalContent(staged, dst) {
     if (dst === null)
-        return false;
+        return false; // 目的端没有日志 ⇒ 谈不上"内容相同",按需改写
     return sessionLogDigest(staged) === sessionLogDigest(dst);
 }
 //# sourceMappingURL=session-sync-content.js.map

package/dist/session-sync-kernel.d.ts

@@ -1,22 +1,81 @@
+/**
+ * 2c session-sync KERNEL (design/158 A2) — the PURE half of session-sync: the §7 relation classifier, the staging-id
+ * scheme, the {@link StagingHandle}/{@link ImportStagingStore} contracts and the {@link SyncConflictError} type.
+ * Moved VERBATIM out of session-sync.ts (which keeps the StoreBackend-coupled ORCHESTRATION: exportSession/
+ * importSession/planSync) so the three DB session adapters (local/pg/tidb) and security.ts can depend on these
+ * symbols WITHOUT touching the orchestration module — session-sync.ts value-imports StoreBackend and type-imports
+ * security's OwnerAwareSessionStore, so importing it from security.ts formed the repo's only true type cycle
+ * (security ↔ session-sync; lens2 §B/§E). This file imports NOTHING from the repo (core types only) — a leaf,
+ * same shape as session-sync-content.ts. session-sync.ts re-exports everything here, so existing import sites
+ * keep working unchanged.
+ */
 import type { SessionTreeEntry } from "@sema-agent/core";
+/**
+ * P1d-β (PUSH streaming, docs/DESIGN-session-sync.md §15 + the persistence synthesis) — a TWO-PHASE STAGED import
+ * handle. The whole-bundle `importSession` (session-sync.ts) buffers every entry in one JSON body (server memory ∝ session size);
+ * β instead STREAMS the entry log (NDJSON) into a SHADOW session id, validating it ONLINE per line through core's
+ * StreamingImportValidator (the single invariant gate — core 1.143.0), then ATOMICALLY swaps
+ * the shadow rows into the real session id in ONE txn — so server memory is bounded by the in-flight BATCH, not the
+ * whole log. A handle is minted by {@link ImportStagingStore.beginImportStaging} (Phase A) and driven by the NDJSON
+ * route (Phase B): `appendBatch` per batch, then `commit` (the swap) or `abort` (drop the staging rows).
+ *
+ * Invariants the implementations uphold:
+ *  - The staging rows live under `stagingId = ${realSessionId}#stg-${token}` (the `#` is illegal in a real uuidv7, so
+ *    it can NEVER collide with a real session id) and have NO `session_meta` row → they are INVISIBLE to wake / ownerOf
+ *    / listSessions (the existing orphan invariant) until `commit` writes the real session_meta LAST as the sole
+ *    commit point. A crash before commit leaves only collectable orphan staging rows, never a half-session.
+ *  - `appendBatch` is IDEMPOTENT (INSERT … ON DUPLICATE KEY / ON CONFLICT DO NOTHING on the `(session_id, entry_id)`
+ *    uk), so a re-streamed batch (a resumed Phase B) is a no-op.
+ *  - `commit` re-classifies the relation IN-TXN against the dst's CURRENT entry ids (closing the Phase-A plan→commit
+ *    TOCTOU): a flip to fork/stale without the caller's overwrite consent rolls back and throws {@link SyncConflictError}.
+ */
 export interface StagingHandle {
+    /** The shadow session id the staged rows live under (`${realSessionId}#stg-${token}`) — opaque to the route. */
     readonly stagingId: string;
+    /** The real (destination) session id the staged rows are committed INTO. */
     readonly realSessionId: string;
+    /** Append a bounded batch of entries to the staging id, re-seq'd dense from a running counter held in the handle.
+     *  Idempotent (ON DUPLICATE KEY / ON CONFLICT DO NOTHING) — a re-streamed batch is a no-op. One txn per batch. */
     appendBatch(entries: SessionTreeEntry[]): Promise<void>;
+    /** ATOMICALLY swap the staged rows into the real session id (ONE txn): in-txn re-classify (TOCTOU close) → purge dst
+     *  → row-key rename staging→real → session_meta LAST (the commit point). `owner` is re-stamped (§9). Throws
+     *  {@link SyncConflictError} on an unconsented fork/stale flip. Returns the committed relation. */
     commit(owner: string | null, opts?: {
         resolution?: "overwrite-dst";
     }): Promise<{
         relation: SyncRelation["relation"];
     }>;
+    /** Drop the staging rows (Phase B aborted before commit) — DELETE the staging-id session_event rows. Idempotent. */
     abort(): Promise<void>;
 }
+/** A session store that can stage a streamed import (P1d-β). The 3 backends implement it; the in-memory dev store
+ *  does not → the method is optional (the route 501s when absent, parity with the other §0.5 optional seams). */
 export type ImportStagingStore = {
+    /** Begin a staged import into `realSessionId` under a shadow id `${realSessionId}#stg-${token}` (the ROUTE mints the
+     *  uuidv7 `token` and passes it — the store NEVER calls Date.now/uuidv7 itself, so the staging id is deterministic
+     *  and the route owns the lease key). Returns a {@link StagingHandle} the route streams batches into then commits. */
     beginImportStaging(realSessionId: string, token: string): StagingHandle;
+    /** Reaper — drop staging-id session_event rows with NO session_meta whose oldest row is older than the grace window
+     *  (an in-flight stream's rows stay fresh → never reaped). Mirrors `sweepOrphanBlobs`' grace discipline. */
     sweepStagingSessions?(): Promise<number>;
 };
+/** The staging-id format: a real session id with a `#stg-${token}` suffix. The `#` is illegal in a uuidv7, so a
+ *  staging id can never collide with a real session id (the orphan invariant) and is recognizable for the reaper. */
 export declare function stagingIdFor(realSessionId: string, token: string): string;
+/** The substring marker every staging id carries (the reaper's `LIKE '%#stg-%'` selector). */
 export declare const STAGING_ID_MARKER = "#stg-";
+/** Recover the real session id from a staging id (everything before the `#stg-` marker), or null if not a staging id. */
 export declare function realIdOfStaging(stagingId: string): string | null;
+/**
+ * §7 — the relationship between a SOURCE bundle's entry log and the DESTINATION's CURRENT entry log, the gate that
+ * decides whether an import is a safe sync or a data-losing overwrite. Five exhaustive cases:
+ *   - `fresh`        — the dst has no such session (nothing to lose) → import is unconditional.
+ *   - `identical`    — src and dst hold the SAME entry-id set → the conversation log is already present & equal (no-op).
+ *   - `fast_forward` — dst's entries are a STRICT subset of src (src is strictly ahead = clean append) → safe to apply.
+ *   - `stale`        — src's entries are a STRICT subset of dst (src is strictly behind) → applying would LOSE the dst
+ *                      entries the src never saw → a conflict (refused unless the user explicitly overwrites).
+ *   - `fork`         — each side has ≥1 entry the other lacks (true divergence after a common ancestor) → a conflict.
+ */
 export type SyncRelation = {
     relation: "fresh";
 } | {
@@ -33,8 +92,38 @@ export type SyncRelation = {
     srcExclusive: string[];
     dstExclusive: string[];
 };
+/**
+ * §7 — classify how importing `srcEntries` into a destination holding `dstEntries` would relate the two logs. PURE
+ * (no I/O); the §7 fork detector. The comparison is over the ENTRY-ID SETS, not leaf_id:
+ *
+ * Entry ids are copied VERBATIM across backends (fork/import re-seq only `seq`; id/parentId/payload are byte-identical
+ * — see tidb-session-store fork/importEntries), so a set comparison of ids is the SOUND divergence test §7 demands. It
+ * fixes v1's leaf_id-only check, which was unsound BOTH ways:
+ *   - FALSE NEGATIVE (the dangerous one): a cross-end rewind moves `LeafEntry.targetId` back onto a shared OLD entry id,
+ *     so two genuinely-forked logs report the SAME leaf_id → v1 would silently overwrite = data loss (exactly the 2c
+ *     use case). Set comparison sees each side's exclusive ids and reports `fork`.
+ *   - FALSE POSITIVE: a clean fast-forward ends on a NEW leaf id ≠ the dst's leaf → v1 flags a (non-)conflict. Set
+ *     comparison sees dst ⊊ src and reports `fast_forward` (safe).
+ *
+ * `commonAncestor` for a fork = the entry id present in BOTH logs that appears LAST in `srcEntries` oldest-first order
+ * (the deepest shared appended entry = the divergence point), or `null` if the logs share no entry at all.
+ */
 export declare function classifySyncRelationship(srcEntries: SessionTreeEntry[], dstEntries: SessionTreeEntry[] | null): SyncRelation;
+/**
+ * §7 — the SAME relation classifier as {@link classifySyncRelationship}, over entry-id LISTS (oldest-first) instead of
+ * full entries. This is the canonical implementation the entries-typed wrapper delegates to. It exists in its own right
+ * for the P1d HTTP `/sync/plan` route: the two peers are different PROCESSES (the local shell + the cloud), so the
+ * planning peer holds only the OTHER end's entry-id list (not its `SessionTreeEntry[]`) — the relation is decidable from
+ * the ids alone (ids are copied VERBATIM across backends, so a set comparison of ids is the sound divergence test §7
+ * demands; see the wrapper's doc-comment for why leaf_id was unsound). `srcIds`/`dstIds` are OLDEST-FIRST so the
+ * fork `commonAncestor` (the deepest shared id) and the ordered exclusive/new lists are derived correctly.
+ */
 export declare function classifySyncRelationshipByIds(srcIds: string[], dstIds: string[] | null): SyncRelation;
+/**
+ * §7 — a typed conflict the route maps to HTTP 409: an import that WOULD lose destination history (a `fork` or a
+ * `stale` source) and the caller did NOT pass an explicit `{ resolution: "overwrite-dst" }`. Carries the classified
+ * relation so the route/shell can surface the exclusive entry sets to the user for a keep-local / keep-cloud decision.
+ */
 export declare class SyncConflictError extends Error {
     readonly sessionId: string;
     readonly relation: Extract<SyncRelation, {