@fungi.computer/shiitake 0.1.0 → 0.3.0

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

@@ -1,8 +1,10 @@
-import type { Message, Usage, MuleResume } from "@fungi.computer/mule/effect";
+import type { Usage, MuleResume } from "@fungi.computer/mule/effect";
 import * as Schema from "effect/Schema";
 import type { ModelPreference } from "../model-preference.js";
+import type { ModelMessage } from "../../client.js";
 import type { AcceptedWork } from "../client-boundary.js";
 import type { Json } from "../../extensions.js";
+import { ShiitakeError } from "../../errors.js";
 import type { SqliteOwner } from "../contracts.js";
 import { type CompactionTrigger, type StoredSessionEntry } from "./session-entry.js";
 import type { VerifiedAgentReply } from "./agent-reply.js";
@@ -96,7 +98,7 @@ export type PreparedSessionRun = Readonly<{
         }>;
     }>;
     modelPreference: ModelPreference | null;
-    messages: readonly Message[];
+    messages: readonly ModelMessage[];
     /**
      * Context rows, not the whole lineage: the latest compaction's kept window
      * through this work, after the few older facts that still decide it.
@@ -129,11 +131,13 @@ export type AppendCompactionInput = Readonly<{
     sessionId: string;
     expectedLeafId: string;
     workId: string;
-    firstKeptEntryId: string;
+    head: string;
     summary: string;
     tokensBefore: number;
     usage: Usage;
     contextRevision: string;
+    /** The archive owner's receipt, stored in the entry that commits. */
+    receipt?: string;
     details?: Readonly<{
         readFiles: readonly string[];
         modifiedFiles: readonly string[];
@@ -188,6 +192,17 @@ export type ForkSessionAtInput = SelectSessionBranchInput;
 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;
+/** Host-owned metadata identity, interpreted by SQLite's JSON decoder only. */
+export type AdmissionIdentity = Readonly<{
+    path: string;
+    value: string;
+}>;
+/** Extract the host-selected principal without giving the engine domain grammar. */
+export declare function readAdmissionIdentity(owner: SqliteOwner, path: string, meta: Json | undefined): AdmissionIdentity;
+/** Immutable admission author check; used before every exact cancellation, including replay. */
+export declare function assertAdmissionIdentity(owner: SqliteOwner, sessionId: string, commandId: string, identity: AdmissionIdentity): void;
+/** Read just one newest admission; FIFO execution and oldest-first paging are unchanged. */
+export declare function readNewestPendingSessionCommand(owner: SqliteOwner, sessionId: string, identity?: AdmissionIdentity): StoredCommandAdmission | 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<{
@@ -208,13 +223,14 @@ export declare function hasPendingSessionSteer(owner: SqliteOwner, sessionId: st
 export declare function takePendingSessionControls(owner: SqliteOwner, sessionId: string, delivery: "steer" | "followUp", targetWorkId: string): readonly Readonly<{
     workId: string;
     requestId: string;
-    message: Message;
+    message: ModelMessage;
 }>[];
 /** 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";
+    diagnostic: string | undefined;
     enqueue: EnqueueAcceptedWork;
 }>): void;
 /** Read one stable private command admission by accepted work identity. */
@@ -249,6 +265,22 @@ export declare function deleteStoredSession(owner: SqliteOwner, input: Readonly<
     assertIdleSession: (queue: string) => void;
     recordInboxDeletion: (sessionId: string) => void;
 }>): boolean;
+/**
+ * The refusal of every read of, and write to, a Session the lineage audit
+ * found broken. Work settled for it carries `diagnostic`, a bounded form of
+ * the message that still names the Session and its reset.
+ */
+export declare class BrokenSessionError extends ShiitakeError {
+    readonly store: string;
+    readonly sessionId: string;
+    constructor(store: string, sessionId: string, message: string);
+    get diagnostic(): string;
+}
+/**
+ * Whether the lineage audit refused this Session. Settlement asks before it
+ * records anything in the Session, which it can no longer write.
+ */
+export declare function sessionLineageRefused(owner: SqliteOwner, sessionId: string): 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. */
@@ -283,25 +315,25 @@ export declare function appendSessionEntry(owner: SqliteOwner, input: AppendSess
 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.
+ * Each walk descends from the tip only while it is above a floor sequence,
+ * so a reader of recent rows never visits the history behind them. The
+ * selected walk steps only to an older parent, so it ends without
+ * deduplicating; the fork walk keeps every link for its whole-lineage check.
  */
 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     )";
+    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 ALL\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 child.sequence > ?\n          AND +parent.sequence < child.sequence\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 child.sequence > ?\n          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.
+ * One root-to-tip lineage. Its integrity is enforced where entries are
+ * written (`guardSessionLineage`), so locating it reads only its tip and its
+ * root; readers take bounded windows of it by sequence, walking down from the
+ * tip only as far as their floor.
  */
 export type SessionLineage = Readonly<{
     sessionId: string;
@@ -313,7 +345,11 @@ export type SessionLineage = Readonly<{
     newestId: string;
     newestSequence: number;
 }>;
-/** Locate the selected lineage; undefined when the Session has no leaf. */
+/**
+ * Locate a selected lineage from its two ends; undefined when the Session
+ * has no leaf. The guards make a Session's one complete root the root of
+ * every lineage in it, so neither end needs a walk.
+ */
 export declare function readSessionLineage(owner: SqliteOwner, input: ReadSelectedPathInput): SessionLineage | undefined;
 export type LineageWindowInput = Readonly<{
     /** Exclusive lower sequence bound; omitted starts at the root. */
@@ -343,15 +379,16 @@ export declare function lineageEntrySequence(owner: SqliteOwner, lineage: Sessio
 export type LineageWorkFacts = Readonly<{
     /** Works whose command entry lies on the lineage. */
     commands: ReadonlySet<string>;
-    /** Newest failure text each work recorded on the lineage. */
+    /** Newest owner-produced terminal diagnostic 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.
+ * Look up, on the lineage, only the facts of the given works. Diagnostics come
+ * only from owned terminal fields, never provider message or retry text. The works'
+ * indexes give their oldest row, and the walks stop just below it, so a page
+ * of recent works never visits older history.
  */
 export declare function readLineageWorkFacts(owner: SqliteOwner, lineage: SessionLineage, workIds: ReadonlySet<string>): LineageWorkFacts;
 /**
@@ -363,7 +400,12 @@ export declare function readLineageWorkFacts(owner: SqliteOwner, lineage: Sessio
 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.
+ * without a work, the settled context the next run starts from: the kept
+ * window through the tip, preceded only by the older facts that still decide
+ * it. Those are cancellations that withdrew a command inside the window, and
+ * earlier compactions of the active work, whose recovery runs at most once.
+ * The read is bounded by the kept window and its deciding facts, not by the
+ * history a compaction cut.
  */
 export declare function readSessionContextPath(owner: SqliteOwner, input: Readonly<{
     sessionId: string;
@@ -371,22 +413,56 @@ export declare function readSessionContextPath(owner: SqliteOwner, input: Readon
 }>): 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[];
+export declare function buildSessionContext(path: readonly StoredSessionRow[], activeWorkId?: string): readonly ModelMessage[];
 /** Prepare one accepted command against its frozen selected lineage. */
 export declare function prepareSessionRun(owner: SqliteOwner, input: PrepareSessionRunInput): PreparedSessionRun;
+/**
+ * Whether a summary whose first kept entry is `head` still fits the selected
+ * lineage (Pi Durable §6). It is stale when `head` is not on the selected
+ * lineage or sits before the current context start, where a later compaction
+ * already cut; placing it would bring cut history back. One bounded read.
+ */
+export declare function compactionHeadState(owner: SqliteOwner, input: Readonly<{
+    sessionId: string;
+    head: string;
+}>): "current" | "stale";
 /** 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. */
+}> & (Readonly<{
+    result: "nothing_to_compact";
+    /** Bounded, display-safe notice diagnostic. */
     diagnostic?: string | undefined;
-}>;
+}> | Readonly<{
+    result: "failed";
+    /** Bounded, display-safe reason for the failure. */
+    diagnostic?: string | undefined;
+    /** Known completed summary spend, even if its handoff failed. */
+    usage?: Usage | undefined;
+}> | Readonly<{
+    /** A finished summary dropped because its head moved. */
+    result: "stale";
+    /** What the dropped summary cost, so its spend is not lost. */
+    usage?: Usage | undefined;
+}> | Readonly<{
+    /** A finished summary dropped because, placed, it would not fit. */
+    result: "insufficient";
+    /** What the dropped summary cost, so its spend is not lost. */
+    usage?: Usage | 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;
+/**
+ * Place a summary selected before now (a background compaction): the head
+ * check of `compactionHeadState` and the leaf CAS in one transaction, so a
+ * head that moved after any earlier check still makes it `stale` (Pi
+ * Durable §6). A stale summary writes nothing.
+ */
+export declare function placeCompactionTransitionOwned(owner: SqliteOwner, input: AppendCompactionInput): StoredSessionRow | "stale";
 /**
  * Write one decoded admission (a prompt or a compaction request) and its one
  * durable work pointer.
@@ -397,6 +473,10 @@ export declare function appendCompactionTransitionOwned(owner: SqliteOwner, inpu
  * 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;
+/** Called only in the admission door's transaction, shared by admission and withdrawal. */
+export declare function assertSessionRequestNotWithdrawn(owner: SqliteOwner, sessionId: string, requestId: string): void;
+/** An admitted request wins; otherwise its key becomes a durable admission fence. */
+export declare function withdrawSessionRequestOwned(owner: SqliteOwner, sessionId: string, requestId: string): import("../../client.js").WithdrawResult;
 /** 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;
 /**