@neta-art/cohub-cli 7.0.1 → 7.1.0

package/dist/runtime/projection-store.js

@@ -0,0 +1,103 @@
+import { fingerprintProjectionTurns, HttpError, isProjectionCompaction } from "@neta-art/cohub";
+import { getSessionProjectionTurn, listSessionProjectionTurns, projectTurnBatch } from "./turn-projection.js";
+export function rebindProjectionNativeSession(result, nativeSessionId) {
+    if (result.append)
+        return result;
+    const records = result.projection.records.map((entry) => {
+        if (entry.sourceTurnId !== null)
+            return entry;
+        if (entry.record.type === "session") {
+            return { ...entry, record: { ...entry.record, id: nativeSessionId, affinity: { ...entry.record.affinity, threadId: nativeSessionId } } };
+        }
+        if (entry.record.type === "session_meta") {
+            const payload = entry.record.payload;
+            return { ...entry, record: { ...entry.record, payload: { ...payload, id: nativeSessionId, session_id: nativeSessionId } } };
+        }
+        return entry;
+    });
+    return { ...result, projection: { ...result.projection, records } };
+}
+/** Reads durable Cohub turns and materializes one harness-specific native projection batch. */
+export class ProjectionStore {
+    source;
+    constructor(source) {
+        this.source = source;
+    }
+    async project(input, signal) {
+        const throughSequence = input.throughTurnId ? await this.sourceSequence(input.sessionId, input.throughTurnId, signal) : 0;
+        let source = await this.readTurns(input, throughSequence, signal);
+        if (source.append && source.turns.some((turn) => turn.messages.some(isProjectionCompaction))) {
+            source = { turns: await listSessionProjectionTurns(this.source, input.sessionId, { throughSequence, excludeTurnId: input.turnId, signal }), append: false };
+        }
+        const projection = projectTurnBatch({
+            spaceId: input.spaceId,
+            sessionId: input.sessionId,
+            nativeSessionId: input.nativeSessionId,
+            cwd: input.cwd,
+            provider: input.provider,
+            turns: source.turns,
+        }, input.target, !source.append);
+        const last = source.turns.at(-1);
+        const previous = source.append ? input.cursor : null;
+        return {
+            projection,
+            turns: source.turns,
+            append: source.append,
+            cursor: {
+                throughSequence: last?.sequence ?? previous?.throughSequence ?? null,
+                throughTurnId: last?.sourceTurnId ?? previous?.throughTurnId ?? null,
+                sourceFingerprint: last ? fingerprintProjectionTurns([last]) : previous?.sourceFingerprint ?? null,
+            },
+        };
+    }
+    async sourceSequence(sessionId, turnId, signal) {
+        const client = this.source.session(sessionId);
+        const response = await client.turns.get(turnId, { signal });
+        return response.turn.sequence;
+    }
+    async cursorForTurn(sessionId, turnId, signal) {
+        const turn = await getSessionProjectionTurn(this.source, sessionId, turnId, signal);
+        return {
+            throughSequence: turn.sequence,
+            throughTurnId: turn.sourceTurnId,
+            sourceFingerprint: fingerprintProjectionTurns([turn]),
+        };
+    }
+    async readTurns(input, throughSequence, signal) {
+        const cursor = input.cursor;
+        if (cursor?.throughSequence != null && cursor.throughSequence > throughSequence) {
+            return { turns: await listSessionProjectionTurns(this.source, input.sessionId, { throughSequence, excludeTurnId: input.turnId, signal }), append: false };
+        }
+        if (cursor?.throughTurnId && cursor.throughSequence != null) {
+            let anchor;
+            try {
+                anchor = await getSessionProjectionTurn(this.source, input.sessionId, cursor.throughTurnId, signal);
+            }
+            catch (error) {
+                if (!(error instanceof HttpError) || error.status !== 404)
+                    throw error;
+                anchor = null;
+            }
+            const anchorFingerprint = anchor ? fingerprintProjectionTurns([anchor]) : null;
+            if (anchorFingerprint !== cursor.sourceFingerprint) {
+                return {
+                    turns: await listSessionProjectionTurns(this.source, input.sessionId, { throughSequence, excludeTurnId: input.turnId, signal }),
+                    append: false,
+                };
+            }
+            return {
+                turns: await listSessionProjectionTurns(this.source, input.sessionId, {
+                    afterSequence: Math.max(1, cursor.throughSequence),
+                    throughSequence,
+                    excludeTurnId: input.turnId,
+                    signal,
+                }),
+                append: true,
+            };
+        }
+        return {
+            turns: await listSessionProjectionTurns(this.source, input.sessionId, { throughSequence, excludeTurnId: input.turnId, signal }),
+            append: false,
+        };
+    }
+}

package/dist/runtime/session-store.d.ts

@@ -1,10 +1,15 @@
 import { type RuntimeExecutionEvent, type HarnessArchive, type RuntimePendingExecution, type RuntimeTurnInput } from "@neta-art/cohub";
 import { RuntimeArchiveStore, type ArchiveTransport } from "./archive-store.js";
 import type { CodexTokenTotals } from "./codex-usage.js";
+import { type RuntimeDiagnosticContext, type RuntimeDiagnostics } from "./diagnostics.js";
+import type { SessionTurnProjectionClient } from "./turn-projection.js";
 export declare class ContextRequiredError extends Error {
-    readonly historyOnly: boolean;
-    constructor(message: string, historyOnly?: boolean);
 }
+export type RuntimeSessionStoreOptions = {
+    stateRoot?: string;
+    archiveTransport?: ArchiveTransport;
+    projectionSource: SessionTurnProjectionClient;
+};
 export type NativeSession = {
     version: 1;
     sessionId: string;
@@ -19,14 +24,31 @@ export type NativeSession = {
     resultChecksum?: string;
     archivePendingTurnId?: string;
     codexTokenTotals?: CodexTokenTotals;
+    projectionVersion?: 1;
+    sourceSequence?: number | null;
+    sourceTurnId?: string | null;
+    sourceFingerprint?: string | null;
+    nativeLeafId?: string | null;
 };
 /** Local references are hints validated against actual native files, never cloud existence claims. */
 export declare class RuntimeSessionStore {
     readonly root: string;
     readonly archives: RuntimeArchiveStore;
     private archiveFlush;
-    constructor(spaceId: string, stateRoot?: string, transport?: ArchiveTransport);
+    private diagnostics;
+    private readonly nativeWrites;
+    private readonly projectionStore;
+    constructor(spaceId: string, options: RuntimeSessionStoreOptions);
+    setDiagnostics(diagnostics: RuntimeDiagnostics): void;
     private statePath;
+    private nativePath;
+    private withNativeWrite;
+    private syncParentDirectory;
+    private writeNativeFile;
+    private appendNativeFile;
+    private lastNativeRecordId;
+    private reportProjectionWarnings;
+    private syncNativeProjection;
     pendingExecutionBatches(): AsyncGenerator<RuntimePendingExecution[]>;
     flushArchives(signal: AbortSignal): Promise<void>;
     private flushArchiveOutbox;
@@ -42,6 +64,6 @@ export declare class RuntimeSessionStore {
         state: NativeSession;
         events: RuntimeExecutionEvent[];
     } | null>;
-    archive(state: NativeSession, turnId: string): Promise<HarnessArchive | null>;
+    archive(state: NativeSession, turnId: string, diagnosticContext?: RuntimeDiagnosticContext): Promise<HarnessArchive | null>;
     acknowledge(state: NativeSession, turnId: string, revision: string): Promise<void>;
 }

package/dist/runtime/session-store.js

@@ -1,31 +1,224 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, open, readFile, readdir, rm } from "node:fs/promises";
+import { mkdir, open, readFile, readdir, rename, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { contextToPiMessages, RUNTIME_RECOVERY_BATCH_SIZE, selectRuntimeContextMessages, runtimeEventSchema } from "@neta-art/cohub";
+import { RUNTIME_RECOVERY_BATCH_SIZE, runtimeEventSchema, serializeProjectionRecords } from "@neta-art/cohub";
 import { RuntimeArchiveStore, checksumNativeFile, atomicRuntimeJson as atomicJson } from "./archive-store.js";
 import { importNativeArchive, readCodexArchiveTotals } from "./native-archive.js";
+import { serializeDiagnosticError } from "./diagnostics.js";
+import { ProjectionStore, rebindProjectionNativeSession } from "./projection-store.js";
 export class ContextRequiredError extends Error {
-    historyOnly;
-    constructor(message, historyOnly = false) {
-        super(message);
-        this.historyOnly = historyOnly;
-    }
 }
 const checksum = (data) => createHash("sha256").update(data).digest("hex");
 const missing = (error) => error?.code === "ENOENT";
 class CaptureUnavailableError extends Error {
 }
+function piSessionDirectory(cwd) {
+    const custom = process.env.PI_CODING_AGENT_SESSION_DIR?.trim();
+    if (custom)
+        return custom;
+    const agentDir = process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), ".pi", "agent");
+    const safePath = `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+    return join(agentDir, "sessions", safePath);
+}
+function codexSessionPath(id) {
+    const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, "").replaceAll(":", "-");
+    const root = process.env.CODEX_HOME?.trim() || join(homedir(), ".codex");
+    return join(root, "sessions", timestamp.slice(0, 4), timestamp.slice(5, 7), timestamp.slice(8, 10), `rollout-${timestamp}-${id}.jsonl`);
+}
 /** Local references are hints validated against actual native files, never cloud existence claims. */
 export class RuntimeSessionStore {
     root;
     archives;
     archiveFlush = null;
-    constructor(spaceId, stateRoot = join(homedir(), ".local", "state", "cohub", "runtime"), transport) {
-        this.root = join(stateRoot, spaceId);
-        this.archives = new RuntimeArchiveStore(join(this.root, "archives"), transport);
+    diagnostics = null;
+    nativeWrites = new Map();
+    projectionStore;
+    constructor(spaceId, options) {
+        this.root = join(options.stateRoot ?? join(homedir(), ".local", "state", "cohub", "runtime"), spaceId);
+        this.archives = new RuntimeArchiveStore(join(this.root, "archives"), options.archiveTransport);
+        this.projectionStore = new ProjectionStore(options.projectionSource);
+    }
+    setDiagnostics(diagnostics) {
+        this.diagnostics = diagnostics;
+        this.archives.setErrorReporter((error, index) => diagnostics.log("warn", "archive.upload_pending", { error: serializeDiagnosticError(error) }, {
+            component: "archive",
+            sessionId: index?.sessionId,
+            turnId: index?.turnId,
+            harness: index?.harness,
+        }));
     }
     statePath(input) { return join(this.root, input.harness, `${input.sessionId}.json`); }
+    nativePath(input, nativeSessionId, cwd) {
+        if (input.harness === "pi")
+            return join(piSessionDirectory(cwd), `${nativeSessionId}.jsonl`);
+        return codexSessionPath(nativeSessionId);
+    }
+    async withNativeWrite(path, write) {
+        const previous = this.nativeWrites.get(path) ?? Promise.resolve();
+        const current = previous.catch(() => undefined).then(write);
+        this.nativeWrites.set(path, current);
+        try {
+            await current;
+        }
+        finally {
+            if (this.nativeWrites.get(path) === current)
+                this.nativeWrites.delete(path);
+        }
+    }
+    async syncParentDirectory(path) {
+        if (process.platform === "win32")
+            return;
+        const directory = await open(dirname(path), "r");
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    async writeNativeFile(path, data) {
+        await this.withNativeWrite(path, async () => {
+            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            const temporary = `${path}.${randomUUID()}.projection`;
+            try {
+                const file = await open(temporary, "wx", 0o600);
+                try {
+                    await file.writeFile(data, "utf8");
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                await rename(temporary, path);
+                await this.syncParentDirectory(path);
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        });
+    }
+    async appendNativeFile(path, data, expectedChecksum) {
+        if (!data)
+            return;
+        await this.withNativeWrite(path, async () => {
+            const file = await open(path, "r+", 0o600);
+            try {
+                const bytes = await file.readFile();
+                if (expectedChecksum && checksum(bytes) !== expectedChecksum)
+                    throw new Error("Native session changed outside Cohub; original data was preserved");
+                const prefix = bytes.length > 0 && bytes.at(-1) !== 10 ? "\n" : "";
+                await file.write(`${prefix}${data}`, bytes.length, "utf8");
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await this.syncParentDirectory(path);
+        });
+    }
+    async lastNativeRecordId(path) {
+        const file = await open(path, "r");
+        try {
+            let position = (await file.stat()).size;
+            let tail = "";
+            while (position > 0) {
+                const size = Math.min(position, 64 * 1024);
+                position -= size;
+                const chunk = Buffer.alloc(size);
+                await file.read(chunk, 0, size, position);
+                tail = chunk.toString("utf8") + tail;
+                const candidate = tail.trimEnd();
+                const newline = candidate.lastIndexOf("\n");
+                if (newline >= 0) {
+                    const record = JSON.parse(candidate.slice(newline + 1));
+                    return typeof record.id === "string" ? record.id : null;
+                }
+            }
+            const record = JSON.parse(tail.trim());
+            return typeof record.id === "string" ? record.id : null;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    reportProjectionWarnings(input, warnings) {
+        if (warnings.length === 0)
+            return;
+        this.diagnostics?.log("warn", "runtime.projection_loss", { warningCount: warnings.length, warnings: warnings.slice(0, 100), truncated: warnings.length > 100 }, { component: "projection", sessionId: input.sessionId, turnId: input.turnId, harness: input.harness });
+    }
+    async syncNativeProjection(input, cwd, previous, signal) {
+        const existing = previous && (previous.checksum.length > 0 || previous.sourceSequence != null || previous.pendingTurnId != null) ? previous : null;
+        const projection = await this.projectionStore.project({
+            spaceId: input.spaceId,
+            sessionId: input.sessionId,
+            turnId: input.turnId,
+            nativeSessionId: existing?.nativeSessionId ?? randomUUID(),
+            cwd,
+            provider: input.provider,
+            target: input.harness,
+            throughTurnId: input.context.throughTurnId,
+            cursor: existing ? {
+                throughSequence: existing.sourceSequence ?? null,
+                throughTurnId: existing.sourceTurnId ?? null,
+                sourceFingerprint: existing.sourceFingerprint ?? null,
+            } : null,
+        }, signal);
+        if (existing && projection.append && projection.turns.length === 0)
+            return { state: existing, resume: "native" };
+        const replacing = existing !== null && !projection.append;
+        const id = replacing || !existing ? randomUUID() : existing.nativeSessionId;
+        const path = replacing || !existing ? this.nativePath(input, id, cwd) : existing.path;
+        const materialized = replacing ? rebindProjectionNativeSession(projection, id) : projection;
+        this.reportProjectionWarnings(input, materialized.projection.warnings);
+        const turns = materialized.turns;
+        const next = {
+            ...(replacing || !existing ? { version: 1, sessionId: input.sessionId, harness: input.harness, nativeSessionId: id, path, cwd, throughTurnId: null, revision: input.context.revision, checksum: "", pendingTurnId: null } : existing),
+            projectionVersion: 1,
+            nativeSessionId: id,
+            path,
+            cwd,
+            sourceSequence: materialized.cursor.throughSequence,
+            sourceTurnId: materialized.cursor.throughTurnId,
+            sourceFingerprint: materialized.cursor.sourceFingerprint,
+            throughTurnId: input.context.throughTurnId,
+            revision: input.context.revision,
+        };
+        const serialized = serializeProjectionRecords(materialized.projection.records);
+        if (input.harness === "codex" && turns.length === 0 && !existing)
+            return { state: next, resume: "new" };
+        if (materialized.append && existing) {
+            let suffix = serialized;
+            let leafId = existing.nativeLeafId ?? null;
+            if (input.harness === "pi") {
+                leafId = await this.lastNativeRecordId(existing.path);
+                if (leafId) {
+                    let rebound = false;
+                    const records = materialized.projection.records.map((entry) => {
+                        if (rebound || !("parentId" in entry.record))
+                            return entry;
+                        rebound = true;
+                        return { ...entry, record: { ...entry.record, parentId: leafId } };
+                    });
+                    suffix = serializeProjectionRecords(records);
+                }
+            }
+            await this.appendNativeFile(existing.path, suffix, existing.checksum);
+            const projectedLeaf = materialized.projection.records.at(-1)?.record.id;
+            if (typeof projectedLeaf === "string")
+                leafId = projectedLeaf;
+            next.nativeLeafId = leafId;
+        }
+        else {
+            await this.writeNativeFile(path, serialized);
+            const projectedLeaf = materialized.projection.records.at(-1)?.record.id;
+            next.nativeLeafId = typeof projectedLeaf === "string" ? projectedLeaf : null;
+        }
+        next.checksum = await checksumNativeFile(path);
+        if (existing)
+            await atomicJson(this.statePath(next), next);
+        return { state: next, resume: existing ? "handoff" : (turns.length ? "handoff" : "new") };
+    }
     async *pendingExecutionBatches() {
         let batch = [];
         for (const harness of ["pi", "codex"]) {
@@ -46,6 +239,7 @@ export class RuntimeSessionStore {
                     }
                 }
                 catch (error) {
+                    this.diagnostics?.log("error", "runtime.session_state_unreadable", { path: join(directory, name), error: serializeDiagnosticError(error) });
                     console.error(`Runtime session state unreadable: ${join(directory, name)}`, error);
                 }
             }
@@ -100,10 +294,13 @@ export class RuntimeSessionStore {
                         receipt, reason: error.message, failedAt: new Date().toISOString(),
                     });
                     await rm(join(captures, name), { force: true });
+                    this.diagnostics?.log("error", "archive.capture_unavailable", { reason: error.message, receipt: true }, { component: "archive" });
                     console.error("Archive capture unavailable; receipt retained:", error.message);
                 }
-                else
+                else {
+                    this.diagnostics?.log("warn", "archive.capture_pending", { error: serializeDiagnosticError(error) }, { component: "archive" });
                     console.error("Archive capture pending:", error);
+                }
             }
         }
         await this.archives.flush(signal);
@@ -173,8 +370,11 @@ export class RuntimeSessionStore {
         }
         if (previous) {
             try {
-                if (await checksumNativeFile(previous.path) !== previous.checksum)
-                    throw new Error("Native session changed outside Cohub; original data was preserved");
+                const nativeChecksum = await checksumNativeFile(previous.path);
+                if (nativeChecksum !== previous.checksum) {
+                    this.diagnostics?.log("warn", "runtime.projection_rebuilt", { reason: "native file changed outside Cohub" }, { component: "projection", sessionId: input.sessionId, turnId: input.turnId, harness: input.harness });
+                    return await this.syncNativeProjection(input, cwd, null, signal);
+                }
                 if (previous.archivePendingTurnId) {
                     await this.archives.stage(previous, previous.archivePendingTurnId);
                     previous.archivePendingTurnId = undefined;
@@ -182,24 +382,22 @@ export class RuntimeSessionStore {
                 }
                 if (input.harness === "codex" && !previous.codexTokenTotals)
                     previous.codexTokenTotals = await readCodexArchiveTotals(previous.path);
-                if (previous.cwd === cwd && previous.throughTurnId === input.context.throughTurnId && previous.revision === input.context.revision)
-                    return { state: previous, resume: "native" };
+                return await this.syncNativeProjection(input, cwd, previous?.cwd === cwd ? previous : null, signal);
             }
             catch (error) {
                 if (!missing(error))
                     throw error;
             }
         }
-        if (input.context.complete === false && !input.context.archive)
-            throw new ContextRequiredError("Full context is required to materialize this session");
         const id = randomUUID();
-        const path = join(this.root, input.harness, `${id}.jsonl`);
+        const path = this.nativePath(input, id, cwd);
         const archive = input.context.archive;
         const restore = archive?.harness === input.harness && archive.sessionId === input.sessionId && archive.turnId === input.context.throughTurnId;
         const rawPath = join(this.root, "archives", "restored", `${id}.jsonl`);
         const state = {
             version: 1, harness: input.harness, sessionId: input.sessionId, nativeSessionId: id,
             path, cwd, throughTurnId: input.context.throughTurnId, revision: input.context.revision, checksum: "", pendingTurnId: null,
+            projectionVersion: 1, sourceSequence: null, sourceTurnId: null, sourceFingerprint: null,
         };
         if (restore) {
             try {
@@ -209,52 +407,19 @@ export class RuntimeSessionStore {
             }
             catch (error) {
                 signal?.throwIfAborted();
+                this.diagnostics?.log("warn", "archive.restore_failed", { error: serializeDiagnosticError(error) }, { component: "archive" });
                 console.error("Native archive unavailable; rebuilding from durable history:", error);
             }
         }
-        if (input.context.complete === false)
-            throw new ContextRequiredError("Database history is required after archive recovery failed", true);
-        let data = null;
-        if (input.harness === "pi") {
-            const entries = [{ type: "session", version: 3, id, cwd, timestamp: new Date().toISOString() }];
-            let parentId = null;
-            const history = selectRuntimeContextMessages(input.context.messages);
-            const summary = history[0]?.role === "system" ? history[0].content.find((block) => block.type === "system_note" && block.note_type === "compacted") : undefined;
-            let compaction;
-            if (summary?.type === "system_note") {
-                parentId = randomUUID().slice(0, 8);
-                compaction = { type: "compaction", id: parentId, parentId: null, timestamp: new Date().toISOString(), summary: summary.text,
-                    firstKeptEntryId: "", tokensBefore: history[0]?.meta?.compaction?.tokensBefore ?? 0 };
-                entries.push(compaction);
-            }
-            for (const message of contextToPiMessages(history)) {
-                const entryId = randomUUID().slice(0, 8);
-                if (compaction && !compaction.firstKeptEntryId)
-                    compaction.firstKeptEntryId = entryId;
-                entries.push({ type: "message", id: entryId, parentId, timestamp: new Date().toISOString(), message });
-                parentId = entryId;
-            }
-            data = `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
-        }
-        if (data != null) {
-            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-            const file = await open(path, "wx", 0o600);
-            try {
-                await file.writeFile(data);
-                await file.sync();
-            }
-            finally {
-                await file.close();
-            }
-            state.checksum = checksum(data);
-        }
-        return { state, resume: input.context.messages.length ? "handoff" : "new" };
+        return await this.syncNativeProjection(input, cwd, state, signal);
     }
     async started(state, turnId) { state.pendingTurnId = turnId; state.resultChecksum = undefined; await atomicJson(this.statePath(state), state); }
     resultPath(state) { return join(this.root, "results", `${state.sessionId}.${state.harness}.json`); }
     async recordResult(state, requestId, events) {
         if (!state.pendingTurnId)
             throw new Error("Cannot record a result for an idle native session");
+        if (state.harness === "pi")
+            state.nativeLeafId = await this.lastNativeRecordId(state.path);
         state.resultChecksum = await checksumNativeFile(state.path);
         if (state.archivePendingTurnId)
             await atomicJson(join(this.archives.root, "captures", `${state.archivePendingTurnId}.json`), state);
@@ -278,13 +443,19 @@ export class RuntimeSessionStore {
             throw error;
         }
     }
-    async archive(state, turnId) {
+    async archive(state, turnId, diagnosticContext = {}) {
         if (!state.path)
             return null;
         state.archivePendingTurnId = turnId;
-        const reference = await this.archives.stage(state, turnId);
-        state.archivePendingTurnId = undefined;
-        return reference;
+        try {
+            const reference = await this.archives.stage(state, turnId);
+            state.archivePendingTurnId = undefined;
+            return reference;
+        }
+        catch (error) {
+            this.diagnostics?.log("warn", "archive.capture_failed", { error: serializeDiagnosticError(error) }, { ...diagnosticContext, component: "archive", turnId, harness: state.harness });
+            throw error;
+        }
     }
     async acknowledge(state, turnId, revision) {
         if (state.pendingTurnId !== turnId)
@@ -293,7 +464,14 @@ export class RuntimeSessionStore {
             return state.resultChecksum ?? state.checksum; throw error; });
         if (state.resultChecksum && currentChecksum !== state.resultChecksum)
             throw new Error("Native data changed before acknowledgement; files preserved");
-        const acknowledged = { ...state, checksum: currentChecksum, pendingTurnId: null, resultChecksum: undefined, throughTurnId: turnId, revision };
+        let sourceSequence = state.sourceSequence ?? null;
+        let sourceTurnId = state.sourceTurnId ?? null;
+        let sourceFingerprint = state.sourceFingerprint ?? null;
+        const projectionCursor = await this.projectionStore.cursorForTurn(state.sessionId, turnId);
+        sourceSequence = projectionCursor.throughSequence;
+        sourceTurnId = projectionCursor.throughTurnId;
+        sourceFingerprint = projectionCursor.sourceFingerprint;
+        const acknowledged = { ...state, checksum: currentChecksum, pendingTurnId: null, resultChecksum: undefined, throughTurnId: turnId, revision, sourceSequence, sourceTurnId, sourceFingerprint };
         await atomicJson(this.statePath(state), acknowledged);
         Object.assign(state, acknowledged);
     }

package/dist/runtime/space-binding.d.ts

@@ -0,0 +1,45 @@
+export type RuntimeSpaceBinding = {
+    /** Canonical local workspace root. */
+    root: string;
+    /** Environment + authenticated actor identity. */
+    key: string;
+    spaceId: string;
+};
+export type RuntimeSpaceBindingsFile = {
+    version: 1;
+    bindings: RuntimeSpaceBinding[];
+};
+export type RuntimeSpaceBindingResolution = {
+    spaceId: string;
+    source: "binding" | "created" | "explicit";
+};
+export declare class RuntimeSpaceBindingsError extends Error {
+    name: string;
+}
+export declare function runtimeSpaceBindingsPath(): string;
+export declare function normalizeRuntimeRoot(root: string): string;
+export declare function canonicalRuntimeRoot(root: string): Promise<string>;
+export declare function parseRuntimeSpaceBindings(raw: string, path?: string): RuntimeSpaceBindingsFile;
+export declare function readRuntimeSpaceBindings(path?: string): Promise<RuntimeSpaceBindingsFile>;
+export declare function findRuntimeSpaceBinding(bindings: RuntimeSpaceBinding[] | RuntimeSpaceBindingsFile, input: {
+    root: string;
+    key: string;
+}): RuntimeSpaceBinding | null;
+export declare function withRuntimeSpaceBindingsLock<T>(fn: () => Promise<T>, options?: {
+    path?: string;
+    lockPath?: string;
+}): Promise<T>;
+export declare function getRuntimeSpaceBinding(root: string, key: string | null | undefined, path?: string): Promise<RuntimeSpaceBinding | null>;
+/**
+ * Resolve a local Runtime Space without silently creating duplicates.
+ * The per-binding lock covers creation; the shared file is locked only for
+ * short read-modify-write commits.
+ */
+export declare function resolveRuntimeSpace(input: {
+    root: string;
+    identityKey: string | null | undefined;
+    explicitSpaceId?: string | null;
+    createSpace: () => Promise<string>;
+    validateSpace?: (spaceId: string) => Promise<void>;
+    path?: string;
+}): Promise<RuntimeSpaceBindingResolution>;