@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/sessions/assistant-initiative-append.js

@@ -0,0 +1,64 @@
+import { assertAssistantInitiative } from "./assistant-initiative.js";
+import { saveDurableSessionFile } from "./durable-session-commit.js";
+import { deleteSessionFile, ensureSessionsDir, loadSessionFile } from "./session-store.js";
+import { assertValidSessionId } from "./record/rules.js";
+import { assertSessionKindUnchanged, sessionKindCreationFields } from "./spark-session.js";
+/** Covers the proactive owner's complete retained receipt window. Never model context. */
+export const MAX_ASSISTANT_INITIATIVE_RECEIPTS = 100;
+/** Pure append shared by storage adapters; proposal identity is the replay key. */
+export function appendSparkInitiativeRecord(existing, sessionId, input, now) {
+    input.assertCurrent?.();
+    assertValidSessionId(sessionId);
+    assertAssistantInitiative(input);
+    const identity = sessionKindCreationFields(sessionId, { kind: "spark" });
+    if (existing)
+        assertSessionKindUnchanged(existing, "spark");
+    if (hasSavedInitiative(existing, input.initiative.proposalId))
+        return existing;
+    const timestamp = now.toISOString();
+    const session = existing ?? {
+        id: sessionId, ...identity, createdAt: timestamp, updatedAt: timestamp,
+        lastAgentMode: "reasoning", messageCount: 0, messages: [],
+    };
+    const messages = [...session.messages, {
+            id: `initiative:${input.initiative.proposalId}`, role: "assistant", content: input.content,
+            source: "co_worker", grounding: "conversation", createdAt: timestamp, initiative: input.initiative,
+        }];
+    const assistantInitiativeReceipts = [...(session.assistantInitiativeReceipts ?? []), input.initiative.proposalId]
+        .slice(-MAX_ASSISTANT_INITIATIVE_RECEIPTS);
+    return { ...session, messages, messageCount: messages.length, updatedAt: timestamp, assistantInitiativeReceipts };
+}
+function hasSavedInitiative(session, proposalId) {
+    if (!session)
+        return false;
+    if (session.assistantInitiativeReceipts?.includes(proposalId))
+        return true;
+    return hasVisibleAssistantInitiative(session, proposalId);
+}
+export function hasVisibleAssistantInitiative(session, proposalId) {
+    return session.messages.some((message) => message.initiative?.proposalId === proposalId);
+}
+/** Caller holds the canonical session mutation queue across commit and rollback. */
+export async function appendAssistantInitiativeRecord(options) {
+    options.input.assertCurrent?.();
+    assertValidSessionId(options.sessionId);
+    await ensureSessionsDir(options.directory);
+    const existing = await loadSessionFile(options.directory, options.sessionId);
+    const record = appendSparkInitiativeRecord(existing, options.sessionId, options.input, options.now);
+    if (record === existing)
+        return record;
+    await saveDurableSessionFile(options.directory, record, options.input.assertCurrent);
+    try {
+        options.input.assertCurrent?.();
+    }
+    catch (error) {
+        await restorePreInitiativeRecord(options.directory, options.sessionId, existing);
+        throw error;
+    }
+    return record;
+}
+async function restorePreInitiativeRecord(directory, sessionId, existing) {
+    if (existing)
+        return saveDurableSessionFile(directory, existing);
+    await deleteSessionFile(directory, sessionId);
+}

package/dist/src/sessions/assistant-initiative-message.d.ts

@@ -0,0 +1,3 @@
+import type { SessionMessage } from "./types.js";
+/** Classification shared by persisted projections and model history. */
+export declare function isAssistantInitiativeMessage(message: SessionMessage): boolean;

package/dist/src/sessions/assistant-initiative-message.js

@@ -0,0 +1,12 @@
+/** Classification shared by persisted projections and model history. */
+export function isAssistantInitiativeMessage(message) {
+    if (message.role !== "assistant")
+        return false;
+    if (message.source !== "co_worker")
+        return false;
+    if (message.initiative?.kind !== "proactive_proposal_v1")
+        return false;
+    if (typeof message.initiative.proposalId !== "string")
+        return false;
+    return message.initiative.proposalId.length > 0;
+}

package/dist/src/sessions/assistant-initiative.d.ts

@@ -1,4 +1,5 @@
-import type { SessionMessage, SessionRecord } from "./types.js";
+import type { SessionRecord } from "./types.js";
+export { isAssistantInitiativeMessage } from "./assistant-initiative-message.js";
 export type AssistantInitiative = Readonly<{
     kind: "proactive_proposal_v1";
     proposalId: string;
@@ -8,6 +9,9 @@ export type AssistantInitiative = Readonly<{
         id: string;
         version: string;
     }>[];
+    /** Optional only for legacy initiatives authored before context handoffs. */
+    handoffBrief?: string;
+    handoffTitle?: string;
 }>;
 export type CreateAssistantConversationInput = Readonly<{
     title: string;
@@ -23,4 +27,4 @@ export declare function createAssistantConversationRecord(options: {
     input: CreateAssistantConversationInput;
     now: Date;
 }): Promise<SessionRecord>;
-export declare function isAssistantInitiativeMessage(message: SessionMessage): boolean;
+export declare function assertAssistantInitiative(input: CreateAssistantConversationInput): void;

package/dist/src/sessions/assistant-initiative.js

@@ -1,5 +1,7 @@
 import { assertValidSessionId } from "./record/rules.js";
 import { deleteSessionFile, ensureSessionsDir, loadSessionFile, saveSessionFile } from "./session-store.js";
+import { isSparkHandoffBrief } from "./spark-handoff-brief.js";
+export { isAssistantInitiativeMessage } from "./assistant-initiative-message.js";
 /** Called under the same per-session mutation queue as edits and deletion. */
 export async function createAssistantConversationRecord(options) {
     const { sessionId, input } = options;
@@ -33,14 +35,7 @@ export async function createAssistantConversationRecord(options) {
     }
     return record;
 }
-export function isAssistantInitiativeMessage(message) {
-    if (message.role !== "assistant" || message.source !== "co_worker")
-        return false;
-    if (message.initiative?.kind !== "proactive_proposal_v1")
-        return false;
-    return typeof message.initiative.proposalId === "string" && message.initiative.proposalId.length > 0;
-}
-function assertAssistantInitiative(input) {
+export function assertAssistantInitiative(input) {
     if (!input.title.trim() || input.title.length > 160)
         throw new Error("assistant_initiative_title_invalid");
     if (!input.content.trim() || input.content.length > 4000)
@@ -49,6 +44,11 @@ function assertAssistantInitiative(input) {
         throw new Error("assistant_initiative_binding_invalid");
     if (!input.initiative.reason.trim() || input.initiative.reason.length > 1000)
         throw new Error("assistant_initiative_reason_invalid");
+    if (input.initiative.handoffBrief !== undefined && !isSparkHandoffBrief(input.initiative.handoffBrief))
+        throw new Error("assistant_initiative_handoff_brief_invalid");
+    if (input.initiative.handoffTitle !== undefined &&
+        (typeof input.initiative.handoffTitle !== "string" || !input.initiative.handoffTitle.trim() || input.initiative.handoffTitle.length > 160))
+        throw new Error("assistant_initiative_handoff_title_invalid");
     if (!input.initiative.sources.length || input.initiative.sources.length > 12)
         throw new Error("assistant_initiative_sources_invalid");
     for (const source of input.initiative.sources) {

package/dist/src/sessions/automation-session-origin.d.ts

@@ -0,0 +1,34 @@
+export type AutomationSessionOrigin = Readonly<{
+    kind: "automation_node_v1";
+    automationId: string;
+    runId: string;
+    nodeId: string;
+    attemptId: string;
+}>;
+/** Runtime-only authority. A matching JSON object cannot recreate this handle. */
+export type AutomationSessionHandle = Readonly<{
+    kind: "automation_session_handle";
+}>;
+export declare class AutomationSessionLockedError extends Error {
+    readonly code = "automation_session_locked";
+    constructor();
+}
+export declare function isAutomationSessionLockedError(error: unknown): boolean;
+export declare function isAutomationSessionOrigin(value: unknown): value is AutomationSessionOrigin;
+export declare function hasAutomationSessionOrigin(value: {
+    automationOrigin?: unknown;
+}): boolean;
+/** One SessionService instance owns its handles and async execution scope. */
+export declare function createAutomationSessionAccess(): Readonly<{
+    canAccess: (sessionId: string, record: {
+        automationOrigin?: unknown;
+    }) => boolean;
+    assertAccess(sessionId: string, record: {
+        automationOrigin?: unknown;
+    }): void;
+    issue(sessionId: string, origin: AutomationSessionOrigin): Readonly<{
+        kind: "automation_session_handle";
+    }>;
+    revoke(handle: AutomationSessionHandle): void;
+    run<T>(handle: AutomationSessionHandle, task: () => Promise<T>): Promise<T>;
+}>;

package/dist/src/sessions/automation-session-origin.js

@@ -0,0 +1,78 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export class AutomationSessionLockedError extends Error {
+    code = "automation_session_locked";
+    constructor() {
+        super("automation_session_locked");
+        this.name = "AutomationSessionLockedError";
+    }
+}
+export function isAutomationSessionLockedError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const value = error;
+    return (value.code === "automation_session_locked" ||
+        value.message === "automation_session_locked");
+}
+export function isAutomationSessionOrigin(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const origin = value;
+    return (origin.kind === "automation_node_v1" &&
+        hasIdentity(origin.automationId) &&
+        hasIdentity(origin.runId) &&
+        hasIdentity(origin.nodeId) &&
+        hasIdentity(origin.attemptId));
+}
+export function hasAutomationSessionOrigin(value) {
+    const origin = value.automationOrigin;
+    return (!!origin &&
+        typeof origin === "object" &&
+        origin.kind === "automation_node_v1");
+}
+function hasIdentity(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function matchesOrigin(expected, actual) {
+    return (expected.automationId === actual.automationId &&
+        expected.runId === actual.runId &&
+        expected.nodeId === actual.nodeId &&
+        expected.attemptId === actual.attemptId);
+}
+/** One SessionService instance owns its handles and async execution scope. */
+export function createAutomationSessionAccess() {
+    const scope = new AsyncLocalStorage();
+    const handles = new WeakMap();
+    function canAccess(sessionId, record) {
+        if (!hasAutomationSessionOrigin(record))
+            return true;
+        const current = scope.getStore();
+        return (current?.sessionId === sessionId &&
+            isAutomationSessionOrigin(record.automationOrigin) &&
+            matchesOrigin(current.origin, record.automationOrigin));
+    }
+    return Object.freeze({
+        canAccess,
+        assertAccess(sessionId, record) {
+            if (!canAccess(sessionId, record))
+                throw new AutomationSessionLockedError();
+        },
+        issue(sessionId, origin) {
+            if (!isAutomationSessionOrigin(origin))
+                throw new Error("automation_session_origin_invalid");
+            const handle = Object.freeze({
+                kind: "automation_session_handle",
+            });
+            handles.set(handle, Object.freeze({ sessionId, origin }));
+            return handle;
+        },
+        revoke(handle) {
+            handles.delete(handle);
+        },
+        async run(handle, task) {
+            const accepted = handles.get(handle);
+            if (!accepted)
+                throw new AutomationSessionLockedError();
+            return await scope.run(accepted, task);
+        },
+    });
+}

package/dist/src/sessions/automation-session-store.d.ts

@@ -0,0 +1,12 @@
+import { type AutomationSessionHandle, type AutomationSessionOrigin, type createAutomationSessionAccess } from "./automation-session-origin.js";
+/** Adapter-owned lifetime and recovery for hidden attempt transcripts only. */
+export declare function createAutomationSessionStore(input: {
+    sessionsDir: string;
+    now(): Date;
+    access: ReturnType<typeof createAutomationSessionAccess>;
+    enqueue<T>(sessionId: string, mutation: () => Promise<T>): Promise<T>;
+}): {
+    create: (sessionId: string, origin: AutomationSessionOrigin) => Promise<AutomationSessionHandle>;
+    release: (handle: AutomationSessionHandle) => void;
+    reconcile: (cleanupAttachments: (id: string) => Promise<void>, onError: (sessionId: string, error: unknown) => void) => Promise<void>;
+};

package/dist/src/sessions/automation-session-store.js

@@ -0,0 +1,129 @@
+import { readdir } from "node:fs/promises";
+import { AutomationSessionLockedError, hasAutomationSessionOrigin, isAutomationSessionOrigin } from "./automation-session-origin.js";
+import { assertValidSessionId } from "./record/rules.js";
+import { saveDurableSessionFile } from "./durable-session-commit.js";
+import { deleteSessionFile, ensureSessionsDir, loadSessionFile } from "./session-store.js";
+const MAX_SESSION_RETIREMENTS = 64;
+const MAX_SESSION_SCANS = 256;
+/** Adapter-owned lifetime and recovery for hidden attempt transcripts only. */
+export function createAutomationSessionStore(input) {
+    const handles = new WeakMap();
+    const owners = new Map();
+    const retiring = new Set();
+    let cursor = "";
+    let reconciliation;
+    function releaseOwner(sessionId) {
+        const remaining = (owners.get(sessionId) ?? 1) - 1;
+        if (remaining > 0) {
+            owners.set(sessionId, remaining);
+            return;
+        }
+        owners.delete(sessionId);
+    }
+    async function create(sessionId, origin) {
+        assertValidSessionId(sessionId);
+        if (!isAutomationSessionOrigin(origin))
+            throw new Error("automation_session_origin_invalid");
+        if (retiring.has(sessionId))
+            throw new AutomationSessionLockedError();
+        const handle = input.access.issue(sessionId, origin);
+        owners.set(sessionId, (owners.get(sessionId) ?? 0) + 1);
+        try {
+            await input.access.run(handle, () => input.enqueue(sessionId, async () => {
+                await ensureSessionsDir(input.sessionsDir);
+                const existing = await loadSessionFile(input.sessionsDir, sessionId);
+                if (existing && !hasAutomationSessionOrigin(existing))
+                    throw new Error("automation_session_origin_conflict");
+                if (existing)
+                    return;
+                const timestamp = input.now().toISOString();
+                await saveDurableSessionFile(input.sessionsDir, {
+                    id: sessionId, automationOrigin: Object.freeze({ ...origin }), title: sessionId,
+                    createdAt: timestamp, updatedAt: timestamp, lastAgentMode: "reasoning",
+                    messageCount: 0, messages: [],
+                });
+            }));
+            handles.set(handle, sessionId);
+            return handle;
+        }
+        catch (error) {
+            input.access.revoke(handle);
+            releaseOwner(sessionId);
+            throw error;
+        }
+    }
+    function release(handle) {
+        const sessionId = handles.get(handle);
+        if (!sessionId)
+            return;
+        handles.delete(handle);
+        input.access.revoke(handle);
+        releaseOwner(sessionId);
+    }
+    async function retire(sessionId, origin, cleanupAttachments) {
+        // Claim synchronously before issuing recovery authority or awaiting storage.
+        if (owners.has(sessionId))
+            return;
+        retiring.add(sessionId);
+        const handle = input.access.issue(sessionId, origin);
+        try {
+            await input.access.run(handle, () => input.enqueue(sessionId, async () => {
+                const current = await loadSessionFile(input.sessionsDir, sessionId);
+                if (!current || current.id !== sessionId)
+                    return;
+                if (!isAutomationSessionOrigin(current.automationOrigin))
+                    return;
+                input.access.assertAccess(sessionId, current);
+                // Keep the durable origin until its dependent cleanup succeeds.
+                await cleanupAttachments(sessionId);
+                await deleteSessionFile(input.sessionsDir, sessionId);
+            }));
+        }
+        finally {
+            input.access.revoke(handle);
+            retiring.delete(sessionId);
+        }
+    }
+    async function reconcileFiles(cleanupAttachments, onError) {
+        await ensureSessionsDir(input.sessionsDir);
+        const entries = await readdir(input.sessionsDir, { withFileTypes: true });
+        const names = entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+            .map((entry) => entry.name).sort();
+        const ordered = [...names.filter((name) => name > cursor), ...names.filter((name) => name <= cursor)];
+        let attempted = 0;
+        let scanned = 0;
+        for (const name of ordered) {
+            if (attempted === MAX_SESSION_RETIREMENTS)
+                break;
+            if (scanned === MAX_SESSION_SCANS)
+                break;
+            scanned += 1;
+            cursor = name;
+            const sessionId = name.slice(0, -5);
+            if (owners.has(sessionId))
+                continue;
+            try {
+                assertValidSessionId(sessionId);
+                const session = await loadSessionFile(input.sessionsDir, sessionId);
+                if (!session || session.id !== sessionId)
+                    continue;
+                if (!isAutomationSessionOrigin(session.automationOrigin))
+                    continue;
+                attempted += 1;
+                await retire(sessionId, session.automationOrigin, cleanupAttachments);
+            }
+            catch (error) {
+                // Advancing the cursor also for failures keeps later bounded batches fair.
+                onError(sessionId, error);
+            }
+        }
+    }
+    function reconcile(cleanupAttachments, onError) {
+        if (reconciliation)
+            return reconciliation;
+        reconciliation = reconcileFiles(cleanupAttachments, onError)
+            .finally(() => { reconciliation = undefined; });
+        return reconciliation;
+    }
+    return { create, release, reconcile };
+}

package/dist/src/sessions/durable-session-commit.d.ts

@@ -1,4 +1,5 @@
 import type { SessionRecord } from "./types.js";
+import type { SessionMetadataChange } from "./metadata/source-receipt.js";
 export declare class SessionCommitOutcomeUnknownError extends Error {
     readonly sessionId: string;
     readonly code = "session_commit_outcome_unknown";
@@ -6,4 +7,4 @@ export declare class SessionCommitOutcomeUnknownError extends Error {
 }
 export declare function syncSessionDirectory(directory: string): Promise<void>;
 /** Same session file and replacement boundary, with explicit durable-commit errors. */
-export declare function saveDurableSessionFile(sessionsDir: string, session: SessionRecord, assertCurrent?: () => void): Promise<void>;
+export declare function saveDurableSessionFile(sessionsDir: string, session: SessionRecord, assertCurrent?: () => void, metadataChange?: SessionMetadataChange): Promise<void>;

package/dist/src/sessions/durable-session-commit.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { open, rename, rm } from "node:fs/promises";
 import { join } from "node:path";
+import { currentSourceStamp, sessionSourceStamp, updateSessionMetadata } from "./metadata/store.js";
 export class SessionCommitOutcomeUnknownError extends Error {
     sessionId;
     code = "session_commit_outcome_unknown";
@@ -24,15 +25,18 @@ export async function syncSessionDirectory(directory) {
     }
 }
 /** Same session file and replacement boundary, with explicit durable-commit errors. */
-export async function saveDurableSessionFile(sessionsDir, session, assertCurrent) {
+export async function saveDurableSessionFile(sessionsDir, session, assertCurrent, metadataChange = "projection") {
     const target = join(sessionsDir, `${session.id}.json`);
+    const previousSource = metadataChange === "request-only" ? await currentSourceStamp(target) : undefined;
     const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
     let replaced = false;
+    let source;
     try {
         const handle = await open(temporary, "wx", 0o600);
         try {
             await handle.writeFile(JSON.stringify(session, null, 2), "utf8");
             await handle.sync();
+            source = sessionSourceStamp(await handle.stat({ bigint: true }));
         }
         finally {
             await handle.close();
@@ -48,4 +52,5 @@ export async function saveDurableSessionFile(sessionsDir, session, assertCurrent
             throw new SessionCommitOutcomeUnknownError(session.id, { cause: error });
         throw error;
     }
+    await updateSessionMetadata(sessionsDir, session, source, previousSource);
 }

package/dist/src/sessions/index.d.ts

@@ -5,6 +5,7 @@ import type { SessionArtifactPathInput, SessionContextEntryKind, SessionMessageG
 export type { SessionArtifactPath, SessionArtifactPathInput } from "./types.js";
 export { buildContextBuckets, buildContextWindow };
 export declare function getOrCreateSession(sessionId: string): Promise<import("./types.js").SessionRecord>;
+export declare function assertInteractiveSession(sessionId: string): Promise<void>;
 export declare function getAllSessions(): Promise<import("./types.js").SessionRecord[]>;
 export declare function listSessions(params?: {
     limit?: number;

package/dist/src/sessions/index.js

@@ -5,6 +5,9 @@ export { buildContextBuckets, buildContextWindow };
 export function getOrCreateSession(sessionId) {
     return sessionService.getOrCreateSession(sessionId);
 }
+export function assertInteractiveSession(sessionId) {
+    return sessionService.assertInteractiveSession(sessionId);
+}
 export function getAllSessions() {
     return sessionService.getAllSessions();
 }

package/dist/src/sessions/memory/source.d.ts

@@ -6,7 +6,7 @@ export type SessionMemorySettledTurn = Readonly<{
 }>;
 export type SessionMemorySourceSnapshot = Readonly<{
     sourceRevision: string;
-    /** Settled history, including assistant initiatives that must never be summarized. */
+    /** Settled history, including standalone assistant conversation units. */
     historyMessages: readonly SessionMessage[];
     turns: readonly SessionMemorySettledTurn[];
     messageReferences: readonly SessionMemoryMessageReference[];

package/dist/src/sessions/memory/source.js

@@ -1,23 +1,16 @@
 import { createHash } from "node:crypto";
 import { isAssistantInitiativeMessage } from "../assistant-initiative.js";
 export function snapshotSessionMemorySource(session) {
-    const settledTurns = collectSettledConversationTurns(session.messages);
-    const historyMessages = Object.freeze(settledTurns.flatMap(turnMessages));
-    const turns = Object.freeze(settledTurns.filter(isCompactableConversationTurn));
-    const historyReferences = historyMessages.map(createMessageReference);
-    const messageReferences = Object.freeze(historyReferences.filter(function isCompactableMessageReference(_reference, index) {
-        return !isAssistantInitiativeMessage(historyMessages[index]);
-    }));
+    const turns = collectSettledConversationTurns(session.messages);
+    const historyMessages = Object.freeze(turns.flatMap(turnMessages));
+    const messageReferences = Object.freeze(historyMessages.map(createMessageReference));
     return Object.freeze({
-        sourceRevision: fingerprint(historyReferences.map(({ fingerprint: value }) => value).join("\n")),
+        sourceRevision: fingerprint(messageReferences.map(({ fingerprint: value }) => value).join("\n")),
         historyMessages,
         turns,
         messageReferences,
     });
 }
-function isCompactableConversationTurn(turn) {
-    return !isAssistantInitiativeMessage(turn.assistant);
-}
 export function resolveCoveredTurnCount(snapshot, checkpoint) {
     if (!checkpoint) {
         return 0;

package/dist/src/sessions/metadata/projection.d.ts

@@ -0,0 +1,15 @@
+import type { SessionListItem, SessionRecord, SessionSnapshotMessage } from "../types.js";
+export type SessionMessageMetadata = Pick<SessionSnapshotMessage, "id" | "role" | "createdAt">;
+/** Derived data only. User read cursors stay in the Web UI's existing store. */
+export type SessionMetadata = {
+    version: 1;
+    source: string;
+    interactive: boolean;
+    updatedAt: string;
+    summary: SessionListItem;
+    messages: SessionMessageMetadata[];
+};
+export declare function projectSessionMetadata(session: SessionRecord, source: string): SessionMetadata;
+export declare function isCurrentSessionMetadata(value: unknown, sessionId: string, source: string): value is SessionMetadata;
+/** Stable ordering is owned here so future paging need not change callers' storage knowledge. */
+export declare function compareSessionMetadata(left: SessionMetadata, right: SessionMetadata): number;

package/dist/src/sessions/metadata/projection.js

@@ -0,0 +1,55 @@
+import { hasAutomationSessionOrigin } from "../automation-session-origin.js";
+import { clientVisibleMessages, toEpochMs, toMessageIdForUi, toSessionListItem, } from "../record/projection.js";
+export function projectSessionMetadata(session, source) {
+    return {
+        version: 1,
+        source,
+        interactive: !hasAutomationSessionOrigin(session),
+        updatedAt: session.updatedAt,
+        summary: toSessionListItem(session),
+        messages: clientVisibleMessages(session.messages).map((message) => ({
+            id: toMessageIdForUi(message.id),
+            role: message.role,
+            createdAt: toEpochMs(message.createdAt),
+        })),
+    };
+}
+function isMessageMetadata(value) {
+    if (!value)
+        return false;
+    if (typeof value.id !== "string" && typeof value.id !== "number")
+        return false;
+    if (value.role !== "user" && value.role !== "assistant")
+        return false;
+    return Number.isFinite(value.createdAt);
+}
+export function isCurrentSessionMetadata(value, sessionId, source) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    if (record.version !== 1)
+        return false;
+    if (record.source !== source)
+        return false;
+    if (typeof record.interactive !== "boolean")
+        return false;
+    if (typeof record.updatedAt !== "string")
+        return false;
+    if (record.summary?.id !== sessionId)
+        return false;
+    if (typeof record.summary.title !== "string")
+        return false;
+    if (typeof record.summary.lastMessagePreview !== "string")
+        return false;
+    if (!Number.isFinite(record.summary.createdAt))
+        return false;
+    if (!Number.isFinite(record.summary.updatedAt))
+        return false;
+    if (!Array.isArray(record.messages))
+        return false;
+    return record.messages.every(isMessageMetadata);
+}
+/** Stable ordering is owned here so future paging need not change callers' storage knowledge. */
+export function compareSessionMetadata(left, right) {
+    return right.updatedAt.localeCompare(left.updatedAt) || left.summary.id.localeCompare(right.summary.id);
+}

package/dist/src/sessions/metadata/publication.d.ts

@@ -0,0 +1,12 @@
+import type { BigIntStats } from "node:fs";
+export declare function isMissingSessionFile(error: unknown): boolean;
+export declare function sessionSourceStamp(source: BigIntStats): string;
+export declare function currentSourceStamp(path: string): Promise<string | null>;
+export declare function reportMetadataFailure(sessionId: string, error: unknown): void;
+/** Only the derived index is expendable; canonical session read failures still propagate. */
+export declare function readMetadataJson(path: string): Promise<unknown>;
+/** Serialize index publication/deletion by session, never across unrelated sessions. */
+export declare function publishSessionMetadata(path: string, operation: () => Promise<void>): Promise<void>;
+/** List backfills and the Runtime owner may run in different processes. */
+export declare function publishSessionProjection(path: string, operation: () => Promise<void>): Promise<void>;
+export declare function writeMetadataJson(target: string, value: unknown, sourcePath: string, source: string): Promise<boolean>;