@bolt-foundry/gambit 0.8.3 → 0.8.5-rc.11

package/esm/src/server_session_store.js

@@ -0,0 +1,876 @@
+import * as dntShim from "../_dnt.shims.js";
+import * as path from "../deps/jsr.io/@std/path/1.1.4/mod.js";
+import { existsSync } from "../deps/jsr.io/@std/fs/1.0.23/mod.js";
+const TRACE_EVENT_TYPES = new Set([
+    "run.start",
+    "message.user",
+    "run.end",
+    "deck.start",
+    "deck.end",
+    "action.start",
+    "action.end",
+    "tool.call",
+    "tool.result",
+    "model.call",
+    "model.result",
+    "model.stream.event",
+    "log",
+    "monolog",
+]);
+const isTraceEventType = (type) => TRACE_EVENT_TYPES.has(type) || type.startsWith("response.") ||
+    (type.startsWith("gambit.") &&
+        TRACE_EVENT_TYPES.has(type.slice("gambit.".length)));
+const normalizePersistedTraceRecord = (record) => {
+    const type = typeof record.type === "string" ? record.type : "";
+    if (!type)
+        return null;
+    if (TRACE_EVENT_TYPES.has(type) || type.startsWith("response.")) {
+        return record;
+    }
+    if (!type.startsWith("gambit."))
+        return null;
+    const rawMeta = record._gambit;
+    const meta = rawMeta && typeof rawMeta === "object" && !Array.isArray(rawMeta)
+        ? rawMeta
+        : undefined;
+    const sourceType = typeof meta?.source_type === "string" &&
+        meta.source_type.trim().length > 0
+        ? meta.source_type.trim()
+        : type.slice("gambit.".length);
+    if (!TRACE_EVENT_TYPES.has(sourceType))
+        return null;
+    return {
+        ...record,
+        type: sourceType,
+    };
+};
+const inferWorkspaceDomain = (payloadType) => {
+    if (payloadType === "buildBotStatus" || payloadType === "buildBotTrace" ||
+        payloadType === "buildBotStream" || payloadType === "buildBotStreamEnd" ||
+        payloadType.startsWith("gambit.build.")) {
+        return "build";
+    }
+    if (payloadType === "testBotStatus" || payloadType === "testBotTrace" ||
+        payloadType === "testBotStream" || payloadType === "testBotStreamEnd" ||
+        payloadType.startsWith("gambit.test.")) {
+        return "test";
+    }
+    if (payloadType === "calibrateSession" || payloadType === "grading.run" ||
+        payloadType === "grading.flag" || payloadType === "grading.flag.reason" ||
+        payloadType === "grading.reference" ||
+        payloadType.startsWith("gambit.grade.") ||
+        payloadType.startsWith("gambit.grading.")) {
+        return "grade";
+    }
+    return "session";
+};
+const isWorkspaceEventDomain = (value) => value === "build" || value === "test" || value === "grade" ||
+    value === "session";
+const CANONICAL_EVENT_TYPE_BY_LEGACY = new Map([
+    ["buildBotStatus", "gambit.build.status"],
+    ["buildBotTrace", "gambit.build.trace"],
+    ["buildBotStream", "gambit.build.stream.delta"],
+    ["buildBotStreamEnd", "gambit.build.stream.done"],
+    ["testBotStatus", "gambit.test.status"],
+    ["testBotStream", "gambit.test.stream.delta"],
+    ["testBotStreamEnd", "gambit.test.stream.done"],
+    ["calibrateSession", "gambit.grade.session"],
+    ["feedback.update", "gambit.feedback.update"],
+    ["grading.run", "gambit.grading.run"],
+    ["grading.flag", "gambit.grading.flag"],
+    ["grading.flag.reason", "gambit.grading.flag.reason"],
+    ["grading.reference", "gambit.grading.reference"],
+    ["notes.update", "gambit.notes.update"],
+    ["conversation.score.update", "gambit.conversation.score.update"],
+    ["session.start", "gambit.session.start"],
+    ["server.error", "gambit.server.error"],
+]);
+const normalizeEventType = (type, kind) => {
+    if (type.startsWith("response.") || type.startsWith("gambit.")) {
+        return { canonicalType: type };
+    }
+    if (kind === "trace" || isTraceEventType(type)) {
+        return { canonicalType: type };
+    }
+    const mapped = CANONICAL_EVENT_TYPE_BY_LEGACY.get(type);
+    if (mapped) {
+        return { canonicalType: mapped, legacyType: type };
+    }
+    return { canonicalType: `gambit.${type}`, legacyType: type };
+};
+const safeStringify = (value, space) => {
+    const stack = [];
+    return JSON.stringify(value, function (_key, candidate) {
+        if (!candidate || typeof candidate !== "object") {
+            return candidate;
+        }
+        while (stack.length > 0 && stack[stack.length - 1] !== this) {
+            stack.pop();
+        }
+        if (stack.includes(candidate)) {
+            return "[Circular]";
+        }
+        stack.push(candidate);
+        return candidate;
+    }, space);
+};
+export const createSessionStore = (deps) => {
+    const { sessionsRoot, ensureDir, randomId, logger, enrichStateWithSession, workspaceStateSchemaVersion, workspaceSchemaError, } = deps;
+    const sessionStateCache = new Map();
+    const sessionWriteQueues = new Map();
+    const sessionWriteActive = new Set();
+    const sessionOffsetById = new Map();
+    const buildProjectionCache = new Map();
+    const enqueueSessionWrite = (sessionId, task) => {
+        const queue = sessionWriteQueues.get(sessionId) ?? [];
+        queue.push(task);
+        sessionWriteQueues.set(sessionId, queue);
+        if (sessionWriteActive.has(sessionId))
+            return;
+        sessionWriteActive.add(sessionId);
+        while (queue.length) {
+            const next = queue.shift();
+            if (!next)
+                continue;
+            try {
+                next();
+            }
+            catch (err) {
+                logger.warn(`[sim] session write failed: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        sessionWriteActive.delete(sessionId);
+    };
+    const mergeSessionState = (current, next) => {
+        if (!current)
+            return next;
+        const merged = {
+            ...current,
+            ...next,
+            meta: {
+                ...(current.meta ?? {}),
+                ...(next.meta ?? {}),
+            },
+            messages: next.messages ?? current.messages,
+            items: next.items ?? current.items,
+            format: next.format ?? current.format,
+            messageRefs: next.messageRefs ?? current.messageRefs,
+            feedback: next.feedback ?? current.feedback,
+            notes: next.notes ?? current.notes,
+            conversationScore: next.conversationScore ?? current.conversationScore,
+            traces: next.traces ?? current.traces,
+        };
+        return merged;
+    };
+    const parseFiniteInteger = (value) => {
+        if (typeof value !== "number" || !Number.isFinite(value))
+            return undefined;
+        if (!Number.isInteger(value))
+            return undefined;
+        return value;
+    };
+    const normalizeBuildProjectionRun = (workspaceId, value) => {
+        if (!value || typeof value !== "object") {
+            return {
+                id: workspaceId,
+                status: "idle",
+                messages: [],
+                traces: [],
+                toolInserts: [],
+            };
+        }
+        const run = value;
+        const status = run.status;
+        const normalizedStatus = status === "running" || status === "completed" ||
+            status === "error" || status === "canceled"
+            ? status
+            : "idle";
+        return {
+            id: typeof run.id === "string" && run.id.trim().length > 0
+                ? run.id
+                : workspaceId,
+            status: normalizedStatus,
+            error: typeof run.error === "string" ? run.error : undefined,
+            startedAt: typeof run.startedAt === "string" ? run.startedAt : undefined,
+            finishedAt: typeof run.finishedAt === "string"
+                ? run.finishedAt
+                : undefined,
+            messages: Array.isArray(run.messages)
+                ? run.messages
+                : [],
+            traces: Array.isArray(run.traces) ? run.traces : [],
+            toolInserts: Array.isArray(run.toolInserts)
+                ? run.toolInserts
+                : [],
+        };
+    };
+    const toCanonicalEventRecord = (args) => {
+        const payloadType = typeof args.data.type === "string"
+            ? args.data.type
+            : `gambit.${args.eventType}.event`;
+        const rawMeta = args.data._gambit;
+        const meta = rawMeta && typeof rawMeta === "object" && !Array.isArray(rawMeta)
+            ? rawMeta
+            : {};
+        return {
+            ...args.data,
+            type: payloadType,
+            offset: args.offset,
+            createdAt: args.createdAt,
+            _gambit: {
+                ...meta,
+                domain: args.eventType,
+                offset: args.offset,
+            },
+        };
+    };
+    const readEnvelopeRecords = (eventsPath) => {
+        try {
+            const text = dntShim.Deno.readTextFileSync(eventsPath);
+            const records = [];
+            let maxOffset = -1;
+            for (const line of text.split("\n")) {
+                if (!line.trim())
+                    continue;
+                const parsed = JSON.parse(line);
+                const offset = parseFiniteInteger(parsed.offset) ??
+                    parseFiniteInteger(parsed._gambit?.offset);
+                if (offset === undefined)
+                    continue;
+                const envelopeType = typeof parsed.type === "string" ? parsed.type : "";
+                const nestedData = parsed.data;
+                const payload = isWorkspaceEventDomain(envelopeType) &&
+                    nestedData && typeof nestedData === "object" &&
+                    !Array.isArray(nestedData)
+                    ? nestedData
+                    : parsed;
+                const payloadType = typeof payload.type === "string"
+                    ? payload.type
+                    : "";
+                if (!payloadType)
+                    continue;
+                const meta = parsed._gambit &&
+                    typeof parsed._gambit === "object" &&
+                    !Array.isArray(parsed._gambit)
+                    ? parsed._gambit
+                    : null;
+                const domain = (() => {
+                    const explicit = meta?.domain;
+                    if (explicit === "build" || explicit === "test" ||
+                        explicit === "grade" || explicit === "session") {
+                        return explicit;
+                    }
+                    if (isWorkspaceEventDomain(envelopeType)) {
+                        return envelopeType;
+                    }
+                    return inferWorkspaceDomain(payloadType);
+                })();
+                if (!domain)
+                    continue;
+                const createdAt = typeof parsed.createdAt === "string"
+                    ? parsed.createdAt
+                    : typeof parsed.created_at === "string"
+                        ? parsed.created_at
+                        : typeof payload.createdAt === "string"
+                            ? payload.createdAt
+                            : typeof payload.created_at === "string"
+                                ? payload.created_at
+                                : typeof meta?.created_at === "string"
+                                    ? meta.created_at
+                                    : new Date(0).toISOString();
+                const envelope = {
+                    offset,
+                    type: domain,
+                    createdAt,
+                    data: payload,
+                };
+                records.push(envelope);
+                if (offset > maxOffset) {
+                    maxOffset = offset;
+                }
+            }
+            return { records, maxOffset };
+        }
+        catch {
+            return { records: [], maxOffset: -1 };
+        }
+    };
+    const ensureMonotonicOffsets = (records, eventsPath) => {
+        let expected = 0;
+        let highest = -1;
+        for (const record of records) {
+            if (record.offset !== expected) {
+                throw new Error(`Non-monotonic offset in ${eventsPath}: expected ${expected}, got ${record.offset}`);
+            }
+            highest = record.offset;
+            expected = record.offset + 1;
+        }
+        return highest;
+    };
+    const getCurrentSessionOffset = (sessionId, state) => {
+        const cached = sessionOffsetById.get(sessionId);
+        if (cached !== undefined)
+            return cached;
+        const fromMeta = parseFiniteInteger(state?.meta
+            ?.lastAppliedOffset) ??
+            parseFiniteInteger(state?.meta
+                ?.lastAppliedEventSeq);
+        if (fromMeta !== undefined) {
+            sessionOffsetById.set(sessionId, fromMeta);
+            return fromMeta;
+        }
+        const eventsPath = typeof state?.meta?.sessionEventsPath === "string"
+            ? state.meta.sessionEventsPath
+            : path.join(sessionsRoot, sessionId, "events.jsonl");
+        const { records } = readEnvelopeRecords(eventsPath);
+        if (records.length > 0) {
+            const validated = ensureMonotonicOffsets(records, eventsPath);
+            sessionOffsetById.set(sessionId, validated);
+            return validated;
+        }
+        sessionOffsetById.set(sessionId, -1);
+        return -1;
+    };
+    const nextSessionOffsetCandidate = (sessionId, state) => getCurrentSessionOffset(sessionId, state) + 1;
+    const upsertScenarioRunSummary = (meta) => {
+        const scenarioRunId = typeof meta.scenarioRunId === "string"
+            ? meta.scenarioRunId
+            : undefined;
+        if (!scenarioRunId)
+            return;
+        const lastEventSeq = parseFiniteInteger(meta.lastAppliedOffset) ??
+            parseFiniteInteger(meta.lastAppliedEventSeq) ??
+            0;
+        const updatedAt = typeof meta.sessionUpdatedAt === "string"
+            ? meta.sessionUpdatedAt
+            : new Date().toISOString();
+        const selectedScenarioDeckId = typeof meta.selectedScenarioDeckId === "string"
+            ? meta.selectedScenarioDeckId
+            : typeof meta.testBotName === "string"
+                ? meta.testBotName
+                : "unknown";
+        const selectedScenarioDeckLabel = typeof meta.selectedScenarioDeckLabel === "string"
+            ? meta.selectedScenarioDeckLabel
+            : undefined;
+        const scenarioConfigPath = typeof meta.scenarioConfigPath === "string"
+            ? meta.scenarioConfigPath
+            : typeof meta.testBotConfigPath === "string"
+                ? meta.testBotConfigPath
+                : typeof meta.deck === "string"
+                    ? meta.deck
+                    : "unknown";
+        const previous = Array.isArray(meta.scenarioRunSummaries)
+            ? meta.scenarioRunSummaries
+            : [];
+        const nextSummary = {
+            scenarioRunId,
+            lastEventSeq,
+            updatedAt,
+            selectedScenarioDeckId,
+            selectedScenarioDeckLabel,
+            scenarioConfigPath,
+        };
+        const existingIdx = previous.findIndex((entry) => entry.scenarioRunId === scenarioRunId);
+        meta.scenarioRunSummaries = existingIdx >= 0
+            ? previous.map((entry, idx) => idx === existingIdx ? nextSummary : entry)
+            : [...previous, nextSummary];
+        meta.scenarioRunSummary = nextSummary;
+    };
+    const normalizeScenarioRunSummary = (value) => {
+        if (!value || typeof value !== "object")
+            return null;
+        const summary = value;
+        const scenarioRunId = typeof summary.scenarioRunId === "string"
+            ? summary.scenarioRunId
+            : null;
+        const lastEventSeq = parseFiniteInteger(summary.lastEventSeq);
+        const updatedAt = typeof summary.updatedAt === "string"
+            ? summary.updatedAt
+            : null;
+        const selectedScenarioDeckId = typeof summary.selectedScenarioDeckId === "string"
+            ? summary.selectedScenarioDeckId
+            : null;
+        const selectedScenarioDeckLabel = typeof summary.selectedScenarioDeckLabel === "string"
+            ? summary.selectedScenarioDeckLabel
+            : undefined;
+        const scenarioConfigPath = typeof summary.scenarioConfigPath === "string"
+            ? summary.scenarioConfigPath
+            : null;
+        if (!scenarioRunId || lastEventSeq === undefined || !updatedAt ||
+            !selectedScenarioDeckId || !scenarioConfigPath) {
+            return null;
+        }
+        return {
+            scenarioRunId,
+            lastEventSeq,
+            updatedAt,
+            selectedScenarioDeckId,
+            selectedScenarioDeckLabel,
+            scenarioConfigPath,
+        };
+    };
+    const selectCanonicalScenarioRunSummary = (meta) => {
+        const fromCurrent = normalizeScenarioRunSummary(meta.scenarioRunSummary);
+        const fromListRaw = Array.isArray(meta.scenarioRunSummaries)
+            ? meta.scenarioRunSummaries
+            : [];
+        const fromList = fromListRaw
+            .map((entry) => normalizeScenarioRunSummary(entry))
+            .filter((entry) => Boolean(entry));
+        const all = fromCurrent ? [fromCurrent, ...fromList] : fromList;
+        if (!all.length)
+            return null;
+        all.sort((a, b) => {
+            if (a.lastEventSeq !== b.lastEventSeq) {
+                return b.lastEventSeq - a.lastEventSeq;
+            }
+            if (a.updatedAt !== b.updatedAt) {
+                return b.updatedAt.localeCompare(a.updatedAt);
+            }
+            return a.scenarioRunId.localeCompare(b.scenarioRunId);
+        });
+        return all[0] ?? null;
+    };
+    const materializeSnapshot = (state) => {
+        const snapshot = { ...state };
+        const sessionId = typeof snapshot.meta?.sessionId === "string"
+            ? snapshot.meta.sessionId
+            : undefined;
+        if (sessionId) {
+            const meta = { ...(snapshot.meta ?? {}) };
+            const lastAppliedOffset = getCurrentSessionOffset(sessionId, snapshot);
+            meta.lastAppliedOffset = lastAppliedOffset;
+            meta.lastAppliedEventSeq = lastAppliedOffset;
+            upsertScenarioRunSummary(meta);
+            snapshot.meta = meta;
+        }
+        delete snapshot.traces;
+        return snapshot;
+    };
+    const writeJsonAtomic = (filePath, payload) => {
+        const dir = path.dirname(filePath);
+        ensureDir(dir);
+        const tmpPath = path.join(dir, `.tmp-${path.basename(filePath)}-${randomId("tmp")}`);
+        dntShim.Deno.writeTextFileSync(tmpPath, safeStringify(payload, 2));
+        dntShim.Deno.renameSync(tmpPath, filePath);
+    };
+    const appendJsonl = (filePath, payload) => {
+        const dir = path.dirname(filePath);
+        ensureDir(dir);
+        const line = safeStringify(payload);
+        dntShim.Deno.writeTextFileSync(filePath, `${line}\n`, { append: true });
+    };
+    const readBuildProjection = (workspaceId) => {
+        const cached = buildProjectionCache.get(workspaceId);
+        if (cached)
+            return cached;
+        const filePath = path.join(sessionsRoot, workspaceId, "build_state.json");
+        try {
+            const parsed = JSON.parse(dntShim.Deno.readTextFileSync(filePath));
+            const lastAppliedOffset = parseFiniteInteger(parsed.lastAppliedOffset) ??
+                -1;
+            const run = normalizeBuildProjectionRun(workspaceId, parsed.run);
+            const projection = {
+                workspaceId,
+                lastAppliedOffset,
+                run,
+                state: parsed.state && typeof parsed.state === "object"
+                    ? parsed.state
+                    : undefined,
+            };
+            buildProjectionCache.set(workspaceId, projection);
+            return projection;
+        }
+        catch {
+            const empty = {
+                workspaceId,
+                lastAppliedOffset: -1,
+                run: {
+                    id: workspaceId,
+                    status: "idle",
+                    messages: [],
+                    traces: [],
+                    toolInserts: [],
+                },
+                state: undefined,
+            };
+            buildProjectionCache.set(workspaceId, empty);
+            return empty;
+        }
+    };
+    const replayBuildProjection = (workspaceId, envelopes) => {
+        const state = {
+            workspaceId,
+            lastAppliedOffset: -1,
+            run: {
+                id: workspaceId,
+                status: "idle",
+                messages: [],
+                traces: [],
+                toolInserts: [],
+            },
+        };
+        for (const envelope of envelopes) {
+            state.lastAppliedOffset = envelope.offset;
+            if (envelope.type !== "build")
+                continue;
+            const payloadType = typeof envelope.data.type === "string"
+                ? envelope.data.type
+                : "";
+            if (payloadType === "buildBotStatus" ||
+                payloadType === "gambit.build.status") {
+                const run = normalizeBuildProjectionRun(workspaceId, envelope.data.run);
+                state.run = run;
+                const buildStateSnapshot = envelope.data.state;
+                if (buildStateSnapshot && typeof buildStateSnapshot === "object") {
+                    state.state = buildStateSnapshot;
+                }
+                continue;
+            }
+            if (payloadType === "buildBotTrace" || payloadType === "gambit.build.trace") {
+                const event = envelope.data.event;
+                if (event && typeof event === "object") {
+                    const currentTraces = Array.isArray(state.run.traces)
+                        ? state.run.traces
+                        : [];
+                    state.run = {
+                        ...state.run,
+                        traces: [...currentTraces, event],
+                    };
+                }
+            }
+        }
+        return state;
+    };
+    const rebuildBuildProjectionFromEvents = (workspaceId, eventsPath) => {
+        const { records } = readEnvelopeRecords(eventsPath);
+        if (records.length > 0) {
+            ensureMonotonicOffsets(records, eventsPath);
+        }
+        const projection = replayBuildProjection(workspaceId, records);
+        const buildPath = path.join(sessionsRoot, workspaceId, "build_state.json");
+        writeJsonAtomic(buildPath, projection);
+        buildProjectionCache.set(workspaceId, projection);
+    };
+    const updateSnapshotBoundary = (sessionId, statePath, offset) => {
+        if (!statePath || !existsSync(statePath))
+            return;
+        try {
+            const text = dntShim.Deno.readTextFileSync(statePath);
+            const parsed = JSON.parse(text);
+            const parsedMeta = parsed.meta && typeof parsed.meta === "object"
+                ? parsed.meta
+                : {};
+            const previousBoundary = parseFiniteInteger(parsedMeta.lastAppliedOffset) ??
+                parseFiniteInteger(parsedMeta.lastAppliedEventSeq) ??
+                -1;
+            if (offset <= previousBoundary)
+                return;
+            parsedMeta.lastAppliedOffset = offset;
+            parsedMeta.lastAppliedEventSeq = offset;
+            parsedMeta.sessionUpdatedAt = new Date().toISOString();
+            upsertScenarioRunSummary(parsedMeta);
+            const nextState = { ...parsed, meta: parsedMeta };
+            writeJsonAtomic(statePath, nextState);
+            sessionStateCache.set(sessionId, nextState);
+        }
+        catch {
+            // Keep append-only logging best-effort even if snapshot boundary update fails.
+        }
+    };
+    const appendWorkspaceEnvelope = (state, eventType, data) => {
+        const sessionId = typeof state.meta?.sessionId === "string"
+            ? state.meta.sessionId
+            : undefined;
+        const eventsPath = typeof state.meta?.sessionEventsPath === "string"
+            ? state.meta.sessionEventsPath
+            : undefined;
+        const statePath = typeof state.meta?.sessionStatePath === "string"
+            ? state.meta.sessionStatePath
+            : undefined;
+        if (!sessionId || !eventsPath)
+            return null;
+        const normalizedData = (() => {
+            const rawType = typeof data.type === "string" ? data.type : "";
+            if (!rawType)
+                return data;
+            const { canonicalType, legacyType } = normalizeEventType(rawType, data.kind);
+            if (!legacyType) {
+                return { ...data, type: canonicalType };
+            }
+            const rawMeta = data._gambit;
+            const meta = rawMeta && typeof rawMeta === "object" && !Array.isArray(rawMeta)
+                ? rawMeta
+                : {};
+            return {
+                ...data,
+                type: canonicalType,
+                _gambit: {
+                    ...meta,
+                    legacy_type: legacyType,
+                    domain: eventType,
+                },
+            };
+        })();
+        const createdAt = new Date().toISOString();
+        const optimisticOffset = nextSessionOffsetCandidate(sessionId, state);
+        const envelope = {
+            offset: optimisticOffset,
+            createdAt,
+            type: eventType,
+            data: normalizedData,
+        };
+        enqueueSessionWrite(sessionId, () => {
+            const offset = nextSessionOffsetCandidate(sessionId, state);
+            appendJsonl(eventsPath, toCanonicalEventRecord({
+                eventType,
+                offset,
+                createdAt,
+                data: normalizedData,
+            }));
+            sessionOffsetById.set(sessionId, offset);
+            if (state.meta && typeof state.meta === "object") {
+                state.meta.lastAppliedOffset = offset;
+                state.meta.lastAppliedEventSeq = offset;
+            }
+            updateSnapshotBoundary(sessionId, statePath, offset);
+            if (eventType === "build") {
+                rebuildBuildProjectionFromEvents(sessionId, eventsPath);
+            }
+        });
+        return envelope;
+    };
+    const appendSessionEvent = (state, payload) => appendWorkspaceEnvelope(state, "session", payload);
+    const appendFeedbackLog = (state, payload) => appendWorkspaceEnvelope(state, "session", {
+        ...payload,
+        logType: "feedback",
+    });
+    const appendGradingLog = (state, payload) => appendWorkspaceEnvelope(state, "grade", payload);
+    const appendErrorLog = (state, payload) => appendWorkspaceEnvelope(state, "session", {
+        ...payload,
+        logType: "error",
+    });
+    const appendServerErrorLog = (workspaceId, payload) => {
+        if (!workspaceId)
+            return;
+        const state = readSessionState(workspaceId);
+        if (!state)
+            return;
+        appendErrorLog(state, {
+            type: "server.error",
+            ...payload,
+        });
+    };
+    const loadSessionTraces = (state) => {
+        const eventsPath = typeof state.meta?.sessionEventsPath === "string"
+            ? state.meta.sessionEventsPath
+            : undefined;
+        if (!eventsPath)
+            return [];
+        try {
+            const { records } = readEnvelopeRecords(eventsPath);
+            if (records.length > 0) {
+                ensureMonotonicOffsets(records, eventsPath);
+            }
+            const traces = [];
+            for (const envelope of records) {
+                const record = envelope.data;
+                const kind = typeof record.kind === "string" ? record.kind : "";
+                const type = typeof record.type === "string" ? record.type : "";
+                if (kind === "trace" || isTraceEventType(type)) {
+                    const normalized = normalizePersistedTraceRecord(record);
+                    if (normalized)
+                        traces.push(normalized);
+                }
+            }
+            return traces;
+        }
+        catch {
+            return [];
+        }
+    };
+    const persistSessionState = (state) => {
+        const { state: enriched, dir } = enrichStateWithSession(state);
+        const sessionId = typeof enriched.meta?.sessionId === "string"
+            ? enriched.meta.sessionId
+            : undefined;
+        const merged = sessionId
+            ? mergeSessionState(sessionStateCache.get(sessionId), enriched)
+            : enriched;
+        if (sessionId) {
+            sessionStateCache.set(sessionId, merged);
+        }
+        if (dir && sessionId) {
+            const snapshot = materializeSnapshot(merged);
+            const eventsPath = typeof snapshot.meta?.sessionEventsPath === "string"
+                ? snapshot.meta.sessionEventsPath
+                : path.join(dir, "events.jsonl");
+            const statePath = typeof snapshot.meta?.sessionStatePath === "string"
+                ? snapshot.meta.sessionStatePath
+                : path.join(dir, "state.json");
+            enqueueSessionWrite(sessionId, () => {
+                try {
+                    ensureDir(dir);
+                    const firstWrite = !existsSync(eventsPath);
+                    if (firstWrite) {
+                        const startOffset = nextSessionOffsetCandidate(sessionId, snapshot);
+                        appendJsonl(eventsPath, toCanonicalEventRecord({
+                            eventType: "session",
+                            offset: startOffset,
+                            createdAt: new Date().toISOString(),
+                            data: {
+                                type: "gambit.session.start",
+                                _gambit: {
+                                    legacy_type: "session.start",
+                                    domain: "session",
+                                },
+                                category: "lifecycle",
+                                sessionId,
+                                runId: snapshot.runId,
+                                deck: snapshot.meta?.deck,
+                            },
+                        }));
+                        sessionOffsetById.set(sessionId, startOffset);
+                    }
+                    const snapshotOffset = nextSessionOffsetCandidate(sessionId, snapshot);
+                    const snapshotToWrite = {
+                        ...snapshot,
+                        meta: {
+                            ...(snapshot.meta ?? {}),
+                            lastAppliedOffset: snapshotOffset,
+                            lastAppliedEventSeq: snapshotOffset,
+                        },
+                    };
+                    appendJsonl(eventsPath, toCanonicalEventRecord({
+                        eventType: "session",
+                        offset: snapshotOffset,
+                        createdAt: new Date().toISOString(),
+                        data: {
+                            type: "session.snapshot",
+                            category: "snapshot",
+                            sessionId,
+                            runId: snapshotToWrite.runId,
+                            state: snapshotToWrite,
+                        },
+                    }));
+                    // Advance in-memory offset immediately after append so a later
+                    // snapshot write failure cannot cause duplicate offsets on retry.
+                    sessionOffsetById.set(sessionId, snapshotOffset);
+                    writeJsonAtomic(statePath, snapshotToWrite);
+                    rebuildBuildProjectionFromEvents(sessionId, eventsPath);
+                }
+                catch (err) {
+                    logger.warn(`[sim] failed to persist session state: ${err instanceof Error ? err.message : err}`);
+                }
+            });
+        }
+        return merged;
+    };
+    const readSessionStateStrict = (sessionId, opts) => {
+        const dir = path.join(sessionsRoot, sessionId);
+        const filePath = path.join(dir, "state.json");
+        const text = dntShim.Deno.readTextFileSync(filePath);
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object") {
+            throw new Error(`Invalid workspace state payload at ${filePath}`);
+        }
+        const parsedMeta = parsed.meta && typeof parsed.meta === "object"
+            ? parsed.meta
+            : {};
+        const schemaVersion = typeof parsedMeta.workspaceSchemaVersion === "string"
+            ? parsedMeta.workspaceSchemaVersion.trim()
+            : null;
+        // Backward compatibility: legacy workspace state files may not include
+        // workspaceSchemaVersion yet. Treat missing schema as v1-equivalent.
+        if (schemaVersion && schemaVersion !== workspaceStateSchemaVersion) {
+            throw new Error(workspaceSchemaError(sessionId, schemaVersion));
+        }
+        const meta = {
+            ...parsedMeta,
+            sessionId,
+            workspaceId: typeof parsedMeta.workspaceId === "string" &&
+                parsedMeta.workspaceId.trim().length > 0
+                ? parsedMeta.workspaceId
+                : sessionId,
+            sessionDir: dir,
+            workspaceSchemaVersion: workspaceStateSchemaVersion,
+        };
+        if (typeof meta.sessionStatePath !== "string") {
+            meta.sessionStatePath = filePath;
+        }
+        if (typeof meta.sessionEventsPath !== "string") {
+            meta.sessionEventsPath = path.join(dir, "events.jsonl");
+        }
+        if (typeof meta.sessionBuildStatePath !== "string") {
+            meta.sessionBuildStatePath = path.join(dir, "build_state.json");
+        }
+        const eventsPath = typeof meta.sessionEventsPath === "string"
+            ? meta.sessionEventsPath
+            : undefined;
+        if (eventsPath) {
+            const { records, maxOffset } = readEnvelopeRecords(eventsPath);
+            if (records.length > 0) {
+                const validated = ensureMonotonicOffsets(records, eventsPath);
+                const lastAppliedOffset = validated >= 0 ? validated : maxOffset;
+                meta.lastAppliedOffset = lastAppliedOffset;
+                meta.lastAppliedEventSeq = lastAppliedOffset;
+                sessionOffsetById.set(sessionId, lastAppliedOffset);
+            }
+            else if (typeof meta.lastAppliedOffset !== "number") {
+                meta.lastAppliedOffset = -1;
+                meta.lastAppliedEventSeq = -1;
+            }
+        }
+        const enriched = { ...parsed, meta };
+        if (opts?.withTraces) {
+            const loadedTraces = loadSessionTraces(enriched);
+            const fallbackTraces = Array.isArray(enriched.traces)
+                ? enriched.traces
+                : [];
+            const traces = loadedTraces.length > 0 ? loadedTraces : fallbackTraces;
+            const withTraces = { ...enriched, traces };
+            sessionStateCache.set(sessionId, withTraces);
+            return withTraces;
+        }
+        sessionStateCache.set(sessionId, enriched);
+        return enriched;
+    };
+    const readSessionState = (sessionId, opts) => {
+        try {
+            return readSessionStateStrict(sessionId, opts);
+        }
+        catch (err) {
+            if (err instanceof dntShim.Deno.errors.NotFound)
+                return undefined;
+            logger.warn(`[sim] failed to read workspace state for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    };
+    const readBuildState = (workspaceId) => {
+        const state = readSessionState(workspaceId);
+        if (!state)
+            return undefined;
+        const eventsPath = typeof state.meta?.sessionEventsPath === "string"
+            ? state.meta.sessionEventsPath
+            : path.join(sessionsRoot, workspaceId, "events.jsonl");
+        if (existsSync(eventsPath)) {
+            rebuildBuildProjectionFromEvents(workspaceId, eventsPath);
+        }
+        return readBuildProjection(workspaceId);
+    };
+    return {
+        parseFiniteInteger,
+        selectCanonicalScenarioRunSummary,
+        appendWorkspaceEnvelope,
+        appendSessionEvent,
+        appendFeedbackLog,
+        appendGradingLog,
+        appendErrorLog,
+        appendServerErrorLog,
+        persistSessionState,
+        readSessionStateStrict,
+        readSessionState,
+        readBuildState,
+        replayBuildProjection,
+    };
+};