@mcoda/mswarm 0.1.134 → 0.1.135-codali.2

package/dist/vendor/codali/session/SessionStore.js

@@ -1,21 +1,59 @@
 import { randomUUID } from "node:crypto";
-import { promises as fs } from "node:fs";
+import { constants, promises as fs } from "node:fs";
 import path from "node:path";
+import { atomicWriteJson, withStateLock } from "./AtomicState.js";
+import { createWorkState, validateWorkState } from "./WorkState.js";
+import { readStateFile, sessionStoragePath } from "./SessionStoragePath.js";
 const DEFAULT_SESSION_STORAGE_DIR = ".mcoda/codali/sessions";
 const safeId = (value) => {
-    const safe = value.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 120);
-    if (!safe)
-        throw new Error("Session id must contain at least one safe character");
-    return safe;
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,119}$/.test(value))
+        throw new Error("Invalid session id");
+    return value;
+};
+const safeSummaryRef = (value) => {
+    const normalized = typeof value === "string" ? value.replace(/\\/g, "/") : "";
+    if (!/^summaries\/[A-Za-z0-9._-]+\.json$/.test(normalized))
+        throw new Error("Unsafe session summary reference");
+    return normalized;
+};
+const validateMetadata = (value, sessionId) => {
+    if (!value || value.schemaVersion !== 1)
+        throw new Error("Unsupported session metadata schema; use a compatible client");
+    if (value.sessionId !== sessionId || typeof value.repoRoot !== "string" || typeof value.task !== "string" || !["active", "paused", "completed", "failed"].includes(value.status))
+        throw new Error("Invalid session metadata identity/status");
+    for (const key of ["runIds", "transcriptRefs", "summaryRefs", "contextLaneRefs", "instructionSources"]) {
+        if (!Array.isArray(value[key]) || value[key].some(item => typeof item !== "string"))
+            throw new Error(`Invalid session ${key}`);
+    }
+    value.summaryRefs.forEach(safeSummaryRef);
+    return value;
 };
 const parseJsonLines = (content) => {
     if (!content.trim())
         return [];
-    return content
-        .split("\n")
-        .map((line) => line.trim())
-        .filter(Boolean)
-        .map((line) => JSON.parse(line));
+    const lines = content.split("\n");
+    const result = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index].trim();
+        if (!line)
+            continue;
+        try {
+            result.push(JSON.parse(line));
+        }
+        catch (error) {
+            // Only an unterminated final record may be a crash tail. Never hide middle corruption.
+            if (index === lines.length - 1 && !content.endsWith("\n"))
+                break;
+            throw error;
+        }
+    }
+    return result;
+};
+const parseTranscript = (content, sessionId) => {
+    const events = parseJsonLines(content);
+    if (events.some(event => !event || event.schemaVersion !== 1 || event.sessionId !== sessionId))
+        throw new Error("Unsupported/invalid session transcript schema");
+    return events;
 };
 const nowIso = () => new Date().toISOString();
 const shortJson = (value, maxLength = 400) => {
@@ -63,15 +101,20 @@ export class SessionStore {
         this.lastTimestampMs = 0;
         this.workspaceRoot = path.resolve(options.workspaceRoot);
         this.storageDir = options.storageDir ?? DEFAULT_SESSION_STORAGE_DIR;
+        this.allowExternalStorage = options.allowExternalStorage === true;
     }
     rootDir() {
         const resolved = path.resolve(this.workspaceRoot, this.storageDir);
         const relative = path.relative(this.workspaceRoot, resolved);
-        if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        if (!this.allowExternalStorage && (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))) {
             throw new Error("Session storage path is outside workspace root");
         }
         return resolved;
     }
+    checkedPath(file, createParents = false, directory = false) {
+        return sessionStoragePath({ workspaceRoot: this.workspaceRoot, storageRoot: this.rootDir(), file,
+            allowExternal: this.allowExternalStorage, createParents, directory });
+    }
     sessionDir(sessionId) {
         return path.join(this.rootDir(), safeId(sessionId));
     }
@@ -109,13 +152,23 @@ export class SessionStore {
             createdAt,
             updatedAt: createdAt,
         };
-        await fs.mkdir(this.sessionDir(sessionId), { recursive: true });
-        await fs.writeFile(this.metadataPath(sessionId), `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+        const metadataPath = await this.checkedPath(this.metadataPath(sessionId), true);
+        await withStateLock(metadataPath, async () => {
+            try {
+                await fs.stat(metadataPath);
+                throw new Error("Session already exists");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            await atomicWriteJson(metadataPath, metadata);
+        });
         return metadata;
     }
     async readSession(sessionId) {
-        const content = await fs.readFile(this.metadataPath(sessionId), "utf8");
-        return JSON.parse(content);
+        const content = await readStateFile(await this.checkedPath(this.metadataPath(sessionId)));
+        return validateMetadata(JSON.parse(content), sessionId);
     }
     async getOrCreateSession(input) {
         if (input.sessionId) {
@@ -131,25 +184,30 @@ export class SessionStore {
         return this.createSession(input);
     }
     async updateSession(sessionId, patch) {
-        const current = await this.readSession(sessionId);
-        const next = {
-            ...current,
-            ...patch,
-            runIds: patch.runIds ?? current.runIds,
-            transcriptRefs: patch.transcriptRefs ?? current.transcriptRefs,
-            summaryRefs: patch.summaryRefs ?? current.summaryRefs,
-            contextLaneRefs: patch.contextLaneRefs ?? current.contextLaneRefs,
-            instructionSources: patch.instructionSources ?? current.instructionSources,
-            updatedAt: this.nextTimestampIso(current.updatedAt),
-        };
-        await fs.writeFile(this.metadataPath(sessionId), `${JSON.stringify(next, null, 2)}\n`, "utf8");
-        return next;
+        return this.mutateSession(sessionId, current => ({ ...current, ...patch }));
+    }
+    async mutateSession(sessionId, mutate) {
+        const metadataPath = await this.checkedPath(this.metadataPath(sessionId));
+        return withStateLock(metadataPath, async () => {
+            const current = await this.readSession(sessionId);
+            const patch = mutate(structuredClone(current));
+            const next = {
+                ...current,
+                ...patch,
+                runIds: patch.runIds ?? current.runIds,
+                transcriptRefs: patch.transcriptRefs ?? current.transcriptRefs,
+                summaryRefs: patch.summaryRefs ?? current.summaryRefs,
+                contextLaneRefs: patch.contextLaneRefs ?? current.contextLaneRefs,
+                instructionSources: patch.instructionSources ?? current.instructionSources,
+                updatedAt: this.nextTimestampIso(current.updatedAt),
+            };
+            validateMetadata(next, sessionId);
+            await atomicWriteJson(metadataPath, next);
+            return next;
+        });
     }
     async addRun(sessionId, runId) {
-        const current = await this.readSession(sessionId);
-        if (current.runIds.includes(runId))
-            return current;
-        return this.updateSession(sessionId, { runIds: [...current.runIds, runId] });
+        return this.mutateSession(sessionId, current => ({ ...current, runIds: [...new Set([...current.runIds, runId])] }));
     }
     async appendTranscript(sessionId, event) {
         const record = {
@@ -160,16 +218,53 @@ export class SessionStore {
             runId: event.runId,
             data: event.data,
         };
-        const transcriptPath = this.transcriptPath(sessionId);
-        await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
-        await fs.appendFile(transcriptPath, `${JSON.stringify(record)}\n`, "utf8");
+        await this.readSession(sessionId); // Refuse future schemas before appending anything.
+        const transcriptPath = await this.checkedPath(this.transcriptPath(sessionId));
+        await withStateLock(transcriptPath, async () => {
+            try {
+                const contents = await readStateFile(transcriptPath);
+                parseTranscript(contents, sessionId);
+                if (contents && !contents.endsWith("\n")) {
+                    const lastNewline = contents.lastIndexOf("\n");
+                    let complete = false;
+                    try {
+                        JSON.parse(contents.slice(lastNewline + 1));
+                        complete = true;
+                    }
+                    catch { /* Incomplete crash tail. */ }
+                    // Windows append-only handles cannot truncate an incomplete record.
+                    const repair = await fs.open(transcriptPath, constants.O_WRONLY | constants.O_NOFOLLOW | (complete ? constants.O_APPEND : 0));
+                    try {
+                        if (complete)
+                            await repair.writeFile("\n");
+                        else
+                            await repair.truncate(Buffer.byteLength(contents.slice(0, lastNewline + 1)));
+                    }
+                    finally {
+                        await repair.close();
+                    }
+                }
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            const handle = await fs.open(transcriptPath, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        });
         await this.updateSession(sessionId, {});
         return record;
     }
     async readTranscript(sessionId) {
         try {
-            const content = await fs.readFile(this.transcriptPath(sessionId), "utf8");
-            return parseJsonLines(content);
+            const content = await readStateFile(await this.checkedPath(this.transcriptPath(sessionId)));
+            return parseTranscript(content, sessionId);
         }
         catch (error) {
             if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
@@ -181,7 +276,7 @@ export class SessionStore {
     async listSessions() {
         let entries;
         try {
-            entries = await fs.readdir(this.rootDir());
+            entries = await fs.readdir(await this.checkedPath(this.rootDir(), false, true));
         }
         catch (error) {
             if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
@@ -212,15 +307,12 @@ export class SessionStore {
             eventCount: events.length,
             ...compacted,
         };
-        const summariesDir = this.summariesDir(sessionId);
-        await fs.mkdir(summariesDir, { recursive: true });
+        const summariesDir = await this.checkedPath(this.summariesDir(sessionId), true, true);
         const fileName = `${createdAt.replace(/[^0-9T]/g, "").slice(0, 15)}-${events.length}.json`;
         const filePath = path.join(summariesDir, fileName);
-        await fs.writeFile(filePath, `${JSON.stringify(summary, null, 2)}\n`, "utf8");
-        const relativeRef = path.relative(this.sessionDir(sessionId), filePath);
-        await this.updateSession(sessionId, {
-            summaryRefs: [...metadata.summaryRefs, relativeRef],
-        });
+        await atomicWriteJson(filePath, summary);
+        const relativeRef = path.posix.join("summaries", fileName);
+        await this.mutateSession(sessionId, current => ({ ...current, summaryRefs: [...new Set([...current.summaryRefs, relativeRef])] }));
         return summary;
     }
     async readLatestSummary(sessionId) {
@@ -228,8 +320,11 @@ export class SessionStore {
         const latest = metadata.summaryRefs.at(-1);
         if (!latest)
             return undefined;
-        const content = await fs.readFile(path.join(this.sessionDir(sessionId), latest), "utf8");
-        return JSON.parse(content);
+        const content = await readStateFile(await this.checkedPath(path.join(this.sessionDir(sessionId), safeSummaryRef(latest))));
+        const summary = JSON.parse(content);
+        if (!summary || summary.schemaVersion !== 1 || summary.sessionId !== sessionId)
+            throw new Error("Unsupported/invalid session summary schema");
+        return summary;
     }
     async buildResumeBundle(sessionId, options = {}) {
         const metadata = await this.readSession(sessionId);
@@ -241,4 +336,43 @@ export class SessionStore {
             recentEvents: recentCount ? transcript.slice(-recentCount) : [],
         };
     }
+    async initializeWork(sessionId, objective) {
+        await this.readSession(sessionId);
+        const file = await this.checkedPath(path.join(this.sessionDir(sessionId), "work.json"));
+        return withStateLock(file, async () => {
+            try {
+                return await this.readWork(sessionId);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            const state = createWorkState(objective);
+            await atomicWriteJson(file, state);
+            return state;
+        });
+    }
+    async readWork(sessionId) {
+        const state = JSON.parse(await readStateFile(await this.checkedPath(path.join(this.sessionDir(sessionId), "work.json"))));
+        validateWorkState(state);
+        return state;
+    }
+    async updateWork(sessionId, expectedRevision, mutate) {
+        await this.readSession(sessionId);
+        const file = await this.checkedPath(path.join(this.sessionDir(sessionId), "work.json"));
+        return withStateLock(file, async () => {
+            const state = await this.readWork(sessionId);
+            if (state.revision !== expectedRevision)
+                throw new Error("Work revision conflict; reload before retrying");
+            const identity = [state.goalId, state.originalObjective, state.createdAt];
+            mutate(state);
+            if (JSON.stringify(identity) !== JSON.stringify([state.goalId, state.originalObjective, state.createdAt]))
+                throw new Error("Original goal identity is immutable");
+            state.revision += 1;
+            state.updatedAt = nowIso();
+            validateWorkState(state);
+            await atomicWriteJson(file, state);
+            return state;
+        });
+    }
 }

package/dist/vendor/codali/session/WorkState.d.ts

@@ -0,0 +1,23 @@
+import type { DecisionRecord, EvidenceReceipt, Requirement, WorkState, WorkTask, WorkPhase } from "./WorkTypes.js";
+export declare const createWorkState: (objective: string, requirements?: Requirement[]) => WorkState;
+export declare const validateWorkState: (state: WorkState) => void;
+export declare const refreshReadyTasks: (state: WorkState) => void;
+export declare const replaceWorkPlan: (state: WorkState, tasks: Array<Pick<WorkTask, "id" | "title" | "requirementIds" | "dependsOn" | "allowedPaths" | "phaseId">>, phases?: WorkPhase[], reason?: string) => void;
+/** Update named contracts while retaining every unmentioned task and phase. */
+export declare const updateWorkPlan: (state: WorkState, updates: Parameters<typeof replaceWorkPlan>[1], phaseUpdates?: WorkPhase[], reason?: string) => void;
+export declare const claimWorkTask: (state: WorkState, taskId: string, leaseMs?: number) => WorkTask;
+export declare const releaseWorkTask: (state: WorkState, taskId: string, attemptId: string, note: string) => void;
+/** Withdraw a disproven verification and fence all dependent attempts without rewriting the plan. */
+export declare const reopenVerifiedTask: (state: WorkState, taskId: string, reason: string) => string[];
+export declare const assertWorkAttempt: (state: WorkState, taskId: string, attemptId: string) => WorkTask;
+export declare const recordWorkEvidence: (state: WorkState, taskId: string, attemptId: string, evidence: EvidenceReceipt) => void;
+export declare const verifyWorkTask: (state: WorkState, taskId: string, attemptId: string, currentHashes: Record<string, string>) => void;
+/** Reopen stale proofs and their dependent tasks without discarding audit history. */
+export declare const refreshStaleEvidence: (state: WorkState, currentHashes: Record<string, string>) => string[];
+export declare const amendWorkGoal: (state: WorkState, objective: string, reason: string) => void;
+export declare const recordDecision: (state: WorkState, decision: DecisionRecord) => void;
+export declare const completeWorkGoal: (state: WorkState, currentHashes: Record<string, string>, uncertainInvocationIds?: string[]) => void;
+export declare const workContext: (state: WorkState) => string;
+/** Keep the active contract intact while paging unrelated backlog out of context. */
+export declare const activeWorkContext: (state: WorkState, maxChars: number) => string;
+//# sourceMappingURL=WorkState.d.ts.map

package/dist/vendor/codali/session/WorkState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkState.d.ts","sourceRoot":"","sources":["../../src/session/WorkState.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAiBnH,eAAO,MAAM,eAAe,GAAI,WAAW,MAAM,EAAE,eAAe,WAAW,EAAE,KAAG,SAYjF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,KAAG,IAiDpD,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,KAAG,IAIpD,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,OAAO,SAAS,EAAE,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,OAAO,GAAG,gBAAgB,GAAG,WAAW,GAAG,cAAc,GAAG,SAAS,CAAC,CAAC,EAAE,oBAA2B,EAAE,eAA4B,KAAG,IAgCzN,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,cAAc,GAAI,OAAO,SAAS,EAAE,SAAS,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,eAAc,SAAS,EAAO,EAAE,eAA4B,KAAG,IAiB/J,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,OAAO,SAAS,EAAE,QAAQ,MAAM,EAAE,gBAAiB,KAAG,QAWnF,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,OAAO,SAAS,EAAE,QAAQ,MAAM,EAAE,WAAW,MAAM,EAAE,MAAM,MAAM,KAAG,IAOnG,CAAC;AAEF,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,GAAI,OAAO,SAAS,EAAE,QAAQ,MAAM,EAAE,QAAQ,MAAM,KAAG,MAAM,EAkB3F,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,EAAE,QAAQ,MAAM,EAAE,WAAW,MAAM,KAAG,QAOvF,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,OAAO,SAAS,EAAE,QAAQ,MAAM,EAAE,WAAW,MAAM,EAAE,UAAU,eAAe,KAAG,IAOnH,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,OAAO,SAAS,EAAE,QAAQ,MAAM,EAAE,WAAW,MAAM,EAAE,eAAe,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,IAK3H,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,GAAI,OAAO,SAAS,EAAE,eAAe,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAAM,EAepG,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,OAAO,SAAS,EAAE,WAAW,MAAM,EAAE,QAAQ,MAAM,KAAG,IAWnF,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,OAAO,SAAS,EAAE,UAAU,cAAc,KAAG,IAuB3E,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,OAAO,SAAS,EAAE,eAAe,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,yBAAwB,MAAM,EAAO,KAAG,IASjI,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,OAAO,SAAS,KAAG,MAK7C,CAAC;AAEH,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,EAAE,UAAU,MAAM,KAAG,MAoCtE,CAAC"}