@fungi.computer/shiitake 0.0.0-stage → 0.1.0

package/dist/internal/woodstock/session-store.d.ts

@@ -0,0 +1,432 @@
+import type { Message, Usage, MuleResume } from "@fungi.computer/mule/effect";
+import * as Schema from "effect/Schema";
+import type { ModelPreference } from "../model-preference.js";
+import type { AcceptedWork } from "../client-boundary.js";
+import type { Json } from "../../extensions.js";
+import type { SqliteOwner } from "../contracts.js";
+import { type CompactionTrigger, type StoredSessionEntry } from "./session-entry.js";
+import type { VerifiedAgentReply } from "./agent-reply.js";
+/**
+ * Who admitted one accepted command: a human, host or addressed caller
+ * (`user`), or one rostered extension with its correlation.
+ */
+export declare const ExtensionAdmissionOriginSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"extension">;
+    readonly extensionId: Schema.String;
+    readonly correlation: Schema.NullOr<Schema.String>;
+}>;
+export declare const AdmissionOriginSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"user">;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"extension">;
+    readonly extensionId: Schema.String;
+    readonly correlation: Schema.NullOr<Schema.String>;
+}>]>;
+/** Durable producer tag stored with every accepted command. */
+export type AdmissionOrigin = Schema.Schema.Type<typeof AdmissionOriginSchema>;
+/** One decoded row in the retained Session entry tree. */
+export type StoredSessionRow = Readonly<{
+    id: string;
+    sessionId: string;
+    parentId: string | null;
+    sequence: number;
+    state: "complete" | "streaming";
+    timestamp: number;
+    completedAt: number | null;
+    entry: StoredSessionEntry;
+}>;
+/** Persisted conversation facts; run status belongs to the Session's owner. */
+export type StoredSessionSummary = Readonly<{
+    createdAt: number;
+    updatedAt: number;
+    title: string;
+}>;
+/** One persisted conversation's stored facts, or a row that could not be read. */
+export type StoredSessionSummaryRow = (StoredSessionSummary & Readonly<{
+    kind: "session";
+    sessionId: string;
+}>) | Readonly<{
+    kind: "unavailable";
+    sessionId: string;
+}>;
+/** One page of stored conversation facts, in stable Session identity order. */
+export type StoredSessionSummaryPage = Readonly<{
+    sessions: readonly StoredSessionSummaryRow[];
+    next: string | undefined;
+}>;
+export declare function readStoredSessionFactPage(owner: SqliteOwner, after?: string): StoredSessionSummaryPage;
+/**
+ * Read one persisted Session's stored title facts without opening its host.
+ * This is the one title read: the user's title when set, otherwise the
+ * title derived from the first entered prompt.
+ */
+export declare function readStoredSessionSummary(owner: SqliteOwner, sessionId: string): StoredSessionSummary | undefined;
+export type AppendSessionEntryInput = Readonly<{
+    sessionId: string;
+    id: string;
+    entry: StoredSessionEntry;
+    state?: "complete" | "streaming";
+}>;
+export type CompleteSessionLeafInput = Readonly<{
+    sessionId: string;
+    id: string;
+    entry: Extract<StoredSessionEntry, {
+        kind: "message";
+    }>;
+}>;
+export type ReadSelectedPathInput = Readonly<{
+    sessionId: string;
+    leafId?: string;
+}>;
+export type SessionQueueHead = Readonly<{
+    state: "idle";
+}> | Readonly<{
+    state: "queued" | "running";
+    jobId: string;
+    cancellationRequested: boolean;
+}>;
+export type PrepareSessionRunInput = Readonly<{
+    sessionId: string;
+    commandFactId: string;
+}>;
+export type PreparedSessionRun = Readonly<{
+    command: StoredSessionRow & Readonly<{
+        entry: Extract<StoredSessionEntry, {
+            kind: "command";
+        }>;
+    }>;
+    modelPreference: ModelPreference | null;
+    messages: readonly Message[];
+    /**
+     * Context rows, not the whole lineage: the latest compaction's kept window
+     * through this work, after the few older facts that still decide it.
+     */
+    path: readonly StoredSessionRow[];
+    entryDelivery: "new" | "replay";
+    resume: MuleResume | undefined;
+    abnormalTerminal: "failed" | "cancelled" | undefined;
+}>;
+export type StoredSessionCommandEntry = Extract<StoredSessionEntry, {
+    kind: "command";
+}>;
+/** One stable private command admission before conversation entry. */
+export type StoredCommandAdmission = Readonly<{
+    id: string;
+    sessionId: string;
+    /** Durable acceptance-fact order; never a conversation-entry sequence. */
+    sequence: number;
+    timestamp: number;
+    entry: StoredSessionCommandEntry;
+    /** Producer that admitted this command through the accepted-command door. */
+    origin: AdmissionOrigin;
+}>;
+export type RunContract = StoredSessionCommandEntry["contract"];
+export type AppendCompactionInput = Readonly<{
+    resumesRun?: boolean;
+    trigger: CompactionTrigger;
+    /** Estimated context tokens once this compaction is the boundary. */
+    tokensAfter: number;
+    sessionId: string;
+    expectedLeafId: string;
+    workId: string;
+    firstKeptEntryId: string;
+    summary: string;
+    tokensBefore: number;
+    usage: Usage;
+    contextRevision: string;
+    details?: Readonly<{
+        readFiles: readonly string[];
+        modifiedFiles: readonly string[];
+    }>;
+}>;
+/** Private owner identities retained after one durable acceptance commit. */
+export type AcceptedCommand = Readonly<{
+    sessionId: string;
+    requestId: string;
+    commandId: string;
+}>;
+export type AcceptedSessionCommand = Readonly<{
+    accepted: AcceptedCommand;
+    command: StoredCommandAdmission;
+    delivery: "new" | "replay";
+}>;
+export type AcceptedSessionCancellation = Readonly<{
+    accepted: Readonly<{
+        commandId: string;
+        entryId: string;
+    }>;
+    delivery: "new" | "replay";
+    /** True when the target is the live Watchdog execution. */
+    active: boolean;
+}>;
+export type EnqueueAcceptedWork = (work: Readonly<{
+    jobId: string;
+    sessionId: string;
+    commandFactId: string;
+}>) => void;
+export type RecordAcceptedCancellation = (input: Readonly<{
+    jobId: string;
+    cancellationId: string;
+    onlyIfPending?: boolean;
+}>) => Readonly<{
+    status: "recorded" | "replayed" | "conflict" | "missing";
+}>;
+export type SessionTreeNode = Readonly<{
+    row: StoredSessionRow;
+    children: readonly SessionTreeNode[];
+}>;
+export type SessionTreeInput = Readonly<{
+    sessionId: string;
+}>;
+export type SelectSessionBranchInput = Readonly<{
+    sessionId: string;
+    entryId: string;
+    assertIdleSession?: (queue: string) => void;
+}>;
+export type ForkSessionAtInput = SelectSessionBranchInput;
+/** Bounded existence check; admission conditions never need transcript history. */
+export declare function hasStoredSession(owner: SqliteOwner, sessionId: string): boolean;
+/** Read one retained Session entry by its globally unique row identity. */
+export declare function readSessionEntryById(owner: SqliteOwner, id: string): StoredSessionRow | undefined;
+/** Read waiting admission facts without consulting or recreating scheduler order. */
+export declare function readPendingSessionCommands(owner: SqliteOwner, sessionId: string, limit: number, only?: "all" | "prompts"): {
+    commands: Readonly<{
+        id: string;
+        sessionId: string;
+        /** Durable acceptance-fact order; never a conversation-entry sequence. */
+        sequence: number;
+        timestamp: number;
+        entry: StoredSessionCommandEntry;
+        /** Producer that admitted this command through the accepted-command door. */
+        origin: AdmissionOrigin;
+    }>[];
+    total: number;
+};
+/** Observe one pending steer without materializing or consuming its admission. */
+export declare function hasPendingSessionSteer(owner: SqliteOwner, sessionId: string, workId: string): boolean;
+/** Materialize controls at one Mule safe point exactly once. */
+export declare function takePendingSessionControls(owner: SqliteOwner, sessionId: string, delivery: "steer" | "followUp", targetWorkId: string): readonly Readonly<{
+    workId: string;
+    requestId: string;
+    message: Message;
+}>[];
+/** Settle controls delivered by one parent run, exactly once per request. */
+export declare function settleSessionControls(owner: SqliteOwner, input: Readonly<{
+    sessionId: string;
+    parentWorkId: string;
+    outcome: "completed" | "cancelled" | "failed" | "interrupted";
+    enqueue: EnqueueAcceptedWork;
+}>): void;
+/** Read one stable private command admission by accepted work identity. */
+export declare function readSessionCommandAdmission(owner: SqliteOwner, sessionId: string, id: string): StoredCommandAdmission | undefined;
+/** Read one stable private command admission by accepted request identity. */
+export declare function readSessionCommandAdmissionByRequest(owner: SqliteOwner, sessionId: string, requestId: string): StoredCommandAdmission | undefined;
+/** Read entries correlated to one accepted work identity in Session order. */
+export declare function readSessionEntriesForWork(owner: SqliteOwner, sessionId: string, workId: string): readonly StoredSessionRow[];
+/** Read the latest retained live-retry event for one accepted work item. */
+export declare function readLatestLiveRetryForWork(owner: SqliteOwner, sessionId: string, workId: string): Readonly<{
+    event: Extract<StoredSessionEntry, {
+        kind: "live_retry";
+    }>["event"];
+    timestamp: number;
+}> | undefined;
+/** An indexed existence read: recovery errors never acknowledge successful delivery. */
+export declare function hasSuccessfulToolResult(owner: SqliteOwner, sessionId: string, workId: string, toolCallId: string): boolean;
+/** Most recent tool intent without a matching outcome for the running work. */
+export declare function readActiveToolForWork(owner: SqliteOwner, sessionId: string, workId: string): string | undefined;
+/** Reserve or replay a durable Session identity before its first prompt. */
+export declare function createStoredSession(owner: SqliteOwner, requestId: string, 
+/** Refuses a new Session under storage pressure; replays skip it. */
+admitNew: () => void): string;
+/**
+ * Permanently remove one idle Session: its entries, command admissions,
+ * creation receipt and inbox row, so a retried creation request reserves a
+ * fresh Session.
+ * Returns false when the Session does not exist.
+ */
+export declare function deleteStoredSession(owner: SqliteOwner, input: Readonly<{
+    sessionId: string;
+    assertIdleSession: (queue: string) => void;
+    recordInboxDeletion: (sessionId: string) => void;
+}>): boolean;
+/** Create the retained Session schema and private creation/admission receipts. */
+export declare function prepareSessionStore(owner: SqliteOwner): void;
+/** Read the nullable preference at exactly this selected lineage. */
+export declare function readSessionModelPreference(owner: SqliteOwner, sessionId: string): ModelPreference | null;
+/**
+ * Woodstock order of the newest model choice on the selected lineage, or null.
+ * Clients compare it with terminal orders; Woodstock assigns it no meaning.
+ */
+export declare function readLastModelChoiceSequence(owner: SqliteOwner, sessionId: string): number | null;
+/** Append a decoded preference request; no command or scheduler work is minted. */
+export declare function setSessionModelPreference(owner: SqliteOwner, sessionId: string, preference: ModelPreference | null): StoredSessionRow;
+/**
+ * Set or clear the user's Session title. Display metadata only: no entry is
+ * appended, so history, the selected leaf and recency are unchanged. Setting
+ * the same value again is a no-op write.
+ */
+export declare function setSessionTitle(owner: SqliteOwner, sessionId: string, title: string | null): void;
+/**
+ * The retained append word.
+ *
+ * Complete entries advance the selected leaf. A streaming message placeholder
+ * is durable but deliberately leaves the selected branch unchanged.
+ */
+export declare function appendSessionEntry(owner: SqliteOwner, input: AppendSessionEntryInput): StoredSessionRow;
+/**
+ * The retained leaf-finalize word.
+ *
+ * The private placeholder keeps its message identity. When the complete leaf
+ * advanced during streaming, finish after that leaf with a fresh sequence.
+ * Otherwise retain its original position. Completed history is never moved.
+ */
+export declare function completeSessionLeaf(owner: SqliteOwner, input: CompleteSessionLeafInput): StoredSessionRow;
+/** Rows one bounded lineage read decodes at once. */
+export declare const lineageRowLimit = 200;
+/**
+ * Stored bytes one model context read may decode: the retained storage
+ * plane's `LLM_CONTEXT_BYTES`, now a typed refusal rather than a silent
+ * truncation, because a truncated context would change the model's input.
+ */
+export declare const contextByteLimit: number;
+/**
+ * Root-to-tip walks carry identities only (the 2026-08-15 connection-plane
+ * law); entry data is read afterwards for exactly the rows a reader needs.
+ * The selected walk drops streaming placeholders after walking; the fork walk
+ * stops at them, as a fork copies only complete history.
+ */
+declare const lineageWalks: {
+    readonly selected: "WITH RECURSIVE branch (id, parent_id, sequence, state) AS (\n       SELECT id, parent_id, sequence, state\n         FROM session_entries\n        WHERE session_id = ? AND id = ?\n       UNION\n       SELECT parent.id, parent.parent_id, parent.sequence, parent.state\n         FROM session_entries AS parent\n         JOIN branch AS child ON parent.id = child.parent_id\n        WHERE parent.session_id = ?\n     )";
+    readonly fork: "WITH RECURSIVE branch (id, parent_id, sequence, state) AS (\n       SELECT id, parent_id, sequence, state\n         FROM session_entries\n        WHERE session_id = ? AND id = ? AND state != 'streaming'\n       UNION\n       SELECT parent.id, parent.parent_id, parent.sequence, parent.state\n         FROM session_entries AS parent\n         JOIN branch AS child ON parent.id = child.parent_id\n        WHERE parent.session_id = ? AND parent.state != 'streaming'\n     )";
+};
+/**
+ * One validated root-to-tip lineage, located in SQL without decoding its
+ * rows. Readers take bounded windows of it by sequence.
+ */
+export type SessionLineage = Readonly<{
+    sessionId: string;
+    walk: keyof typeof lineageWalks;
+    /** The entry the walk starts from: the selected leaf or a fork point. */
+    tipId: string;
+    /** The oldest row; client cursors carry it as their generation. */
+    rootId: string;
+    newestId: string;
+    newestSequence: number;
+}>;
+/** Locate the selected lineage; undefined when the Session has no leaf. */
+export declare function readSessionLineage(owner: SqliteOwner, input: ReadSelectedPathInput): SessionLineage | undefined;
+export type LineageWindowInput = Readonly<{
+    /** Exclusive lower sequence bound; omitted starts at the root. */
+    after?: number;
+    /** Exclusive upper sequence bound; omitted ends at the newest row. */
+    before?: number;
+    /** `newest` takes rows backward from `before`, `oldest` forward from `after`. */
+    from: "oldest" | "newest";
+    /** Most rows to take; the stored-byte bound may stop the window earlier. */
+    rows: number;
+}>;
+/** A contiguous run of lineage rows, oldest first, and whether more remain. */
+export type LineageWindow = Readonly<{
+    rows: readonly StoredSessionRow[];
+    more: boolean;
+}>;
+/**
+ * Read one contiguous window of a lineage, bounded by row count and by stored
+ * bytes. Row sizes are measured in SQL before any entry is decoded.
+ */
+export declare function readLineageWindow(owner: SqliteOwner, lineage: SessionLineage, input: LineageWindowInput): LineageWindow;
+/** Whether a complete row with this sequence lies on the lineage. */
+export declare function lineageHasSequence(owner: SqliteOwner, lineage: SessionLineage, rowSequence: number): boolean;
+/** The sequence of one complete row on the lineage, if it is there. */
+export declare function lineageEntrySequence(owner: SqliteOwner, lineage: SessionLineage, id: string): number | undefined;
+/** What a bounded client page needs to know about the works it shows. */
+export type LineageWorkFacts = Readonly<{
+    /** Works whose command entry lies on the lineage. */
+    commands: ReadonlySet<string>;
+    /** Newest failure text each work recorded on the lineage. */
+    diagnostics: ReadonlyMap<string, string>;
+    /** Host metadata of the cancellation that ended each work. */
+    cancellations: ReadonlyMap<string, Json>;
+}>;
+/**
+ * Look up, across the whole lineage, only the facts of the given works. A
+ * diagnostic is the newest of an assistant error, a final retry error or a
+ * work terminal's diagnostic; only that text is extracted, never the message.
+ */
+export declare function readLineageWorkFacts(owner: SqliteOwner, lineage: SessionLineage, workIds: ReadonlySet<string>): LineageWorkFacts;
+/**
+ * Read one complete selected root-to-leaf branch, decoding every row.
+ *
+ * Heap grows with the whole lineage, so no production reader uses this:
+ * clients page with `readLineageWindow`, runs read `readSessionContextPath`.
+ */
+export declare function readSelectedPath(owner: SqliteOwner, input: ReadSelectedPathInput): readonly StoredSessionRow[];
+/**
+ * Context rows of the current selected lineage for one accepted work, or,
+ * without a work, the settled context the next run starts from.
+ */
+export declare function readSessionContextPath(owner: SqliteOwner, input: Readonly<{
+    sessionId: string;
+    workId?: string;
+}>): readonly StoredSessionRow[];
+/** Work cancelled before delivery stays in history but never enters model context. */
+export declare function withdrawnWorkIds(path: readonly StoredSessionRow[]): ReadonlySet<string>;
+export declare function buildSessionContext(path: readonly StoredSessionRow[], activeWorkId?: string): readonly Message[];
+/** Prepare one accepted command against its frozen selected lineage. */
+export declare function prepareSessionRun(owner: SqliteOwner, input: PrepareSessionRunInput): PreparedSessionRun;
+/** One compaction that committed nothing, recorded so clients show the result. */
+export type CompactionNoticeInput = Readonly<{
+    sessionId: string;
+    workId: string;
+    trigger: CompactionTrigger;
+    result: "nothing_to_compact" | "failed";
+    /** Bounded, display-safe reason; only a failure carries one. */
+    diagnostic?: string | undefined;
+}>;
+/** Append one compaction notice on the selected lineage. */
+export declare function appendCompactionNoticeOwned(owner: SqliteOwner, input: CompactionNoticeInput): StoredSessionRow;
+/** Atomically append one compaction transition using the selected leaf CAS. */
+export declare function appendCompactionTransitionOwned(owner: SqliteOwner, input: AppendCompactionInput): StoredSessionRow;
+/**
+ * Write one decoded admission (a prompt or a compaction request) and its one
+ * durable work pointer.
+ *
+ * Only the accepted-command door (`internal/admission-door.ts`) calls this,
+ * inside its owner transaction. A retried request id replays only when the
+ * whole canonical command (kind, delivery, text, images, host metadata,
+ * verified reply and origin) is unchanged.
+ */
+export declare function acceptSessionCommandOwned(owner: SqliteOwner, sessionId: string, input: AcceptedWork, meta: Json | undefined, origin: AdmissionOrigin, contract: RunContract, enqueue: EnqueueAcceptedWork | undefined, targetWorkId?: string, reply?: VerifiedAgentReply): AcceptedSessionCommand;
+/** Cancel the running turn and every waiting admission in one owner transaction. */
+export declare function acceptSessionAbort(owner: SqliteOwner, sessionId: string, readQueueHead: () => SessionQueueHead, record: RecordAcceptedCancellation, meta?: Json): AcceptedSessionCancellation | undefined;
+/**
+ * Atomically resolve one accepted request and delegate queued work to
+ * Watchdog. `undefined` means it is too late (or the id names nothing): the
+ * command is unknown, has already settled, or, for an `onlyIfPending` cancel,
+ * has already started. Nothing is written in that case.
+ */
+export declare function acceptSessionCancellation(owner: SqliteOwner, sessionId: string, commandId: string, readQueueHead: () => SessionQueueHead, record: RecordAcceptedCancellation, onlyIfPending?: boolean, meta?: Json): AcceptedSessionCancellation | undefined;
+/** Move the durable leaf to an existing entry in the same Session. */
+export declare function selectSessionBranch(owner: SqliteOwner, input: SelectSessionBranchInput): void;
+/**
+ * Record one operator or party line on an idle Session. The request id is
+ * the idempotency key: a replay of the same line is `false`, another line
+ * under the same id is a conflict.
+ */
+export declare function appendOperatorEntry(owner: SqliteOwner, input: Readonly<{
+    sessionId: string;
+    requestId: string;
+    author: "operator" | "party";
+    meta: Json | undefined;
+    text: string;
+    assertIdleSession: (queue: string) => void;
+}>): boolean;
+/** Read the complete retained Session tree, including orphan roots. */
+export declare function readSessionTree(owner: SqliteOwner, input: SessionTreeInput): readonly SessionTreeNode[];
+/** Fork exactly one Session root-to-entry lineage with fresh row identities. */
+export declare function forkSessionAt(owner: SqliteOwner, input: ForkSessionAtInput): string;
+/** Read document state from the selected transcript branch. */
+export declare function readSessionDocument(owner: SqliteOwner, sessionId: string, extensionId: string, name: string): string | undefined;
+/** Append a document snapshot under the same transaction as its producing hook. */
+export declare function writeSessionDocument(owner: SqliteOwner, sessionId: string, extensionId: string, name: string, valueJson: string): void;
+export {};