@sema-agent/server 7.138.0 → 7.140.0

package/dist/memory-operator-faces.js

@@ -1,8 +1,59 @@
 import { MemoryEngine, } from "@sema-agent/core";
 import { memoryMountRootOf } from "./memory-scope.js";
+import { memoryStoreForRequest, memoryStoresOfDeployment } from "./memory-scope-stores.js";
 export function backendOwnsControlPlane(backend) {
-    const b = backend;
-    return typeof b?.controlPlaneRoot === "string" && b.controlPlaneRoot !== "";
+    return controlPlaneRootOf(backend) !== undefined;
+}
+function controlPlaneRootOf(backend) {
+    const root = backend?.controlPlaneRoot;
+    return typeof root === "string" && root !== "" ? root : undefined;
+}
+export function captureRecordStoreOf(source, store) {
+    if (source === undefined)
+        return undefined;
+    const root = controlPlaneRootOf(store);
+    return source(root !== undefined ? { controlDir: root } : undefined);
+}
+const seatLayers = (at) => (at !== undefined ? [at.layer] : []);
+function createEngineSeat(build) {
+    const engines = new Map();
+    return (store) => {
+        const known = engines.get(store);
+        if (known !== undefined)
+            return known;
+        if (!backendOwnsControlPlane(store))
+            throw new Error("the memory store that holds this layer owns no engine control plane (controlPlaneRoot) — the operator faces never answer over a store without one");
+        const engine = build(store);
+        engines.set(store, engine);
+        return engine;
+    };
+}
+function erasureLayersOf(input) {
+    if (typeof input !== "object" || input === null)
+        return [];
+    const { select, expectedScopes } = input;
+    const scope = typeof select === "object" && select !== null ? select.scope : undefined;
+    if (typeof scope === "string" && scope.length > 0)
+        return [scope];
+    if (Array.isArray(expectedScopes) && expectedScopes.length > 0 && expectedScopes.every((s) => typeof s === "string" && s.length > 0))
+        return expectedScopes;
+    return [];
+}
+function erasureSessionOf(input) {
+    if (typeof input !== "object" || input === null)
+        return undefined;
+    const { select } = input;
+    const sessionId = typeof select === "object" && select !== null ? select.sessionId : undefined;
+    return typeof sessionId === "string" && sessionId.length > 0 ? sessionId : undefined;
+}
+export class MemoryErasureStoreUnjudged extends Error {
+    code = "memory.erasure_store_unjudged";
+    constructor() {
+        super("memory erasure refused: this erasure reaches a memory store other than the deployment's store (this deployment keeps the typed personal memory layers in a second store), " +
+            "and this build judges an erasure requestId on the deployment's store only, so it cannot tell whether the same requestId already erased under another selector there — " +
+            "erasures that reach the second store are not taken in this build, and nothing was erased; the way out is the engine's deployment-wide erasure request identity, due with the next engine update");
+        this.name = "MemoryErasureStoreUnjudged";
+    }
 }
 export function erasureInputSmugglesPrototypeKey(input) {
     const stack = [input];
@@ -24,50 +75,105 @@ export function erasureInputSmugglesPrototypeKey(input) {
     }
     return false;
 }
-export function createMemoryComplianceFaces(store, opts) {
-    if (!backendOwnsControlPlane(store.backend))
+export function createMemoryComplianceFaces(stores, opts) {
+    if (!backendOwnsControlPlane(stores.backend))
         return undefined;
-    const engine = new MemoryEngine({
-        backend: store.backend,
-        memoryDir: memoryMountRootOf(store.backend, store.root),
-        ...(opts?.onIncident !== undefined ? { onIncident: opts.onIncident } : {}),
-        ...(opts?.captureRecordStore !== undefined ? { captureRecordStore: opts.captureRecordStore } : {}),
+    const engineOf = createEngineSeat((store) => {
+        const records = captureRecordStoreOf(opts?.captureRecords, store);
+        return new MemoryEngine({
+            backend: store,
+            memoryDir: memoryMountRootOf(store, stores.root),
+            ...(opts?.onIncident !== undefined ? { onIncident: opts.onIncident } : {}),
+            ...(records !== undefined ? { captureRecordStore: records } : {}),
+        });
     });
+    const erasureStoreOf = async (input, at) => {
+        const seat = at !== undefined ? "`scope`" : "`select.scope`, or `expectedScopes` next to `select.ids` / `select.sessionId`";
+        const layers = at !== undefined ? seatLayers(at) : erasureLayersOf(input);
+        const sessionId = layers.length === 0 ? erasureSessionOf(input) : undefined;
+        if (sessionId === undefined) {
+            const store = memoryStoreForRequest(stores, layers, seat);
+            if (store !== stores.backend)
+                throw new MemoryErasureStoreUnjudged();
+            return store;
+        }
+        for (const other of memoryStoresOfDeployment(stores, seat)) {
+            if (other === stores.backend)
+                continue;
+            if ((await engineOf(other).sessionMemoryStatus(sessionId)).committedCount !== 0)
+                throw new MemoryErasureStoreUnjudged();
+        }
+        return stores.backend;
+    };
     return {
-        provenanceOf: (entryId) => engine.provenanceOf(entryId),
-        erase: (input) => {
+        provenanceOf: async (entryId, at) => engineOf(memoryStoreForRequest(stores, seatLayers(at))).provenanceOf(entryId),
+        erase: async (input, at) => {
             if (erasureInputSmugglesPrototypeKey(input)) {
                 const e = new Error("memory erasure refused: the request carries a key that rewrites an object's prototype — such a key is not a selector, and core's selector dispatch would read it in preference to the declared one");
                 e.code = "memory.erasure_selector_unsafe";
-                return Promise.reject(e);
+                throw e;
             }
-            return engine.eraseMemoryEntries(input);
+            const store = await erasureStoreOf(input, at);
+            return engineOf(store).eraseMemoryEntries(input);
         },
     };
 }
-export function createMemoryOriginFaces(store, opts) {
-    if (!backendOwnsControlPlane(store.backend))
+export function createMemoryOriginFaces(stores, opts) {
+    if (!backendOwnsControlPlane(stores.backend))
         return undefined;
-    const engine = new MemoryEngine({
-        backend: store.backend,
-        memoryDir: memoryMountRootOf(store.backend, store.root),
-        ...(opts?.onIncident !== undefined ? { onIncident: opts.onIncident } : {}),
-        ...(opts?.captureRecordStore !== undefined ? { captureRecordStore: opts.captureRecordStore } : {}),
+    const engineOf = createEngineSeat((store) => {
+        const records = captureRecordStoreOf(opts?.captureRecords, store);
+        return new MemoryEngine({
+            backend: store,
+            memoryDir: memoryMountRootOf(store, stores.root),
+            ...(opts?.onIncident !== undefined ? { onIncident: opts.onIncident } : {}),
+            ...(records !== undefined ? { captureRecordStore: records } : {}),
+        });
     });
     return {
-        listExternal: (scopes) => engine.listExternalOriginEntries(scopes),
-        listClearances: () => engine.listOriginClearances(),
-        clear: (entryId, input) => engine.clearEntryOrigin(entryId, input),
+        listExternal: async (scopes) => engineOf(memoryStoreForRequest(stores, scopes)).listExternalOriginEntries(scopes),
+        listClearances: (at) => engineOf(memoryStoreForRequest(stores, seatLayers(at))).listOriginClearances(),
+        clear: async (entryId, input, at) => engineOf(memoryStoreForRequest(stores, seatLayers(at))).clearEntryOrigin(entryId, input),
     };
 }
-export function createSessionMemoryStatusFace(store, opts) {
-    if (!backendOwnsControlPlane(store.backend))
+export function foldPlaneStatuses(statuses) {
+    const sum = (key) => statuses.every((s) => s[key] !== undefined) ? statuses.reduce((n, s) => n + s[key], 0) : undefined;
+    const committedCount = sum("committedCount");
+    const foldedCount = sum("foldedCount");
+    const captures = statuses.flatMap((s) => (s.lastCaptureAt !== undefined ? [s.lastCaptureAt] : []));
+    const lastCaptureAt = committedCount !== undefined && captures.length > 0 ? Math.max(...captures) : undefined;
+    const recorded = statuses.find((s) => s.captureOptedOut === true);
+    const capture = recorded !== undefined
+        ? { captureOptedOut: true, ...(recorded.optOutSource !== undefined ? { optOutSource: recorded.optOutSource } : {}) }
+        : statuses.every((s) => s.captureOptedOut === false)
+            ? { captureOptedOut: false }
+            : statuses.some((s) => s.optOutSource === "fault")
+                ? { optOutSource: "fault" }
+                : {};
+    return {
+        ...capture,
+        ...(committedCount !== undefined ? { committedCount } : {}),
+        ...(foldedCount !== undefined ? { foldedCount } : {}),
+        ...(lastCaptureAt !== undefined ? { lastCaptureAt } : {}),
+    };
+}
+export function createSessionMemoryStatusFace(stores, opts) {
+    if (!backendOwnsControlPlane(stores.backend))
         return undefined;
-    const engine = new MemoryEngine({
-        backend: store.backend,
-        memoryDir: memoryMountRootOf(store.backend, store.root),
-        ...(opts?.captureRecordStore !== undefined ? { captureRecordStore: opts.captureRecordStore } : {}),
+    const engineOf = createEngineSeat((store) => {
+        const records = captureRecordStoreOf(opts?.captureRecords, store);
+        return new MemoryEngine({
+            backend: store,
+            memoryDir: memoryMountRootOf(store, stores.root),
+            ...(records !== undefined ? { captureRecordStore: records } : {}),
+        });
     });
-    return { status: (sessionId) => engine.sessionMemoryStatus(sessionId) };
+    const storeOf = (store) => {
+        const engine = engineOf(store);
+        return { controlPlane: engine.controlPlaneRoot, status: (sessionId) => engine.sessionMemoryStatus(sessionId) };
+    };
+    return {
+        storesAt: (at) => (at !== undefined ? [storeOf(memoryStoreForRequest(stores, seatLayers(at)))] : memoryStoresOfDeployment(stores).map(storeOf)),
+    };
 }
 //# sourceMappingURL=memory-operator-faces.js.map

package/dist/memory-project-layer.d.ts

@@ -1,23 +1,5 @@
-/**
- * [ref]([ref] 片二)—— 一个任务的**项目层准备一步**:求键 → 把同一 checkout 的旧层折进当前层 → 交给同步腿跟踪。
- * HTTP 腿(`boot/resolve-spec.ts`)与 run-local 腿共用这一只;键的规则只在 `memory-scope.ts` `memoryProjectLayerFor`(本模块不判让位、不铸键)。
- *
- * ## 折叠(`foldFrom`,由 `project-identity.ts` `projectLayerForTaskRoot` 给出,按序)
- *  · 退役 `repo:<sha256(根)[:24]>` 层 —— **一次性迁移**(7.98.0–7.132.x 的项目键;窗、删法见 `plugins/one-time-migrations.ts` 登记表 M25);
- *  · 当前档为 `r`(origin 远端)时本 checkout 的 `p` 档 —— **常设律**(先 `git init` 后加远端的项目,加远端那一刻不丢项目记忆)。
- * 折 = core `migrateScope`(id 保留、rev 按新 scope 重算、逐条 CAS;冲突留原地,下一个任务再折)。**不记「已折」**:每个任务先读一眼旧层
- * (`listHeaders`,空就不动),旧层之后又来了条目(仍在跑的旧任务 harvest、同步把别处的改动拉回旧层)下一个任务照折。
- * 🔴 **与同步轮串行**:旧层若是被同步的层(`p` 档),在飞的那一轮的应答(拉回的改动 / 删除)按 id 落盘 —— 折在它前面,应答会把刚折走的条目改回旧层
- * 或在新层上删掉它。所以有东西要折时,折叠排进同步腿的串行链(`MemorySyncRunner.exclusive`):等在飞的那一轮落定再折,折的时候没有轮在飞。
- * 折在 spec 返回之前完成(`await`)⇒ 这一任务挂载时就看得见折进来的条目(代价如实:有东西要折又恰有一轮在飞时,任务起步等那一轮)。
- * 折叠失败不挡任务(响亮 warn,条目原地不动、下次再折):项目层记忆暂时少了旧层那几条,比任务起不来更接近用户要的东西。
- *
- * ## 跟踪
- * 当前层在复制覆盖面里(否则规则已让位、根本走不到这里)且有同步腿 ⇒ `track(scope)`:本地还没有条目也每轮拉它 —— 第二台设备第一次进这个项目
- * 就拉得到第一台写的(拉回来可能晚于本任务挂载:第一个任务看不见,下一个任务看得见,如实)。
- */
-import { type MemoryBackend } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
+import type { MemoryScopeStores } from "./memory-scope-stores.js";
 import type { MemorySyncRunner } from "./memory-sync-client.js";
 import type { MemoryProjectKey } from "./project-identity.js";
 export interface MemoryProjectLayers {
@@ -25,8 +7,8 @@ export interface MemoryProjectLayers {
     prepare(config: Pick<ServiceConfig, "requirePrincipal" | "memorySync">, scope: string | undefined, taskRoot: string | undefined): Promise<MemoryProjectKey | undefined>;
 }
 export declare function createMemoryProjectLayers(deps: {
-    /** 本部署的记忆引擎 backend(File 或 SQL 孪生);缺席 ⇒ 没有可折的盘(记忆暗时调用方根本不会问)。 */
-    backend: MemoryBackend | undefined;
+    /** 本部署的记忆作用域店(= 入口装配出的记忆引擎对象);缺席 ⇒ 没有可折的盘(记忆暗时调用方根本不会问)。 */
+    stores: MemoryScopeStores | undefined;
     /** 同步腿(开同步时在场):跟踪当前层;有东西要折时折叠排进它的串行链。 */
     syncRunner: Pick<MemorySyncRunner, "track" | "exclusive"> | undefined;
     log: {

package/dist/memory-project-layer.js

@@ -1,10 +1,13 @@
 import { migrateScope } from "@sema-agent/core";
 import { memoryProjectLayerFor } from "./memory-scope.js";
 export function createMemoryProjectLayers(deps) {
-    const fold = async (backend, from, to) => {
+    const fold = async (stores, from, to) => {
         let report;
         try {
-            report = await migrateScope(backend, from, to);
+            const store = stores.storeOf(to);
+            if (stores.storeOf(from) !== store)
+                throw new Error(`the layers ${JSON.stringify(from)} and ${JSON.stringify(to)} live in two different memory stores — a fold moves entries inside one store`);
+            report = await migrateScope(store, from, to);
         }
         catch (err) {
             deps.log.warn("memory_project_layer_fold_failed", { from, to, err: String(err), note: "entries stay where they are; the next task in this project retries" });
@@ -16,10 +19,10 @@ export function createMemoryProjectLayers(deps) {
             deps.log.warn("memory_project_layer_fold_conflicts", { from, to, conflicts: report.conflicts.length, note: "conflicting entries stay in the old layer; the next task in this project retries" });
         }
     };
-    const occupied = async (backend, sources) => {
+    const occupied = async (stores, sources) => {
         const out = [];
         for (const from of sources) {
-            if ((await backend.listHeaders([from])).some((h) => h.scope === from))
+            if ((await stores.storeOf(from).listHeaders([from])).some((h) => h.scope === from))
                 out.push(from);
         }
         return out;
@@ -30,11 +33,11 @@ export function createMemoryProjectLayers(deps) {
             const current = layer?.key.scope;
             if (layer === undefined || current === undefined)
                 return layer?.key;
-            const backend = deps.backend;
-            if (backend !== undefined && (await occupied(backend, layer.foldFrom)).length > 0) {
+            const stores = deps.stores;
+            if (stores !== undefined && (await occupied(stores, layer.foldFrom)).length > 0) {
                 const foldAll = async () => {
-                    for (const from of await occupied(backend, layer.foldFrom))
-                        await fold(backend, from, current);
+                    for (const from of await occupied(stores, layer.foldFrom))
+                        await fold(stores, from, current);
                 };
                 await (deps.syncRunner !== undefined ? deps.syncRunner.exclusive(foldAll) : foldAll());
             }

package/dist/memory-scope-stores.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 记忆作用域店 —— 「一层住在哪只店」在本宿主的**唯一读者**。
+ *
+ * ## 规则(一条)
+ * 一层(scope)的条目住哪只店,只有引擎的 `resolveMemoryScopeStore` 答;本服务在会话之外读写某一层的每一条腿(同步执行器、项目层折叠、
+ * 中心侧导出 / 同步、bundle 导出导入、合规抹除 / 出处、外源标记、会话记忆状态、整理)一律问**本对象**,不再自持「部署的店」当某一层的答案。
+ * 本对象就是起服装配出来的那只记忆引擎对象(`boot/stores.ts` 的 `memoryEngine`、`run-local.ts` 的同名量):它的 `backend` / `root`
+ * 正是交给 Runner 的两件事实(`RunnerDeps.memoryBackend` / `RunnerDeps.memoryEngineDir`),会话装配解析一层的店读的也是这两件 ——
+ * 所以宿主腿与会话对同一层答同一只店。每进程一只,所有腿共用(引擎的话:每层解析一次、留着用)。
+ *
+ * ## 喂给引擎的契约
+ * `scopeContract` = 本服务铸 spec 时给会话盖的同一只判据 {@link memoryScopeContractOf}(按层问与按会话问答同一只店,理由见该函数注)。
+ *
+ * ## 先判平面,再建店;一只平面一只实例
+ * 目录钉住的部署上,引擎对个人平面的答案是在个人挂载上**新开**的一只 File 店(契约原话:一只挂载;打开 = 建目录、收尾中断的事务、读台账)。
+ * 层键是调用方给的串,所以本对象**先**问平面、**再**按平面取店:
+ *  · 平面 = 引擎同一只读法 `resolveMemoryScopeStore` 在一只**不钉目录**的探针店上的答案。引擎契约:不钉目录的店对个人平面原样答回
+ *    入参店(「the personal plane shares a backend without a directory」)、项目平面恒答部署的店 ⇒ 这一问只得平面、零建店零读盘,
+ *    层键读不出照样抛引擎的 `config.memory_scope_key`(同一只校验)。不在本层另写分类(另写就是第二个读者)。
+ *  · 店 = 每个平面第一次用到时问引擎一次(真店入参),留下这一只;同平面的后来层复用它 —— 每个本对象至多两只店(项目 / 个人),
+ *    「两层同店」按实例判(下面的路由读它)。不按层键缓存:任意多把新层键不建店、不读盘、本对象不长。
+ * 🚧 平面的读法待引擎导出纯分类函数(`classifyScopePlanes` / `scopePlanesOf`)后改读它、删探针店;钉在 `test/memory-layer-seat-http.test.ts`。
+ *
+ * ## 请求的店({@link memoryStoreForRequest})
+ * 动词按它的请求**点名的层**取店;点名的几层不在同一只店 ⇒ 响亮拒(一次请求只落一只店)。请求不点名层的动词(条目 id、店级账本)
+ * 答在**本部署点名的层与部署的店共处的那一只店**上(`memoryLayersNamedBy`:全局层 / 同步层 / 登记簿种子 / 整理层);它们分住两只店时
+ * 不猜,响亮拒并指路「在请求里点名层」。单店部署(缺省 `local`、SQL 记忆后端、配置不点名个人平面键)上无层请求的答法与上一版逐字同。
+ *
+ * ## 本部署的店({@link memoryStoresOfDeployment})
+ * 部署的店 + 本部署点名的每一层住的店,去重、部署的店在前 —— 至多两只。会话 id 的动词读它:一只会话的记忆事实住在它各条腿写进的那只店
+ * (写家所在的平面),而单用户部署上会话的写家只会是项目层(部署的店)或全局层(点名的层),所以这张表就是「这只会话可能住的店」的全集。
+ */
+import { type MemoryBackend } from "@sema-agent/core";
+export interface MemoryScopeStores {
+    /** 部署的记忆后端 —— 交给 Runner 的那一只(`RunnerDeps.memoryBackend`)。它是「层在哪只店」那只读法的输入、项目平面的店本身,
+     *  不是任何一层的答案(层的答案只出自 {@link MemoryScopeStores.storeOf})。 */
+    readonly backend: MemoryBackend;
+    /** 引擎根 —— 交给 Runner 的那一个值(`RunnerDeps.memoryEngineDir`):读法的另一件输入(个人挂载在它下面),也是同步游标的根。 */
+    readonly root: string;
+    /** 层 `layer` 住的那只店(引擎的唯一读法;先判平面、每个平面一只实例)。引擎读不出的层键 ⇒ 抛引擎的 `config.memory_scope_key`,原样。 */
+    storeOf(layer: string): MemoryBackend;
+    /** 本部署配置点名的层(每次现读 —— 登记簿热换)。 */
+    namedLayers(): readonly string[];
+}
+/** 命名照工厂律:返回带行为的活对象 ⇒ `create*`。 */
+export declare function createMemoryScopeStores(input: {
+    backend: MemoryBackend;
+    root: string;
+    namedLayers: () => readonly string[];
+    /** 本对象为一层开出的店(个人平面的 File 店)的构造期 incident 座(与部署的店那只同一只汇点;缺席合法)。 */
+    onIncident?: (err: Error & {
+        code?: string;
+    }) => void;
+}): MemoryScopeStores;
+/** 本服务的「这次请求落不到一只记忆店」拒(400 `request.memory_layer`):点名的层读不出 / 点名的几层分住两只店 / 两店部署上没点名层。 */
+export declare class MemoryLayerRefusal extends Error {
+    readonly code: "request.memory_layer";
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * 一次请求的记忆店。`layers` = 请求点名的层(空 = 没点名):
+ *  · 点名 ⇒ 它们共住的那一只店;分住两只 ⇒ 拒(一次请求只落一只店,按店拆成几次请求)。
+ *  · 没点名 ⇒ 本部署点名的层与部署的店共处的那一只(= 部署的店);它们分住两只 ⇒ 拒,指路在请求里点名层。
+ * `seat` = 这个动词点名层的那一处(拒句里指路用,如 `` `scope` ``;缺省 = 层座 `scope`)。
+ * 拒一律 {@link MemoryLayerRefusal}(读不出的层键同码,引擎原句随句)。
+ */
+export declare function memoryStoreForRequest(stores: MemoryScopeStores, layers: readonly string[], seat?: string): MemoryBackend;
+/**
+ * 本部署的店:部署的店在前,其后是本部署点名的层住的其余店(去重)—— 单店部署恰一只(部署的店本身)。点名的层读不出 ⇒ {@link MemoryLayerRefusal}(同无层那一臂)。
+ * 每次现算(登记簿热换当场生效);只问平面与每平面一只的店,不建多余的店。
+ */
+export declare function memoryStoresOfDeployment(stores: MemoryScopeStores, seat?: string): readonly MemoryBackend[];
+//# sourceMappingURL=memory-scope-stores.d.ts.map

package/dist/memory-scope-stores.js

@@ -0,0 +1,86 @@
+import { resolveMemoryScopeStore } from "@sema-agent/core";
+import { memoryScopeContractOf } from "./memory-scope.js";
+export function createMemoryScopeStores(input) {
+    const byPlane = new Map();
+    const resolve = (layer, backend) => resolveMemoryScopeStore({
+        scope: layer,
+        scopeContract: memoryScopeContractOf([layer]),
+        backend,
+        memoryEngineDir: input.root,
+        ...(input.onIncident !== undefined ? { onIncident: input.onIncident } : {}),
+    });
+    return {
+        backend: input.backend,
+        root: input.root,
+        namedLayers: input.namedLayers,
+        storeOf(layer) {
+            const { plane } = resolve(layer, PLANE_PROBE);
+            const known = byPlane.get(plane);
+            if (known !== undefined)
+                return known;
+            const store = resolve(layer, input.backend).backend;
+            byPlane.set(plane, store);
+            return store;
+        },
+    };
+}
+const PLANE_PROBE = Object.freeze({});
+export class MemoryLayerRefusal extends Error {
+    code = "request.memory_layer";
+    constructor(message, cause) {
+        super(message, cause !== undefined ? { cause } : undefined);
+        this.name = "MemoryLayerRefusal";
+    }
+}
+const quoted = (layers) => layers.map((l) => JSON.stringify(l)).join(", ");
+function storeOfNamed(stores, layer, whose, seat) {
+    try {
+        return stores.storeOf(layer);
+    }
+    catch (err) {
+        if (err?.code !== "config.memory_scope_key")
+            throw err;
+        const why = err instanceof Error ? err.message : String(err);
+        throw new MemoryLayerRefusal(whose === "request"
+            ? `the memory layer ${JSON.stringify(layer)} cannot be read: ${why}`
+            : `this deployment's configured memory layer ${JSON.stringify(layer)} cannot be read (${why}), so the store a request that names no layer belongs to cannot be told — name the layer in the request (${seat})`, err);
+    }
+}
+export function memoryStoreForRequest(stores, layers, seat = "`scope`") {
+    if (layers.length > 0) {
+        const groups = new Map();
+        for (const layer of layers) {
+            const store = storeOfNamed(stores, layer, "request", seat);
+            const group = groups.get(store);
+            if (group === undefined)
+                groups.set(store, [layer]);
+            else
+                group.push(layer);
+        }
+        if (groups.size === 1)
+            return [...groups.keys()][0];
+        const split = [...groups.values()].map((g) => `[${quoted(g)}]`).join(" / ");
+        throw new MemoryLayerRefusal(`the memory layers ${quoted(layers)} live in ${groups.size} different memory stores on this deployment and one request reaches one store — send one request per store: ${split}`);
+    }
+    const groups = deploymentStoreGroups(stores, seat);
+    if (groups.size === 1)
+        return stores.backend;
+    const elsewhere = [...groups.entries()].filter(([store]) => store !== stores.backend).flatMap(([, g]) => g);
+    throw new MemoryLayerRefusal(`this deployment keeps memory layers in ${groups.size} stores — the project layers${groups.get(stores.backend).length > 0 ? ` and ${quoted(groups.get(stores.backend))}` : ""} in the deployment's store, ${quoted(elsewhere)} in another — so a request that names no layer cannot be told which store it means; name the layer in the request (${seat})`);
+}
+export function memoryStoresOfDeployment(stores, seat = "`scope`") {
+    return [...deploymentStoreGroups(stores, seat).keys()];
+}
+function deploymentStoreGroups(stores, seat) {
+    const groups = new Map([[stores.backend, []]]);
+    for (const layer of stores.namedLayers()) {
+        const store = storeOfNamed(stores, layer, "deployment", seat);
+        const group = groups.get(store);
+        if (group === undefined)
+            groups.set(store, [layer]);
+        else
+            group.push(layer);
+    }
+    return groups;
+}
+//# sourceMappingURL=memory-scope-stores.js.map

package/dist/memory-scope.d.ts

@@ -8,11 +8,35 @@ export declare const V2_SCOPE_PREFIXES: readonly string[];
  * 一个 scope 键是否带 v2 typed 前缀。
  *
  * ⚠️ 判据刻意停在**前缀**层,不升级成 core 的 `parseScopeKey`:后者对「带可识别前缀但结构坏」的键
- * 是 fail-loud 抛错,而本谓词的两个调用点都只是在决定「要不要挂 v2 标 / 要不要再包一层」——把抛点
- * 挪到这里会把 core 的校验时机整体前移(行为面改动,不在本条案的射程内)。坏键仍由 core 在它自己的
- * 校验点 fail-loud。
+ * 是 fail-loud 抛错,而本谓词的两个读者都只是在决定「要不要挂 v2 标({@link memoryScopeContractOf})/
+ * 同步层要不要另给(`config.ts`)」——把抛点挪到这里会把 core 的校验时机整体前移(行为面改动,不在本条案的射程内)。
+ * 坏键仍由 core 在它自己的校验点 fail-loud。
  */
 export declare function isV2ScopeKey(key: string): boolean;
+/**
+ * 本服务给一组记忆层盖的**作用域契约**(core `TaskSpec.memory.scopeContract`)—— 一个判据、两个读者:
+ *  · {@link memorySpecForRequest} 铸 spec 时盖在会话上的那一个(读列表 = 全局层 + 登记簿种子);
+ *  · 同步执行器替一层问「这一层在哪只店」时报给引擎的那一个(`resolveMemoryScopeStore` 的 `scopeContract`,`memory-sync-client.ts`)。
+ * 契约决定**类型化键落哪个平面**(v2 下 `user:` / `userproj:` / `org:` 在个人平面,不透明键在项目平面;不声明则一律项目平面),
+ * 所以两个读者必须读同一只:会话把一层放在哪只店,同步就同步哪只店。
+ *
+ * 判据:列表里有类型化键(前缀表 {@link V2_SCOPE_PREFIXES})⇒ `"v2"`;没有 ⇒ `undefined`(不声明;显式 opt-in,不嗅探调用方数据 ——
+ * 这些键只来自本服务自己的铸点与运维的登记簿,见 {@link memorySpecForRequest} 的 142-S1.5 注)。
+ * 按层问与按会话问答同一只店:平面按**每把键自己的种类**分,契约只挪类型化键,而本判据下带类型化键的会话恒盖 `"v2"`。
+ * 🚧 前提是键为规范形:引擎读键前去掉首尾空白,本判据看原串 —— 带首尾空白的类型化键(`" user:alice"`,配置边界今天放行)本判据不认、引擎在 v2 下读得出,
+ * 于是同一把键在带类型化种子的会话里落个人平面、在不带种子的会话与同步执行器里落项目平面。这是会话面先有的不一致(不同项目的会话对同一层就答两只店,
+ * 同步执行器无从同时对上两者),收口点在配置边界(拒或规范化这一形,后者会挪存量记忆的平面),不在本谓词;未闭环。
+ */
+export declare function memoryScopeContractOf(scopes: readonly string[]): "v2" | undefined;
+/**
+ * 本部署**自己点名**的记忆层 —— 配置里写着的每一层(去重、去空串、保序):单用户的全局层(`MEMORY_SCOPE`,{@link memoryScopeFor} 单用户臂的答案)、
+ * 同步层(`MEMORY_SYNC_SCOPE`,缺省即全局层)、项目登记簿的种子层(`config.projects[*].defaultScopes`,{@link memorySpecForRequest} 盖进会话的读列表)、
+ * 整理层(`MEMORY_CONSOLIDATION_SCOPES`)。项目层(`userrepo:…`)按任务根铸、不在配置里,也就不在这里 —— 它们住部署的店。
+ *
+ * 唯一读者:记忆作用域店的「不点名层的动词答在哪只店」(`memory-scope-stores.ts` 的 {@link memoryStoreForRequest} 无层那一臂)。
+ * 登记簿随中心配置热换(`applyEffective` 在同一只 `config.projects` 对象上原地整表换内容),所以读者每次现调本函数,不在起服时冻一份。
+ */
+export declare function memoryLayersNamedBy(config: Pick<ServiceConfig, "requirePrincipal" | "memoryScope" | "memorySync" | "projects" | "memoryConsolidationDriver">): string[];
 /** Resolve the memory scope for a request —— {@link memoryScopeFor} 的三形(按实现逐臂写;[ref] 合并前主会话点名:
  *  旧版这里写「多租户恒 `undefined` ⇒ 记忆暗」,与下面 DB 后端那一臂正好相反,test [ref] 就是被这句带偏的)。
  *
@@ -93,8 +117,8 @@ export declare function replicatesProjectLayersOf(coverage: MemoryReplicationCov
  * Pure posture probe (memoryEngineBackendFor consumes it; main.ts logs it): `undefined` = no plane split
  * (the lane's file plane IS this worker's fs — `in-process` / `host`), `dark` = split + fail-closed, `forced` =
  * split + operator override.
- * [ref]: the plane question reads the lane-caps table (`hostFilePlane`) — it used to be the hand-written synonym
- * `lane === undefined || lane === "host"` (fold-ban gate D, R3); readings are unchanged lane by lane.
+ * The plane question reads the execution environment block (`hostLocalPaths`, sole author `capabilitiesFor`) — it used to be the
+ * hand-written synonym `lane === undefined || lane === "host"`; readings are unchanged lane by lane.
  */
 export declare function memoryEngineRemoteLanePosture(config: ServiceConfig): {
     lane: ExecutionLane;

package/dist/memory-scope.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { FileMemoryEngineBackend, resolveMemoryEngineRoot, deriveControlPlaneDir, formatUserScope, formatProjScope, normalizeMemorySpec } from "@sema-agent/core";
-import { executionLaneCaps, executionLaneOf } from "./execution-lane-caps.js";
+import { capabilitiesFor, executionLaneOf } from "./execution-lane-caps.js";
 import { assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
 import { projectLayerForTaskRoot } from "./project-identity.js";
 import { parseProjectLayerKey, projectLayerOwnerOf } from "./project-layer-key.js";
@@ -14,6 +14,18 @@ export const V2_SCOPE_PREFIXES = Object.freeze(Object.values(V2_SCOPE_PREFIX_BY_
 export function isV2ScopeKey(key) {
     return V2_SCOPE_PREFIXES.some((prefix) => key.startsWith(prefix));
 }
+export function memoryScopeContractOf(scopes) {
+    return scopes.some(isV2ScopeKey) ? "v2" : undefined;
+}
+export function memoryLayersNamedBy(config) {
+    const named = [
+        ...(config.requirePrincipal === true ? [] : [config.memoryScope]),
+        ...(config.memorySync !== undefined ? [config.memorySync.scope] : []),
+        ...Object.values(config.projects ?? {}).flatMap((p) => p.defaultScopes ?? []),
+        ...config.memoryConsolidationDriver.scopes,
+    ];
+    return named.filter((s, i) => typeof s === "string" && s.length > 0 && named.indexOf(s) === i);
+}
 export { MEMORY_SCOPE_COLUMN_CHARS, assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
 export function memoryScopeFor(config, principal, projectId) {
     if (config.requirePrincipal === true) {
@@ -64,7 +76,7 @@ export function replicatesProjectLayersOf(coverage, owner) {
 }
 export function memoryEngineRemoteLanePosture(config) {
     const lane = executionLaneOf(config.remoteExec?.provider);
-    if (executionLaneCaps(lane).hostFilePlane === "supported")
+    if (capabilitiesFor(config).hostLocalPaths)
         return undefined;
     return { lane, posture: config.memoryEngineRemoteLaneAllowed === true ? "forced" : "dark" };
 }
@@ -158,14 +170,14 @@ export function memorySpecForRequest(scope, projectKey, memoryWrite, defaultScop
         throw new Error(`memory project scope ${JSON.stringify(projectScope)} equals the global memory scope (MEMORY_SCOPE) — the project layer and the global layer would be one directory. ` +
             "Set MEMORY_SCOPE to a name outside the server-minted project-key families (see src/project-layer-key.ts).");
     }
-    const isV2 = isV2ScopeKey;
     const extras = (defaultScopes ?? []).filter((s, i, arr) => typeof s === "string" && s.length > 0 && s !== scope && s !== projectScope && arr.indexOf(s) === i);
     const layered = projectKey !== undefined
         ? { scopes: projectScope !== undefined ? [projectScope, scope, ...extras] : [scope, ...extras], writeScope: projectScope ?? scope, projectKey }
         : extras.length > 0
             ? { scopes: [scope, ...extras], writeScope: scope }
             : { scopes: [scope] };
-    const v2 = isV2(scope) || extras.some(isV2) ? { scopeContract: "v2" } : {};
+    const contract = memoryScopeContractOf([scope, ...extras]);
+    const v2 = contract !== undefined ? { scopeContract: contract } : {};
     const stamped = {};
     if (originPolicy !== undefined) {
         if (scope.startsWith("org:"))