@sema-agent/server 7.146.0 → 7.148.0

package/dist/http/routes/memory-origin.js

@@ -1,10 +1,9 @@
 import { z } from "zod";
 import { sendJson, sendError } from "../send.js";
 import { sentMemoryStoreRefusal } from "../memory-store-refusal-reply.js";
-import { sentControlPlaneCorrupt } from "../memory-control-plane-corrupt-reply.js";
 import { buildOriginFence, readOriginAware } from "../../memory-origin-fence.js";
-import { readLayerSeat, sentMemoryLayerRefusal } from "../memory-layer-reply.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
+import { readLayerSeat, sentMemoryFaceFault } from "../memory-face-fault-reply.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 export const MEMORY_ORIGIN_EXTERNAL_PATH = "/v1/memory/origin/external";
@@ -50,7 +49,7 @@ function codeOf(err) {
     return typeof code === "string" ? code : undefined;
 }
 function sentClassifiedFailure(res, ctx, face, err) {
-    if (sentMemoryLayerRefusal(res, err, { kind: "operator" }))
+    if (sentMemoryFaceFault(res, err, { kind: "operator" }))
         return true;
     if (face === "clear") {
         const coreCode = codeOf(err);
@@ -59,8 +58,6 @@ function sentClassifiedFailure(res, ctx, face, err) {
     }
     if (face !== "clearances" && sentMemoryStoreRefusal(res, err, ctx.deps.logger))
         return true;
-    if (sentControlPlaneCorrupt(res, err, { kind: "operator" }))
-        return true;
     ctx.deps.logger?.warn?.(`memory_origin_${face}_failed`, { err: String(err) });
     return false;
 }
@@ -98,6 +95,7 @@ export function buildClearanceRowWire(r) {
         ...(r.tombstonedAt !== undefined ? { tombstonedAt: r.tombstonedAt } : {}),
         events: r.events.map(buildClearanceEventWire),
         custodyBytes: Buffer.byteLength(r.entryText, "utf8"),
+        ...(r.custodyErased === true ? { custodyErased: true } : {}),
     };
 }
 function parseScopes(raw) {
@@ -113,7 +111,7 @@ function parseScopes(raw) {
 }
 export async function handleMemoryOrigin(req, res, match, ctx) {
     const { deps } = ctx;
-    const principal = gatedPrincipal(req, deps.config);
+    const principal = gatedPerson(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
         sendPrincipalRefusal(res, req, deps.config);
         return;
@@ -163,7 +161,8 @@ export async function handleMemoryOrigin(req, res, match, ctx) {
             if (at === null)
                 return;
             try {
-                sendJson(res, 200, { clearances: (at !== undefined ? faces.listClearances(at) : faces.listClearances()).map(buildClearanceRowWire) });
+                const rows = await (at !== undefined ? faces.listClearances(at) : faces.listClearances());
+                sendJson(res, 200, { clearances: rows.map(buildClearanceRowWire) });
             }
             catch (err) {
                 if (!sentClassifiedFailure(res, ctx, "clearances", err))

package/dist/http/routes/memory-policy.js

@@ -5,9 +5,14 @@ import * as facts from "../../capability-facts.js";
 import { sendJson, sendError } from "../send.js";
 import { buildOriginFence, readOriginAware } from "../../memory-origin-fence.js";
 import { parseProjectLayerKey } from "../../project-layer-key.js";
-import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal, sendUnauthorized } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendPrincipalRefusal, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
-import { sentMemoryLayerRefusal } from "../memory-layer-reply.js";
+import { sentMemoryFaceFault } from "../memory-face-fault-reply.js";
+function layerFaceAudience(deps, principal, face, scope) {
+    if (explicitOperatorOk(principal, deps.config))
+        return { kind: "operator" };
+    return { kind: "layer_owner", face, withheld: (coreMessage) => deps.logger?.warn?.(face === "export" ? "memory_export_refused" : "memory_sync_refused", { scope, err: coreMessage }) };
+}
 const ORG_PREFIX = "org:";
 export const MEMORY_EXPORT_MAX_LIMIT = 500;
 function encodeExportCursor(c) {
@@ -36,16 +41,16 @@ function directoryDecidesThisFace(mode) {
             return false;
     }
 }
-async function gateMemoryScope(deps, principal, scope, need) {
-    if (scope === formatUserScope(principal) || parseProjectLayerKey(scope)?.owner === principal)
+async function gateMemoryScope(deps, person, scope, need) {
+    if (scope === formatUserScope(person) || parseProjectLayerKey(scope)?.owner === person)
         return { kind: "allow" };
-    if (explicitOperatorOk(principal, deps.config))
+    if (explicitOperatorOk(person, deps.config))
         return { kind: "allow" };
     const directory = deps.orgMemoryDirectory;
     if (!scope.startsWith(ORG_PREFIX) || directory === undefined || !directoryDecidesThisFace(deps.config.memoryOrgAdmissionMode)) {
         return { kind: "not_found" };
     }
-    const lookup = await directory.lookup(principal);
+    const lookup = await directory.lookup(person);
     if (lookup.kind === "unavailable")
         return { kind: "unavailable", retryAfterMs: lookup.retryAfterMs };
     const grant = lookup.scopes[scope];
@@ -70,7 +75,7 @@ export async function handleMemoryPolicy(req, res, match, ctx) {
     const { readJson, safeDecode } = ctx.helpers;
     switch (match.decl.id) {
         case "memory-export": {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPerson(req, deps.config);
             if (!principal) {
                 sendUnauthorized(res, "identity");
                 return;
@@ -100,7 +105,7 @@ export async function handleMemoryPolicy(req, res, match, ctx) {
             }
             const decoded = beforeRaw === null ? undefined : decodeExportCursor(beforeRaw);
             if (decoded !== undefined && !decoded.ok) {
-                sendError(res, 400, "request.query_invalid", "before must be the opaque `nextBefore` cursor from a previous page of this endpoint", { detail: decoded.why });
+                sendError(res, 400, "request.query_invalid", `before must be the opaque \`nextBefore\` cursor from a previous page of this endpoint: ${decoded.why}`);
                 return;
             }
             try {
@@ -125,7 +130,7 @@ export async function handleMemoryPolicy(req, res, match, ctx) {
                 });
             }
             catch (err) {
-                if (sentMemoryLayerRefusal(res, err, { kind: "operator" }))
+                if (sentMemoryFaceFault(res, err, layerFaceAudience(deps, principal, "export", scope)))
                     return;
                 deps.logger?.warn?.("memory_export_failed", { scope, err: String(err) });
                 sendError(res, 500, "internal.error", "memory export failed");
@@ -133,7 +138,7 @@ export async function handleMemoryPolicy(req, res, match, ctx) {
             return;
         }
         case "memory-sync-scope": {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPerson(req, deps.config);
             if (!principal) {
                 sendUnauthorized(res, "identity");
                 return;
@@ -185,7 +190,7 @@ export async function handleMemoryPolicy(req, res, match, ctx) {
                 sendJson(res, 200, out);
             }
             catch (err) {
-                if (sentMemoryLayerRefusal(res, err, { kind: "operator" }))
+                if (sentMemoryFaceFault(res, err, layerFaceAudience(deps, principal, "sync", scope)))
                     return;
                 deps.logger?.warn?.("memory_sync_failed", { scope, peer: parsed.value.peer, err: String(err) });
                 sendError(res, 500, "internal.error", "memory sync failed");
@@ -193,7 +198,7 @@ export async function handleMemoryPolicy(req, res, match, ctx) {
             return;
         }
         case "policy": {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPerson(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;

package/dist/http/routes/notify-wake.js

@@ -1,8 +1,8 @@
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal, sessionCallerOf } from "../principal-gate.js";
-import { ownerlessRowOpen, sessionOwnerCellOf } from "../../security.js";
+import { gatedSubject, sendPrincipalRefusal } from "../principal-gate.js";
+import { admitSessionRow, enter, refuse } from "../owner-access.js";
 import { sendResumeOutcome } from "../route-ctx.js";
-import { assertNever, SESSION_NOT_FOUND_MESSAGE } from "../route-ctx.js";
+import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { readResumeRestatement } from "../resume-restatement.js";
 export async function handleNotifyWake(req, res, match, ctx) {
@@ -13,11 +13,9 @@ export async function handleNotifyWake(req, res, match, ctx) {
         case "session-notify": {
             if (rateLimited(req, res) || quotaExceeded(req, res))
                 return;
-            const principal = gatedPrincipal(req, deps.config);
-            if (deps.config.requirePrincipal && principal === undefined) {
-                sendPrincipalRefusal(res, req, deps.config);
+            const notifyEntry = enter(req, res, deps, "session-notify");
+            if (notifyEntry === undefined)
                 return;
-            }
             const notifySession = safeDecode(match.params.sessionId);
             if (notifySession === null) {
                 sendError(res, 400, "request.path_malformed", "session id segment is not valid percent-encoding");
@@ -57,16 +55,9 @@ export async function handleNotifyWake(req, res, match, ctx) {
                 return;
             }
             const notifyHead = await owned.sessionStorage.headOf(notifySession);
-            if (notifyHead === undefined) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+            const notifyAdmitted = await admitSessionRow(notifyEntry, res, owned.sessionStorage, notifySession, notifyHead);
+            if (notifyAdmitted === undefined)
                 return;
-            }
-            const notifyOwner = notifyHead.owner;
-            const notifyOperator = explicitOperatorOk(principal, deps.config);
-            if (!notifyOperator && notifyOwner !== principal && !ownerlessRowOpen(await sessionOwnerCellOf(owned.sessionStorage, notifySession, notifyOwner), sessionCallerOf(req, deps))) {
-                sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
-                return;
-            }
             const payload = {
                 task_id: nb.task_id,
                 status: nb.status,
@@ -75,7 +66,7 @@ export async function handleNotifyWake(req, res, match, ctx) {
                 ...(nb.seq !== undefined ? { seq: nb.seq } : {}),
                 ...(nb.source !== undefined ? { source: nb.source } : {}),
             };
-            const out = await ctx.legs.sessionNotify.deliver({ sessionId: notifySession, occupant: notifyHead, ownerlessEntryOwner: principal ?? null }, payload);
+            const out = await ctx.legs.sessionNotify.deliver({ sessionId: notifySession, occupant: notifyAdmitted.row, ownerlessEntryOwner: notifyEntry.caller.subject ?? null }, payload);
             switch (out.delivery) {
                 case "live":
                     sendJson(res, 200, { sessionId: notifySession, delivery: "live" });
@@ -90,7 +81,7 @@ export async function handleNotifyWake(req, res, match, ctx) {
                     sendJson(res, 202, { sessionId: notifySession, delivery: "parked", note: "no live stream — parked in the session inbox; drained as a task_notification on the next stream open" });
                     return;
                 case "withdrawn":
-                    sendError(res, 404, "not_found.session", SESSION_NOT_FOUND_MESSAGE);
+                    refuse(notifyEntry, res, "missing");
                     return;
                 default:
                     return assertNever(out);
@@ -103,7 +94,7 @@ export async function handleNotifyWake(req, res, match, ctx) {
             }
             if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
                 return;
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedSubject(req, deps.config);
             if (deps.config.requirePrincipal && principal === undefined) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;
@@ -119,7 +110,8 @@ export async function handleNotifyWake(req, res, match, ctx) {
                 return;
             }
             const restatement = readResumeRestatement(wakeBody);
-            const out = await resumeWake(wakeSession, wakeBody.message, principal, req, true, undefined, undefined, restatement);
+            const message = typeof wakeBody.message === "string" ? { text: wakeBody.message, trusted: false } : undefined;
+            const out = await resumeWake(wakeSession, message, principal, req, true, undefined, undefined, restatement);
             sendResumeOutcome(res, out, deps.logger);
             return;
         }

package/dist/http/routes/observability.js

@@ -1,5 +1,5 @@
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { quotaWindowResetsAt } from "../../observability/cost-quota.js";
@@ -12,7 +12,7 @@ export async function handleObservability(req, res, match, ctx) {
                 sendOperatorPrincipalsRequired(res);
                 return;
             }
-            if (!explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config)) {
+            if (!explicitOperatorOk(gatedPerson(req, deps.config), deps.config)) {
                 sendError(res, 403, "auth.operator_only", "the outcomes view is operator-only");
                 return;
             }
@@ -41,7 +41,7 @@ export async function handleObservability(req, res, match, ctx) {
             return;
         }
         case "usage": {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPerson(req, deps.config);
             if (!principal) {
                 sendPrincipalRefusal(res, req, deps.config);
                 return;

package/dist/http/routes/principal-inbox.d.ts

@@ -2,7 +2,7 @@
  * 跨主体投递门的**受理口**:`POST /v1/principal-inbox/messages`。
  *
  * 本口只做三件事,其余全归门(`src/org-delivery-gate.ts`,规则全文在它的头注):
- *  ① 取发件人 —— **只**取自验过的身份面(`gatedPrincipal`),交给门的 `authedFrom` 就是 `{ scope: <那位主体> }`;
+ *  ① 取发件人 —— **只**取自验过的身份面(`gatedSubject`),交给门的 `authedFrom` 就是 `{ scope: <那位主体> }`;
  *     体里没有发件人这个键(写了 = 词表外键,400)。没有验过的身份 ⇒ 401(身份面那一句),不论部署是否要求 principal ——
  *     门要一个发件人 scope,匿名者没有。无凭证部署上 principal 头只是调用方自报 ⇒ 本口在分派器的无凭证写门内
  *     (声明行 `credentialGated`,503 `auth.service_token_required`;本地开发显式 `ALLOW_UNAUTHED_WRITES=true` 才放行);

package/dist/http/routes/principal-inbox.js

@@ -1,5 +1,5 @@
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, sendUnauthorized } from "../principal-gate.js";
+import { gatedSubject, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { principalInboxBodyKeyIssue } from "../../request-key-closure.js";
@@ -27,7 +27,7 @@ export async function handlePrincipalInbox(req, res, match, ctx) {
     const { readJson } = ctx.helpers;
     switch (match.decl.id) {
         case "principal-inbox-messages": {
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedSubject(req, deps.config);
             if (principal === undefined) {
                 sendUnauthorized(res, "identity");
                 return;

package/dist/http/routes/projects.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 项目登记簿的**读面** —— `GET /v1/projects`、`GET /v1/projects/:id`。
+ *
+ * ## 律(三句)
+ *  · **一个项目 = settings-schema 的一只 `ProjectRegistration`**:形与判官只在 settings-schema;本仓把判过的登记原样放在 `config.projects` 一张表里
+ *    (`web-admin-client/apply-effective.ts` 的 stage 是唯一写者),本面只读那一张。行 = `{ id, …登记的原键原名 }` —— 不铸 `name` / `repos` /
+ *    `createdAt` 之类的别名(端侧要别的叫法自己投影),逐键处置在 {@link PROJECT_ROW_DISPOSITIONS} 一张表里(settings-schema 给登记加键 ⇒ 这里 tsc 红,
+ *    先表态再上 wire)。
+ *  · **登记簿只由配置中心下发**:settings-schema 的本地读取集不收 `projects` 域 ⇒ 没有中心腿在应用配置的部署上没有登记簿 —— 两口 501
+ *    `capability.unavailable`,能力位 `capabilities.projects`(布尔)读同一只事实(`capability-facts.ts` 的 `projectRegistry`)答 `false`;
+ *    有登记簿时答 `true`。本面不开写动词(写到哪里由另一张设计定;写面到货时另立一位,本位不改义)。
+ *  · **可见性 fail-closed**:身份判在登记簿在场判**之前**(否则「这台有没有登记簿」先于 401 泄出去);fleet 调用方(列表面 `list.read` 读档(`listFilterOf`))看全部;
+ *    带验过主体的调用方只看 `registeredBy` 恰是自己的登记;看不见的与不存在的同码同句(404 `not_found.project`,不给存在性预言机)。
+ *
+ * 归档:`archivedAt` 在场 = 已归档。列表缺省不列,`?archived=true` 只列已归档的,`?archived=false` 与缺省同;单项读不论归档与否都答(会话行引用它)。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ProjectRegistration } from "@sema-agent/settings-schema";
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
+/** 404 的唯一句(不存在与看不见同句)。 */
+export declare const PROJECT_NOT_FOUND_MESSAGE = "no such project";
+/** 投影根:这只登记的 id(登记簿的键 —— 不是登记的成员)。 */
+interface ProjectRowRoot {
+    readonly id: string;
+}
+/**
+ * 项目行的**逐键处置**(表序 = 出口序)。登记的每个键原样出门;`contextItems` 逐条按成员处置(闭集三形,成员同为 `kind` / `value`)。
+ * `id` 是本面铸的唯一键:登记簿的键,行上要有它才能回指 `GET /v1/projects/:id` 与提交体 `projectId`。
+ */
+export declare const PROJECT_ROW_DISPOSITIONS: {
+    readonly id: {
+        readonly mint: (_reg: ProjectRegistration, root: ProjectRowRoot) => string;
+    };
+    readonly displayName: "forward";
+    readonly goal: "forward";
+    readonly contextItems: {
+        readonly nested: {
+            readonly kind: "forward";
+            readonly value: "forward";
+        };
+        readonly rows: "each";
+    };
+    readonly gitRemotes: "forward";
+    readonly defaultScopes: "forward";
+    readonly notes: "forward";
+    readonly icon: "forward";
+    readonly color: "forward";
+    readonly registeredBy: "forward";
+    readonly registeredAt: "forward";
+    readonly archivedAt: "forward";
+};
+/** 项目行的键全集(处置表的键 = wire 上可能出现的每一个键;自铸登记表 `trace/self-minted-wire.ts` 的 `projectRowKey` 按它 `satisfies`)。 */
+export type ProjectRowKey = keyof typeof PROJECT_ROW_DISPOSITIONS;
+/** 一只登记 → wire 行(唯一投影)。 */
+export declare function projectRowOf(id: string, registration: ProjectRegistration): Record<string, unknown>;
+export declare function handleProjects(req: IncomingMessage, res: ServerResponse, match: RouteMatch<ProjectsRouteId>, ctx: RouteCtx): Promise<void>;
+export declare const PROJECTS_ROUTES: readonly [{
+    readonly id: "projects-list";
+    readonly path: "/v1/projects";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "project-get";
+    readonly pattern: RegExp;
+    readonly label: "/v1/projects/:id";
+    readonly methods: readonly ["GET"];
+}];
+/** 本域可分派行的 `id` 闭集。 */
+export type ProjectsRouteId = RouteIdsOf<typeof PROJECTS_ROUTES>;
+export {};
+//# sourceMappingURL=projects.d.ts.map

package/dist/http/routes/projects.js

@@ -0,0 +1,87 @@
+import { PROJECT_ID_REGEX } from "@sema-agent/core";
+import { sendJson, sendError } from "../send.js";
+import { sendUnauthorized } from "../principal-gate.js";
+import { routeListFilter } from "../owner-access.js";
+import { assertNever } from "../route-ctx.js";
+import * as facts from "../../capability-facts.js";
+import { projectByTable } from "../../trace/projection-table.js";
+export const PROJECT_NOT_FOUND_MESSAGE = "no such project";
+export const PROJECT_ROW_DISPOSITIONS = {
+    id: { mint: (_reg, root) => root.id },
+    displayName: "forward",
+    goal: "forward",
+    contextItems: { nested: { kind: "forward", value: "forward" }, rows: "each" },
+    gitRemotes: "forward",
+    defaultScopes: "forward",
+    notes: "forward",
+    icon: "forward",
+    color: "forward",
+    registeredBy: "forward",
+    registeredAt: "forward",
+    archivedAt: "forward",
+};
+export function projectRowOf(id, registration) {
+    return projectByTable("project", PROJECT_ROW_DISPOSITIONS, registration, { id });
+}
+function readArchivedQuery(raw) {
+    switch (raw) {
+        case null:
+        case "false":
+            return false;
+        case "true":
+            return true;
+        default:
+            return "invalid";
+    }
+}
+export async function handleProjects(req, res, match, ctx) {
+    const { deps } = ctx;
+    const { safeDecode } = ctx.helpers;
+    const { fleetWide, gateOwner } = routeListFilter(req, deps, match.decl.id);
+    if (!fleetWide && gateOwner === null) {
+        sendUnauthorized(res, "identity");
+        return;
+    }
+    const registry = facts.projectRegistry(deps);
+    if (!registry.available) {
+        sendError(res, 501, "capability.unavailable", "the project registry is not available on this deployment: projects are published only by the configuration center, and no center configuration is applied here");
+        return;
+    }
+    const visible = (registration) => fleetWide || registration.registeredBy === gateOwner;
+    switch (match.decl.id) {
+        case "projects-list": {
+            const archived = readArchivedQuery(new URLSearchParams(match.search).get("archived"));
+            if (archived === "invalid") {
+                sendError(res, 400, "request.query_invalid", "archived must be `true` or `false`");
+                return;
+            }
+            const projects = Object.entries(registry.registry)
+                .filter(([, registration]) => visible(registration) && (registration.archivedAt !== undefined) === archived)
+                .map(([id, registration]) => projectRowOf(id, registration));
+            sendJson(res, 200, { projects });
+            return;
+        }
+        case "project-get": {
+            const raw = safeDecode(match.params.projectId);
+            if (raw === null || !PROJECT_ID_REGEX.test(raw)) {
+                sendError(res, 400, "request.id_invalid", "invalid project id (must be a canonical uuid)");
+                return;
+            }
+            const id = raw.toLowerCase();
+            const registration = Object.hasOwn(registry.registry, id) ? registry.registry[id] : undefined;
+            if (registration === undefined || !visible(registration)) {
+                sendError(res, 404, "not_found.project", PROJECT_NOT_FOUND_MESSAGE);
+                return;
+            }
+            sendJson(res, 200, projectRowOf(id, registration));
+            return;
+        }
+        default:
+            return assertNever(match.decl.id);
+    }
+}
+export const PROJECTS_ROUTES = [
+    { id: "projects-list", path: "/v1/projects", methods: ["GET"] },
+    { id: "project-get", pattern: /^\/v1\/projects\/(?<projectId>[^/]+)$/, label: "/v1/projects/:id", methods: ["GET"] },
+];
+//# sourceMappingURL=projects.js.map

package/dist/http/routes/retention-ops.js

@@ -1,5 +1,6 @@
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
+import { limitFacts } from "../../limit-refusal.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import * as facts from "../../capability-facts.js";
 import { assertNever } from "../route-ctx.js";
 import { RETENTION_AUDIT_DEFAULT_LIMIT, RETENTION_AUDIT_MAX_LIMIT } from "../../plugins/retention-lane-store-sql.js";
@@ -27,7 +28,7 @@ function decodeCursor(raw) {
 }
 export async function handleRetention(req, res, match, ctx) {
     const { deps } = ctx;
-    const principal = gatedPrincipal(req, deps.config);
+    const principal = gatedPerson(req, deps.config);
     if (deps.config.requirePrincipal && !principal) {
         sendPrincipalRefusal(res, req, deps.config);
         return;
@@ -64,9 +65,7 @@ async function handleHold(req, res, ctx, store, rawDomain, principal, held) {
         return;
     }
     if (domain.length > DOMAIN_MAX_CHARS) {
-        sendError(res, 400, "request.field_invalid", "the retention domain does not fit the hold table's identity column", {
-            detail: `domain is ${domain.length} characters; retention_hold.domain holds at most ${DOMAIN_MAX_CHARS}`,
-        });
+        sendError(res, 400, "request.field_invalid", `the retention domain does not fit the hold table's identity column: domain is ${domain.length} characters; retention_hold.domain holds at most ${DOMAIN_MAX_CHARS}`, limitFacts("domain", "characters", domain.length, DOMAIN_MAX_CHARS));
         return;
     }
     let note;
@@ -84,9 +83,7 @@ async function handleHold(req, res, ctx, store, rawDomain, principal, held) {
                     return;
                 }
                 if (n.length > NOTE_MAX_CHARS) {
-                    sendError(res, 400, "request.field_invalid", "the retention hold note is longer than this face accepts", {
-                        detail: `note is ${n.length} characters; the limit is ${NOTE_MAX_CHARS}`,
-                    });
+                    sendError(res, 400, "request.field_invalid", `the retention hold note is longer than this face accepts: note is ${n.length} characters; the limit is ${NOTE_MAX_CHARS}`, limitFacts("note", "characters", n.length, NOTE_MAX_CHARS));
                     return;
                 }
                 note = n;
@@ -125,7 +122,7 @@ async function handleAuditRead(res, store, search) {
     const beforeRaw = q.get("before");
     const decoded = beforeRaw === null ? undefined : decodeCursor(beforeRaw);
     if (decoded !== undefined && !decoded.ok) {
-        sendError(res, 400, "request.query_invalid", "before must be the opaque `nextBefore` cursor from a previous page of this endpoint", { detail: decoded.why });
+        sendError(res, 400, "request.query_invalid", `before must be the opaque \`nextBefore\` cursor from a previous page of this endpoint: ${decoded.why}`);
         return;
     }
     const domainRaw = q.get("domain");

package/dist/http/routes/rules.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendUnauthorized } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
+import { principalShapeProblem } from "../../principal-shape.js";
 import * as facts from "../../capability-facts.js";
 import { createLogger } from "../../observability/logger.js";
 import { RULE_IMPORT_RETRY_AFTER_SEC, RULE_SCOPE_REFUSAL_SENTENCE, MAX_RULE_SCOPE_CHARS, buildCcImportLayerRootRefusal, parseRuleScope, serializeRuleScope } from "../../rules-consent.js";
@@ -75,7 +76,7 @@ const RuleIdentityBodySchema = z
     behavior: z.enum(RULE_BEHAVIORS),
     rule: z.string().min(1).max(1024),
     scope: z.string().min(1).max(MAX_RULE_SCOPE_CHARS),
-    principal: z.string().min(1).max(190).optional(),
+    principal: z.string().optional(),
 })
     .strict();
 const RULES_CURSOR_FORMAT = 2;
@@ -100,7 +101,7 @@ export async function handleRules(req, res, match, ctx) {
     const { readJson, rateLimited } = ctx.helpers;
     if (rateLimited(req, res))
         return;
-    const principal = gatedPrincipal(req, deps.config);
+    const principal = gatedPerson(req, deps.config);
     if (principal === undefined) {
         sendUnauthorized(res, "identity");
         return;
@@ -142,6 +143,10 @@ export async function handleRules(req, res, match, ctx) {
                     logger.info("local rule import tightening write failed", { detail: prepared.detail, committed: prepared.committed });
                     sendRuleWriteFailure(res, "import-tightening", prepared.committed);
                     return;
+                case "record-store-refused":
+                    logger.info("local rule import record store refused", { detail: prepared.detail, committed: prepared.committed });
+                    sendRuleWriteFailure(res, "import-record", prepared.committed);
+                    return;
                 default: {
                     const unknown = prepared;
                     throw new Error(`unknown local import refusal: ${JSON.stringify(unknown)}`);
@@ -189,8 +194,19 @@ export async function handleRules(req, res, match, ctx) {
         }
         const prepared = await lane.prepareImport(principal, parsed.data.layers);
         if (!prepared.ok) {
-            sendError(res, 413, "request.payload_too_large", "too many allow entries across the submitted settings layers");
-            return;
+            switch (prepared.reason) {
+                case "too-many-candidates":
+                    sendError(res, 413, "request.payload_too_large", "too many allow entries across the submitted settings layers");
+                    return;
+                case "record-store-refused":
+                    logger.info("rule import record store refused", { detail: prepared.detail, committed: prepared.committed });
+                    sendRuleWriteFailure(res, "import-record", prepared.committed);
+                    return;
+                default: {
+                    const unknown = prepared;
+                    throw new Error(`unknown rule import refusal: ${JSON.stringify(unknown)}`);
+                }
+            }
         }
         sendJson(res, 200, { preview: prepared.preview, ...(prepared.ticket !== undefined ? { ticket: prepared.ticket, expiresAtMs: prepared.expiresAtMs } : {}) });
         return;
@@ -230,8 +246,13 @@ function resolveTargetPrincipal(requested, caller, config) {
         return { ok: false, why: "operator_principals_empty" };
     if (!explicitOperatorOk(caller, config))
         return { ok: false, why: "not_operator" };
+    if (principalShapeProblem(requested) !== undefined)
+        return { ok: false, why: "not_a_principal" };
     return { ok: true, principal: requested };
 }
+function sendTargetNotAPrincipal(res) {
+    sendError(res, 400, "request.field_invalid", "principal must name a principal a caller can authenticate as (a visible-character, well-formed name, not a reserved identifier, at most the principal byte length)", { field: "principal" });
+}
 async function handleRuleList(res, search, caller, lane, config) {
     const q = new URLSearchParams(search);
     const target = resolveTargetPrincipal(q.get("principal") ?? undefined, caller, config);
@@ -243,6 +264,9 @@ async function handleRuleList(res, search, caller, lane, config) {
             case "not_operator":
                 sendError(res, 403, "auth.operator_only", "reading another principal's rules is an operator-only action");
                 return;
+            case "not_a_principal":
+                sendTargetNotAPrincipal(res);
+                return;
             default:
                 return assertNever(target.why);
         }
@@ -306,6 +330,19 @@ function sendRuleWriteFailure(res, verb, committed) {
                     throw new Error(`unknown rule-write committed word: ${JSON.stringify(unknownWord)}`);
                 }
             }
+        case "import-record":
+            switch (committed) {
+                case "no":
+                    sendError(res, 503, "state.rule_write_failed", "the import's approval record could not be created (no ticket was issued and no allow rule was written; deny / ask rows of a local batch may already be in force) — send the same request again", { committed });
+                    return;
+                case "unknown":
+                    sendError(res, 503, "state.rule_write_failed", "the import's approval record may or may not have been created (no ticket was issued and no allow rule was written; deny / ask rows of a local batch may already be in force) — send the same request again", { committed });
+                    return;
+                default: {
+                    const unknownWord = committed;
+                    throw new Error(`unknown rule-import committed word: ${JSON.stringify(unknownWord)}`);
+                }
+            }
         case "revoke":
             switch (committed) {
                 case "no":
@@ -350,6 +387,9 @@ async function handleRuleWrite(res, rawBody, caller, lane, config) {
             case "not_operator":
                 sendError(res, 403, "auth.operator_only", "writing another principal's rules is an operator-only action");
                 return;
+            case "not_a_principal":
+                sendTargetNotAPrincipal(res);
+                return;
             default:
                 return assertNever(target.why);
         }
@@ -364,9 +404,9 @@ async function handleRuleWrite(res, rawBody, caller, lane, config) {
             return;
         case "rejected":
             logger.info("rule write refused", { reason: written.reason, detail: written.detail });
-            sendError(res, 400, "request.field_invalid", "this rule was not written — `reason` names which check refused it and `detail` says why", {
+            sendError(res, 400, "request.field_invalid", `this rule was not written — \`reason\` names which check refused it: ${written.detail}`, {
                 reason: written.reason,
-                detail: written.detail,
+                ...(written.canonical !== undefined ? { canonical: written.canonical } : {}),
             });
             return;
         case "failed":
@@ -399,6 +439,9 @@ async function handleRuleRevoke(res, rawBody, caller, lane, config) {
             case "not_operator":
                 sendError(res, 403, "auth.operator_only", "revoking another principal's rules is an operator-only action");
                 return;
+            case "not_a_principal":
+                sendTargetNotAPrincipal(res);
+                return;
             default:
                 return assertNever(target.why);
         }

package/dist/http/routes/run-memory-capture.d.ts

@@ -10,7 +10,7 @@
  *
  * ── 权限法条(steer 车道逐字)────────────────────────────────────────────────────────────────────
  * core 不认证:持有活流句柄即能力。**本面拥有 verified-principal / 会话所有权判定**:裸 sessionId 中继会让任何人
- * 关掉任何人的记忆(可用性攻击)。所以:身份来自 `gatedPrincipal`(验证过的身份,不是可自造的头),run 属主不符
+ * 关掉任何人的记忆(可用性攻击)。所以:身份来自 `gatedSubject`(验证过的身份,不是可自造的头),run 属主不符
  * ⇒ 404 `not_found.run` **同串反枚举**(与 steer/interrupt 同判)。core 在翻转时刻**重新裁决** per-principal
  * entitlement(`RuntimeCaps.allowMemoryOptOut` under `memoryCapturePolicy`,fresh resolve)—— 被拒 ⇒ typed
  * `memory.capture_optout_denied` + 零记录残留;server 不复刻那条裁决。
@@ -28,7 +28,7 @@
  * `sessionBackgroundable` 同谓词):老 worker 键缺席 ⇒ 壳不渲入口(假 affordance 纪律)。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { type RouteCtx, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 export declare function handleRunMemoryCapture(req: IncomingMessage, res: ServerResponse, match: RouteMatch<RunMemoryCaptureRouteId>, ctx: RouteCtx): Promise<void>;
 export declare const RUN_MEMORY_CAPTURE_ROUTES: readonly [{
     readonly id: "run-memory-capture-optout";