@sema-agent/server 7.145.0 → 7.147.0

package/dist/plugins/local-session-store.js

@@ -1,26 +1,27 @@
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { lstat, readFile } from "node:fs/promises";
+import { closeSync, existsSync, fsyncSync, lstatSync, openSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { isDeepStrictEqual } from "node:util";
 import { dirname, join, resolve } from "node:path";
+import { atomicWriteFileAsync } from "./owner-only-file-mode.js";
 import { assertFirstOwnerWritable, forkOwnerOf, importerOwnerOf, placedSessionOwnerOf } from "./session-ownership.js";
 import { SessionOwnerUnreadableError, StampedSessionArchiveError, sessionUnreadableOf } from "../session-error-wire.js";
-import { FileSessionRepo, SessionError, StoredSession, admitSessionPlacement, atomicWriteFile, sessionLogMarkOf, settledForkOptions, uuidv7, validateEntriesForImport } from "@sema-agent/core";
+import { FileSessionRepo, SessionError, StoredSession, admitSessionPlacement, atomicWriteFile, ensureDir, sessionLogMarkOf, settledForkOptions, uuidv7, validateEntriesForImport } from "@sema-agent/core";
 import { placementCapabilityOf } from "./session-placement.js";
 import { z } from "zod";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
-import { StoreBootRefusalError } from "./store-contracts.js";
+import { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
 import { judgeSessionRowWrite, sessionRowTagKey, settleSessionRowWrite, } from "../session-row.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
-import { createZodColumnReader, decodeJsonColumn, isJsonColumnBodyProblem, readStringRecordColumn, SqlJsonColumnError } from "./sql-json-column.js";
-import { SCHEMA_MISMATCH_ERROR_CODE } from "./schema-consistency.js";
-import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./one-time-migrations.js";
+import { createZodColumnReader, decodeJsonColumn, isJsonColumnBodyProblem, isJsonObject, readJsonObjectColumn, readStringRecordColumn, SqlJsonColumnError } from "./sql-json-column.js";
+import { RENAMED_EXECUTION_LANE_M40, RETIRED_EXECUTION_LANE_WORD_M40 } from "./execution-lane-rename-m40.js";
+import { ExecutionLaneRenameWriteRefusedError, ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./one-time-migrations.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { createLogger } from "../observability/logger.js";
-import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
+import { UNMANAGED_RETENTION } from "./retention-declaration.js";
 import { UnreadableLeaf, carriedRowCells, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { isExecutionLane } from "../execution-lane-caps.js";
-import { SessionForkInProgressError, SessionWriterPresentError, WRITABLE, assertPlaceableLane, isUnusableArchive, settledMirrorOutcome, settledPlaceOutcome, } from "../execution-placement.js";
+import { SessionForkInProgressError, WRITABLE, assertPlaceableLane, isUnusableArchive, judgeImportWrite, settledMirrorOutcome, settledPlaceOutcome, } from "../execution-placement.js";
 import { classifyForkTarget, forkByFreshId } from "./session-fork.js";
 import { decodeInstructionSource, encodeInstructionSource, sameInstructionSourceBaseline } from "../instruction-source-notice.js";
 import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
@@ -126,9 +127,13 @@ function rowMetadataOf(sessionId, meta) {
     return { id: sessionId, createdAt: rowCreatedAtOf(sessionId, meta), owner: face.owner, incarnation: face.incarnation, ...(meta.forkedFrom !== undefined ? { forkedFrom: meta.forkedFrom } : {}) };
 }
 const isForkCreatedCell = (meta) => meta !== undefined && meta.forkKey !== undefined && meta.execution === undefined;
+function placementCellOf(meta, forking) {
+    return forking ? { role: "forking" } : (meta?.execution ?? { role: "absent" });
+}
 function readingOfCell(sessionId, meta, forking) {
-    return { occupant: sessionFaceFromRow(sessionId, meta.owner ?? null, meta.incarnation), cell: forking ? { role: "forking" } : (meta.execution ?? { role: "absent" }) };
+    return { occupant: sessionFaceFromRow(sessionId, meta.owner ?? null, meta.incarnation), cell: placementCellOf(meta, forking) };
 }
+const SESSION_META_SIDECAR_FILE = "session-incarnations.json";
 const LOCAL_EXECUTION_CELL = z.discriminatedUnion("role", [
     z.object({ role: z.literal("writer"), lane: z.custom((v) => typeof v === "string" && isExecutionLane(v), { message: "not an execution lane" }) }).strict(),
     z.object({ role: z.literal("mirror") }).strict(),
@@ -154,18 +159,23 @@ function ownerClaimWindowOpen() {
 const SIDECAR_MAP_STATE_BY_PATH = new Map();
 const SESSION_WRITE_LOCKS_BY_ROOT = new Map();
 const quotedFieldNames = (names) => `${names.slice(0, 8).map((name) => JSON.stringify(name.slice(0, 64))).join(", ")}${names.length > 8 ? `, … (${names.length} in all)` : ""}`;
+function describeDataRootFinding(f) {
+    if (f.problem === "newer-engine") {
+        return `  ${f.label} at ${f.path}: engine high-water ${f.engineHighWater.highWater} — the data root has been opened by server ${f.engineHighWater.highWater}, NEWER than this build (${f.engineHighWater.engine}).`;
+    }
+    return f.unknownFields.length > 0
+        ? `  ${f.label} at ${f.path}: UNKNOWN field(s) ${quotedFieldNames(f.unknownFields)} — the data root is NEWER than this build (a newer server engine wrote it).`
+        : `  ${f.label} at ${f.path}: unreadable (${f.problem}) — this build cannot read it, and an unreadable file is treated as a mismatch, not as empty.`;
+}
 function describeLocalDataRootMismatch(findings, when) {
     const lines = [
         when === "boot"
             ? `${SCHEMA_MISMATCH_ERROR_CODE}: the local data root does not match this build's shape — refusing to start.`
             : `${SCHEMA_MISMATCH_ERROR_CODE}: the local data root does not match this build's shape — refusing to read or write the file(s) named below until this process is restarted.`,
     ];
-    for (const f of findings) {
-        lines.push(f.unknownFields.length > 0
-            ? `  ${f.label} at ${f.path}: UNKNOWN field(s) ${quotedFieldNames(f.unknownFields)} — the data root is NEWER than this build (a newer server engine wrote it).`
-            : `  ${f.label} at ${f.path}: unreadable (${f.problem}) — this build cannot read it, and an unreadable file is treated as a mismatch, not as empty.`);
-    }
-    lines.push("This build never reads such a file as empty and never writes over it: either would silently change what the file records.", "", "  Ways out (these three and no others):", "    (1) the data root is NEWER than this build (unknown fields): deploy the build that wrote it;", "    (2) roll back: restore the data-root backup taken before the upgrade, then start this build — also the way out when the file's bytes are damaged (not-json / malformed);", "    (3) the file could not be read at all (an I/O error such as EACCES): repair access to it (permissions, mount, disk) and restart — nothing in the file needs changing.", "The check behind this refusal only reads: the file was left in place and nothing in the data root was changed.");
+    for (const f of findings)
+        lines.push(describeDataRootFinding(f));
+    lines.push("This build never reads such a file as empty and never writes over it: either would silently change what the file records.", "", "  Ways out (these three and no others):", "    (1) the data root is NEWER than this build (unknown fields, or an engine high-water above this build): deploy the build that wrote it (for a high-water: server at or above it) — to run an older build on this machine, give it its own data root (LOCAL_DATA_ROOT);", "    (2) roll back: restore the data-root backup taken before the upgrade, then start this build — also the way out when the file's bytes are damaged (not-json / malformed);", "    (3) the file could not be read at all (an I/O error such as EACCES): repair access to it (permissions, mount, disk) and restart — nothing in the file needs changing.", "The check behind this refusal only reads: the file(s) named above were left in place, unchanged.");
     return lines.join("\n");
 }
 export class LocalDataRootSchemaMismatchError extends StoreBootRefusalError {
@@ -179,6 +189,56 @@ export class LocalDataRootSchemaMismatchError extends StoreBootRefusalError {
         this.name = "LocalDataRootSchemaMismatchError";
     }
 }
+export async function readDataRootFileText(path) {
+    try {
+        return { state: "text", text: await readFile(path, "utf8") };
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT")
+            return { state: "unreadable", fault: e };
+        return judgedAfterEnoent(e, await lstat(path).then(() => ENTRY_PRESENT, (fault) => ({ fault })));
+    }
+}
+export function readDataRootFileTextSync(path) {
+    try {
+        return { state: "text", text: readFileSync(path, "utf8") };
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT")
+            return { state: "unreadable", fault: e };
+        let probe = ENTRY_PRESENT;
+        try {
+            lstatSync(path);
+        }
+        catch (fault) {
+            probe = { fault };
+        }
+        return judgedAfterEnoent(e, probe);
+    }
+}
+const ENTRY_PRESENT = { present: true };
+function judgedAfterEnoent(readFault, probe) {
+    if ("present" in probe)
+        return { state: "unreadable", fault: readFault };
+    return probe.fault?.code === "ENOENT" ? { state: "absent" } : { state: "unreadable", fault: probe.fault };
+}
+export function dataRootMismatchOf(path, label, fault) {
+    if (fault instanceof SqlJsonColumnError)
+        return { path, label, problem: fault.problem, unknownFields: fault.unknownKeys };
+    const code = fault?.code;
+    return { path, label, problem: typeof code === "string" && /^E[A-Z0-9_]+$/.test(code) ? code : "unreadable", unknownFields: [] };
+}
+async function readSessionMetaForM40(path) {
+    const raw = await readDataRootFileText(path);
+    if (raw.state !== "text")
+        return raw;
+    try {
+        return { state: "read", entries: decodeJsonColumn(raw.text, readJsonObjectColumn, `${SESSION_META_SIDECAR_FILE} (one-time migration M40)`) };
+    }
+    catch (e) {
+        return { state: "unreadable", fault: e };
+    }
+}
 class SidecarMap {
     path;
     label;
@@ -244,15 +304,11 @@ class SidecarMap {
             throw this.refuse(path, disk);
     }
     async readDisk(path) {
-        let text;
+        const raw = await readDataRootFileText(path);
+        if (raw.state !== "text")
+            return raw;
         try {
-            text = await readFile(path, "utf8");
-        }
-        catch (e) {
-            return e?.code === "ENOENT" ? { state: "absent" } : { state: "unreadable", fault: e };
-        }
-        try {
-            return { state: "read", entries: decodeJsonColumn(text, this.read, this.label) };
+            return { state: "read", entries: decodeJsonColumn(raw.text, this.read, this.label) };
         }
         catch (e) {
             return { state: "unreadable", fault: e };
@@ -260,9 +316,7 @@ class SidecarMap {
     }
     refuse(path, disk) {
         const shape = isJsonColumnBodyProblem(disk.fault);
-        const problem = disk.fault instanceof SqlJsonColumnError ? disk.fault.problem : (disk.fault?.code ?? "unreadable");
-        const unknownFields = disk.fault instanceof SqlJsonColumnError ? disk.fault.unknownKeys : [];
-        const refusal = new LocalDataRootSchemaMismatchError([{ path, label: this.label, problem, unknownFields }], "serving");
+        const refusal = new LocalDataRootSchemaMismatchError([dataRootMismatchOf(path, this.label, disk.fault)], "serving");
         if (shape)
             this.state.refused = refusal;
         return refusal;
@@ -300,9 +354,7 @@ class SidecarMap {
                     }
                 }
                 try {
-                    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-                    await writeFile(tmp, JSON.stringify(Object.fromEntries(draft)), "utf8");
-                    await rename(tmp, path);
+                    await atomicWriteFileAsync(path, JSON.stringify(Object.fromEntries(draft)), { durability: "best-effort" });
                 }
                 catch (e) {
                     this.onWriteFailed(e);
@@ -435,7 +487,6 @@ export class LocalSessionStore {
     flushTimer;
     writeChain = Promise.resolve();
     dirty = false;
-    writeSeq = 0;
     lastWarnAt = 0;
     sidecarPath;
     titles;
@@ -493,7 +544,7 @@ export class LocalSessionStore {
         this.pinned = sidecar("session-pinned.json", "pinned", readPinnedSidecar);
         this.instructionSources = sidecar("session-instruction-sources.json", "instruction-source", readStringRecordColumn);
         this.workspaces = sidecar("session-workspaces.json", "workspace", readStringRecordColumn);
-        this.meta = sidecar("session-incarnations.json", "session-meta", readSessionMetaSidecar, true);
+        this.meta = sidecar(SESSION_META_SIDECAR_FILE, "session-meta", readSessionMetaSidecar, true);
         const root = dataDir ? resolve(dataDir) : undefined;
         this.dataRoot = root;
         if (root !== undefined && !SESSION_WRITE_LOCKS_BY_ROOT.has(root))
@@ -509,6 +560,33 @@ export class LocalSessionStore {
             place: (sessionId, occupant, cell) => this.placeExecution(sessionId, occupant, cell),
         };
     }
+    async renameRetiredExecutionLaneWordM40() {
+        if (this.dataRoot === undefined)
+            return 0;
+        const path = join(this.dataRoot, SESSION_META_SIDECAR_FILE);
+        const disk = await readSessionMetaForM40(path);
+        if (disk.state !== "read")
+            return 0;
+        let renamed = 0;
+        for (const cell of Object.values(disk.entries)) {
+            if (!isJsonObject(cell))
+                continue;
+            const execution = cell["execution"];
+            if (!isJsonObject(execution) || execution["role"] !== "writer" || execution["lane"] !== RETIRED_EXECUTION_LANE_WORD_M40)
+                continue;
+            execution["lane"] = RENAMED_EXECUTION_LANE_M40;
+            renamed += 1;
+        }
+        if (renamed === 0)
+            return 0;
+        try {
+            await atomicWriteFileAsync(path, JSON.stringify(disk.entries), { durability: "best-effort" });
+        }
+        catch (e) {
+            throw new ExecutionLaneRenameWriteRefusedError(path, e);
+        }
+        return renamed;
+    }
     async assertStrictSidecarsReadable() {
         const loads = await Promise.allSettled(this.strictSidecars.map((map) => map.reconcile()));
         const findings = [];
@@ -943,10 +1021,8 @@ export class LocalSessionStore {
         this.dirty = false;
         const snapshot = Object.fromEntries(this.lastActivity);
         try {
-            await mkdir(join(path, ".."), { recursive: true });
-            const tmp = `${path}.${process.pid}.${++this.writeSeq}.tmp`;
-            await writeFile(tmp, JSON.stringify(snapshot), "utf8");
-            await rename(tmp, path);
+            ensureDir(dirname(path));
+            await atomicWriteFileAsync(path, JSON.stringify(snapshot), { durability: "best-effort" });
         }
         catch (e) {
             this.warnSidecar("write", e);
@@ -1106,6 +1182,9 @@ export class LocalSessionStore {
         });
     }
     async listSessions(opts) {
+        return (await this.listSessionRows(opts)).map((a) => a.row);
+    }
+    async listSessionRows(opts) {
         await this.loadRowSidecars();
         const rows = [];
         for (const header of await this.rowHeaders())
@@ -1116,16 +1195,18 @@ export class LocalSessionStore {
             const owner = this.ownerCellOf(row.sessionId);
             if (opts.owner !== undefined && owner !== opts.owner && !(opts.includeUnowned === true && owner === null))
                 continue;
-            all.push(await this.summaryOf(row, rollups));
+            const meta = this.metaCellOf(row.sessionId);
+            const incarnation = meta === undefined ? undefined : incarnationFromCell(row.sessionId, meta.incarnation, "absent");
+            all.push({ row: await this.summaryOf(row, rollups), occupant: { owner, incarnation } });
         }
         const qlc = opts.q?.toLowerCase();
-        const filtered = qlc ? all.filter((r) => r.objectivePreview?.toLowerCase().includes(qlc)) : all;
-        filtered.sort((a, b) => a.lastActivityAt !== b.lastActivityAt
+        const filtered = qlc ? all.filter(({ row: r }) => r.objectivePreview?.toLowerCase().includes(qlc)) : all;
+        filtered.sort(({ row: a }, { row: b }) => a.lastActivityAt !== b.lastActivityAt
             ? (a.lastActivityAt < b.lastActivityAt ? 1 : -1)
             : (a.sessionId < b.sessionId ? 1 : -1));
         const c = opts.cursor;
         const after = c
-            ? filtered.filter((r) => r.lastActivityAt < c.lastActivityAt || (r.lastActivityAt === c.lastActivityAt && r.sessionId < c.sessionId))
+            ? filtered.filter(({ row: r }) => r.lastActivityAt < c.lastActivityAt || (r.lastActivityAt === c.lastActivityAt && r.sessionId < c.sessionId))
             : filtered;
         return after.slice(0, opts.limit);
     }
@@ -1189,8 +1270,8 @@ export class LocalSessionStore {
             return null;
         }
     }
-    async fork(sourceId, owner) {
-        return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner);
+    async fork(sourceId, owner, opts) {
+        return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner, opts);
     }
     async forkTo(sourceId, owner, target) {
         await this.meta.ensureLoaded();
@@ -1215,20 +1296,24 @@ export class LocalSessionStore {
         const forkOwner = forkOwnerOf(owner, this.metaCellOf(sourceId)?.owner);
         const existing = this.metaCellOf(target.id);
         const targetArchived = await this.existsInRepo(target.id);
-        const copy = () => this.repo.fork(sourceMeta, { ...forkOptions, id: target.id });
+        const placement = this.placements !== undefined ? target.placement : undefined;
+        const copy = () => this.repo.fork(sourceMeta, { ...forkOptions, id: target.id, ...(placement !== undefined ? { placement } : {}) });
         if (existing === undefined && !targetArchived) {
             const created = await this.writeMeta(target.id, (before) => before !== undefined
                 ? undefined
                 : { incarnation: mintSessionIncarnation(), ...(forkOwner !== undefined ? { owner: forkOwner } : {}), ...(target.key !== undefined ? { forkKey: target.key } : {}), createdAt: rowBornNow(), forkedFrom: sourceId });
             if (!created)
                 throw new SessionError("storage", `LocalSessionStore: fork target ${target.id} gained a session-meta cell under its own write lock — refusing to guess`);
+            let forked;
             try {
-                await copy();
+                forked = await copy();
             }
             catch (err) {
                 await this.withdrawCreatedCell(target.id, err, (cause, drop) => `LocalSessionStore: fork into ${target.id} failed while copying (${cause}) and its target cell could not be withdrawn (${drop}) — the target stays in the fork-in-progress state; retry the same fork or delete the session`);
                 throw err;
             }
+            if (placement !== undefined)
+                await this.admitForkedPlacement(target.id, forked, placement);
             return { outcome: "created", id: target.id };
         }
         const out = classifyForkTarget(target, { owner: existing?.owner, forkKey: existing?.forkKey }, forkOwner);
@@ -1236,6 +1321,21 @@ export class LocalSessionStore {
             await copy();
         return out;
     }
+    async admitForkedPlacement(sessionId, forked, placement) {
+        try {
+            admitSessionPlacement(sessionId, (await forked.getMetadata()).placement, { placement }, placementCapabilityOf(this));
+        }
+        catch (refusal) {
+            try {
+                await this.repo.delete({ id: sessionId, createdAt: "" });
+            }
+            catch (left) {
+                throw new SessionError("placement_refused", `${refusal instanceof Error ? refusal.message : String(refusal)} — and the copy ${sessionId} this fork created could not be removed (${left instanceof Error ? left.message : String(left)}); delete the session by id`, refusal instanceof Error ? refusal : undefined);
+            }
+            await this.withdrawCreatedCell(sessionId, refusal, (cause, drop) => `LocalSessionStore: a placed fork into ${sessionId} was refused (${cause}); its copy was removed but its session-meta cell could not be withdrawn (${drop}) — the cell stays on disk, inert; delete the session to clear it`);
+            throw refusal;
+        }
+    }
     async exportEntries(sessionId) {
         if (!this.repo.exportEntries)
             return null;
@@ -1282,10 +1382,8 @@ export class LocalSessionStore {
             await this.assertNotPlacedHeld(sessionId);
         validateEntriesForImport(entries);
         const current = this.metaCellOf(sessionId);
-        if (current?.execution?.role === "writer")
-            throw new SessionWriterPresentError(sessionId, current.execution.lane);
-        if (await this.forkingOf(sessionId, current))
-            throw new SessionForkInProgressError(sessionId);
+        if (landing !== "judged")
+            await this.admitImportHeld(sessionId, current);
         if (!(await this.importMayLand(sessionId, current, owner, landing)))
             throw importRowRefused(sessionId, landing);
         const prior = await this.landImportCell(sessionId, owner);
@@ -1324,6 +1422,14 @@ export class LocalSessionStore {
             throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${placed.kind} placement partition (a delegated agent's transcript) — a session import cannot replace its log`);
         }
     }
+    async admitImportHeld(sessionId, current) {
+        const verdict = await judgeImportWrite(sessionId, {
+            claim: () => this.runs.getActiveTaskId(sessionId),
+            cell: async () => placementCellOf(current, await this.forkingOf(sessionId, current)),
+        });
+        if (verdict !== "proceed")
+            throw verdict.refuse;
+    }
     async importMayLand(sessionId, current, owner, landing) {
         switch (landing) {
             case "create":
@@ -1380,8 +1486,6 @@ export class LocalSessionStore {
             const current = await this.metaOf(sessionId);
             if (!ownerCellIs(opts.expectedOwner, current === undefined ? undefined : (current.owner ?? null)))
                 throw new StagedCommitOwnerChangedError(sessionId);
-            if (await this.forkingOf(sessionId, current))
-                throw new SessionForkInProgressError(sessionId);
             await this.assertNotPlacedHeld(sessionId);
             const dstEntries = await this.exportEntries(sessionId);
             const rel = classifySyncRelationshipByIds(staged.map((e) => e.id), dstEntries === null ? null : dstEntries.map((e) => e.id));
@@ -1397,8 +1501,7 @@ export class LocalSessionStore {
                 if (diverged)
                     throw new SyncConflictError(sessionId, contentForkRelation(diverged, rel.newEntryIds));
             }
-            if (current?.execution?.role === "writer")
-                throw new SessionWriterPresentError(sessionId, current.execution.lane);
+            await this.admitImportHeld(sessionId, current);
             if (rel.relation !== "identical" || !contentEqual) {
                 await this.importHeld(sessionId, importer, staged, "judged");
             }
@@ -1565,7 +1668,7 @@ export class LocalSessionStore {
         this.meta.syncToDisk();
         let anonymized = 0;
         if (listed.some((row) => (row.owner ?? null) !== null)) {
-            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            ensureDir(dir);
             fsyncPaths(dir, dirname(dir));
         }
         const keptStamped = [];

package/dist/plugins/local-task-attachment-store.d.ts

@@ -1,4 +1,6 @@
 import { type AttachmentStoreBindOutcome, type TaskAttachmentStore, type TaskAttachmentRecord } from "./task-attachment-store.js";
+/** 附件店在数据根下的目录(构造器与一次性迁移 M39 的名册同读这一只)。 */
+export declare function attachmentStoreDirFor(rootDir: string): string;
 export declare class LocalTaskAttachmentStore implements TaskAttachmentStore {
     private readonly dir;
     private metas;

package/dist/plugins/local-task-attachment-store.js

@@ -1,16 +1,21 @@
 import { promises as fsp } from "node:fs";
 import { join } from "node:path";
+import { ensureDir } from "@sema-agent/core";
 import { bindRowsInProcess, TaskAttachmentRecordSchema } from "./task-attachment-store.js";
 import { createZodColumnReader, decodeJsonColumn } from "./sql-json-column.js";
+import { atomicWriteFileAsync } from "./owner-only-file-mode.js";
 const ID_RE = /^[0-9a-f-]{16,64}$/i;
 const readAttachmentMeta = createZodColumnReader(TaskAttachmentRecordSchema);
+export function attachmentStoreDirFor(rootDir) {
+    return join(rootDir, "attachments");
+}
 export class LocalTaskAttachmentStore {
     dir;
     metas;
     hydration;
     mutationTail = Promise.resolve();
     constructor(rootDir) {
-        this.dir = join(rootDir, "attachments");
+        this.dir = attachmentStoreDirFor(rootDir);
     }
     hydrate() {
         this.hydration ??= (async () => {
@@ -46,14 +51,10 @@ export class LocalTaskAttachmentStore {
     put(rec) {
         return this.serialized(async () => {
             const metas = await this.hydrate();
-            await fsp.mkdir(this.dir, { recursive: true });
+            ensureDir(this.dir);
             const { content, ...meta } = rec;
-            const binTmp = join(this.dir, `${rec.id}.bin.tmp`);
-            const metaTmp = join(this.dir, `${rec.id}.json.tmp`);
-            await fsp.writeFile(binTmp, Buffer.from(content));
-            await fsp.rename(binTmp, join(this.dir, `${rec.id}.bin`));
-            await fsp.writeFile(metaTmp, JSON.stringify(meta));
-            await fsp.rename(metaTmp, join(this.dir, `${rec.id}.json`));
+            await atomicWriteFileAsync(join(this.dir, `${rec.id}.bin`), Buffer.from(content), { durability: "best-effort" });
+            await atomicWriteFileAsync(join(this.dir, `${rec.id}.json`), JSON.stringify(meta), { durability: "best-effort" });
             metas.set(rec.id, { ...meta });
         });
     }
@@ -73,9 +74,7 @@ export class LocalTaskAttachmentStore {
         }
     }
     async persistMeta(m) {
-        const tmp = join(this.dir, `${m.id}.json.tmp`);
-        await fsp.writeFile(tmp, JSON.stringify(m));
-        await fsp.rename(tmp, join(this.dir, `${m.id}.json`));
+        await atomicWriteFileAsync(join(this.dir, `${m.id}.json`), JSON.stringify(m), { durability: "best-effort" });
     }
     bind(owner, ids, sessionId, boundAtMs) {
         return this.serialized(async () => {

package/dist/plugins/memory-embedder-fingerprint.d.ts

@@ -25,29 +25,37 @@
  * 文件**(server 侧),移入文件零改动;表名常量本文件自有(`PG_MEMORY_ENGINE_TABLES` 不动)。
  * 列名 `meta_key`/`meta_value`:`key` 是 MySQL 保留字,将来若补 TiDB 腿零反引号坑(K2)。
  *
- * ## 六态(v2 总表)
+ * ## 六态(v2 总表)与处置律
  *
  * | 态 | 判定 | 动作 |
  * |---|---|---|
  * | A | embedder 配置缺席 | **门不装**(连 ensure 都不调),元表不动——装配点的事,不在本文件 |
  * | B | 元表有行、identity 逐键相等 | 照常,**零写** |
- * | C | 元表有行、不等 | 清列 → upsert 新 identity(`reason:"changed"`) |
- * | D | 元表无行、库内**有**非 NULL 向量 | 同 C 清(存量库无法证明同源=保守清,`reason:"unattributed"`) |
+ * | C | 元表有行、不等(`changed`) | 对不上 |
+ * | D | 元表无行、库内**有**非 NULL 向量(`unattributed`:存量无法证明同源) | 对不上 |
  * | E | 元表无行、零向量行 | 只写 identity,不清(`memory_embedder_identity_armed`) |
- * | F | 元表有行但 value 解析失败 | 走清空臂(`reason:"unreadable"`)——**绝不当成匹配**(边界必 schema) |
+ * | F | 元表有行但 value 解析失败(`unreadable`)——**绝不当成匹配**(边界必 schema) | 对不上 |
  *
  * (F 的判据是 `model`/`dimensions` 缺失或类型不对;**多出来的未知键不算坏**,见 schema 处的注。)
  *
+ * **处置律(一句)**:门从不凭自己的判断清列。「对不上」(C / D / F)⇒ **拒启**,拒句点名所处的态、记下的与配置的身份、
+ * 出路;唯一会清列的路径是运维**显式确认**这一次重嵌 —— `opts.reembedConfirmed`(装配点读 config 的
+ * `memoryEmbedder.reembedConfirmed`,即 env `MEMORY_EMBEDDER_REEMBED=<model>/<dimensions>`,config 层已判过它恰好点名本次配置的
+ * 身份)⇒ 清列 → upsert 新 identity,`memory_embedder_identity_changed` 照旧响亮。理由:清列不可逆(行只在下次被写时才重嵌),
+ * 拒启可逆(改回配置 / 确认 / 撤掉 embedder 走词面档,向量原样不动)。确认口令绑定身份 ⇒ 记下这个身份之后它判 B、不再有东西可确认。
+ *
  * ## 三条不可动的判据
  *
  * 1. **次序:先清列、后写元表**。反序若中间崩溃 = 新 identity 已记而旧向量还在 = 正是被修的病(此后
  *    每次 boot 恒判 B,残留态永不复检);正序中间崩溃 = 下次 boot 无元表行、向量已 NULL ⇒ E 态补记,
  *    幂等安全。
- * 2. **CAS 循环**(v2 C1-2):元表写后**重读**,读回≠自写 ⇒ 另一副本并发写了**不同** identity(部署
- *    配置漂移)⇒ 响亮 `memory_embedder_identity_conflict`(两值并示)+ 重跑比对,上限
- *    {@link CAS_MAX_ROUNDS} 轮,超限抛(拒启)。运行期旧副本混写非 CAS 可拦 ⇒ 归停机纪律(USAGE)。
+ * 2. **CAS 循环**(v2 C1-2):元表的写是**条件写** —— 只落在本轮判出的那一份上(判时没有行 ⇒ 只插入;判时有行 ⇒ 只在值仍是
+ *    读到的那段文本时改写),写后**重读**,读回≠自写 ⇒ 另一副本在判与写之间写了**不同** identity(部署配置漂移)⇒ 响亮
+ *    `memory_embedder_identity_conflict`(两值并示)+ 重跑比对(下一轮按别人的值判:未确认 ⇒ 拒启),上限 {@link CAS_MAX_ROUNDS} 轮,
+ *    超限抛(拒启)。条件写让「判与写之间被别人抢先」恒被读回看见 —— 盲 upsert 会把别人刚写下的身份(连同其后写进列里的另一空间向量)
+ *    静默盖成自己的。运行期旧副本混写非 CAS 可拦 ⇒ 归停机纪律(USAGE)。
  * 3. **门自身失败 = 抛(拒启)**。吞掉 = 元表停留旧值 = 下次 boot 再清一次,把一次性代价变成每次 boot
- *    的代价;且「门在场但没跑成」静默 = fail-open。
+ *    的代价;且「门在场但没跑成」静默 = fail-open。「对不上而未确认」同样是抛(处置律),先于任何写。
  *
  * ## 两条已知残余(codex 交叉复审 R1-F1/R1-F3,均判为真;处置=成文,不落码面)
  *
@@ -118,8 +126,13 @@ export interface EmbedderFingerprintReport {
     /** 收敛用了几轮(1 = 一次过;>1 = 中途撞到并发不同 identity)。 */
     rounds: number;
 }
-/** 比对腿的部署腿注入(日志 + 时钟)。日志缺席 = 纯静默跑(测试/脚本形),装配点必传。 */
+/** 比对腿的部署腿注入(日志 + 时钟 + 确认位)。日志缺席 = 纯静默跑(测试/脚本形),装配点必传。 */
 export interface ReconcileEmbedderFingerprintOptions {
+    /**
+     * 运维已确认「对不上时清掉向量列、按 `identity` 重嵌」(装配点 = config `memoryEmbedder.reembedConfirmed`)。
+     * 缺席 / `false` ⇒ 对不上(changed / unattributed / unreadable)一律拒启,一行不清、元表不写。
+     */
+    reembedConfirmed?: boolean;
     /** boot logger(`info` 报换模型/首装,`error` 报并发 identity 冲突)。 */
     log?: Pick<Logger, "info" | "error">;
     /** 耗时读数的时钟(默认 `Date.now`)——**整次调用**的耗时进日志(含 CAS 重试轮),
@@ -131,8 +144,18 @@ export interface ReconcileEmbedderFingerprintOptions {
  * 幂等,与其余 `ensurePg*Schema` 同姿势;新腿已注册 `PG_LEGS` + `docs/schema/baseline-pg.sql`。
  */
 export declare function ensurePgMemoryEmbedderMetaSchema(query: PgQueryFn): Promise<void>;
+/** 「对不上」的三态(处置律:未确认 ⇒ 拒启)。 */
+type MismatchState = Extract<EmbedderFingerprintState, "changed" | "unattributed" | "unreadable">;
+/**
+ * 「对不上而未确认」的拒句(纯数据:一条字符串)。点名所处的态 + 三态的闭集、记下的与配置的身份、出路(确认口令逐字可抄)。
+ * 每一态的「记下了什么」各一句;出路对三态同一张表,只有 changed 多一条「改回记下的身份」。
+ */
+export declare function buildEmbedderIdentityRefusal(state: MismatchState, recorded: EmbedderIdentity | {
+    unreadable: string;
+} | null, want: EmbedderIdentity): string;
 /**
- * 指纹比对腿 —— boot 一次(env 族是 boot 快照,运行中不热换)。**门自身失败一律抛**(拒启)。
+ * 指纹比对腿 —— boot 一次(env 族是 boot 快照,运行中不热换)。**门自身失败一律抛**(拒启);「对不上」而 `opts.reembedConfirmed`
+ * 不为真 ⇒ 抛 {@link buildEmbedderIdentityRefusal} 的拒句(处置律,先于任何写)。
  *
  * ⚠️ 调用姿势:`ensurePgMemoryEmbedderMetaSchema` 之后、memory backend 构造之前;embedder 配置**在场**
  * 才调(A 态连 ensure 都不调)。