@sqdr2/dsh-fusion 0.0.0-stage → 0.3.2

package/lib/types/message-source.d.ts

@@ -0,0 +1,29 @@
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'plugin:dsh-fusion': {
+            kind: 'plugin:dsh-fusion';
+        } & ContextFormed;
+        /**
+         * The producer kind this plugin wrote before it was renamed from
+         * `dsh-model-fusion`. Sessions that already exist still carry it in their
+         * durable log, so it stays a readable alias; nothing new is written under
+         * it and no migration rewrites history.
+         */
+        'plugin:dsh-model-fusion': {
+            kind: 'plugin:dsh-model-fusion';
+        } & ContextFormed;
+    }
+}
+/** The kind every new Fusion message is written under. */
+export declare const FUSION_SOURCE_KIND = "plugin:dsh-fusion";
+/** Kinds a Fusion-produced message may already carry in an existing session. */
+export declare const FUSION_SOURCE_KINDS: readonly ["plugin:dsh-fusion", "plugin:dsh-model-fusion"];
+export type FusionSourceKind = (typeof FUSION_SOURCE_KINDS)[number];
+/**
+ * Whether a message source was produced by this plugin, under either name.
+ *
+ * Read-side call sites use this guard instead of comparing one literal, so a
+ * session started before the rename keeps its context across the upgrade.
+ */
+export declare function isFusionSourceKind(kind: unknown): kind is FusionSourceKind;

package/lib/types/profile/compactor.d.ts

@@ -0,0 +1,5 @@
+import type { PairProfile, PhysicalRoute } from '../contracts.js';
+/** A separate summary model is never inferred from a provider name or enabled by default. */
+export declare function compactorChoice(value: unknown): PairProfile['compactor'];
+/** All physical routes in a frozen configuration share the same explicit spending authorization. */
+export declare function profileRoutes(profile: Pick<PairProfile, 'lead' | 'worker' | 'compactor'>): PhysicalRoute[];

package/lib/types/profile/keepalive.d.ts

@@ -0,0 +1,3 @@
+import type { PairProfile } from '../contracts.js';
+/** No provider-name heuristic can establish cache support for a DSH route. */
+export declare function keepaliveChoice(value: unknown): PairProfile['cacheKeepalive'];

package/lib/types/profile/resolve.d.ts

@@ -0,0 +1,17 @@
+import type { PairProfile, PhysicalRoute } from '../contracts.js';
+export interface PromptBundle {
+    lead: string;
+    worker: string;
+    compact: string;
+}
+export interface ResolvedProfile {
+    readonly profile: PairProfile;
+    readonly prompts: PromptBundle;
+}
+export interface ProfileCatalog {
+    readonly authorizedRoutes: readonly PhysicalRoute[];
+}
+export declare function promptDigests(prompts: PromptBundle): PairProfile['promptDigests'];
+export declare function completeProfile(raw: Record<string, unknown>, prompts: PromptBundle): PairProfile;
+export declare function resolveProfile(raw: Record<string, unknown>, prompts: PromptBundle, catalog: ProfileCatalog): ResolvedProfile;
+export declare function loadJsonObject(path: string): Record<string, unknown>;

package/lib/types/prompts.d.ts

@@ -0,0 +1,8 @@
+import type { PromptBundle } from './profile/resolve.js';
+export declare function defaultPromptDir(): string;
+export declare function loadPromptBundle(dir?: string): PromptBundle;
+export declare function loadModelPromptBundle(dir?: string): PromptBundle;
+export declare function promptManifest(dir?: string): {
+    prompts: PromptBundle;
+    digests: Readonly<Record<"lead" | "worker" | "compact", import("./contracts.js").Digest>>;
+};

package/lib/types/recovery/reconcile.d.ts

@@ -0,0 +1,28 @@
+import type { OutboxRow, SessionId } from '../contracts.js';
+import { NEEDS_REPAIR, OUTCOME_UNKNOWN } from '../errors.js';
+export type ChildPersistence = 'present' | 'missing' | 'corrupt';
+export interface RecoveryScan {
+    readonly outbox: OutboxRow;
+    readonly childPersistence: ChildPersistence;
+    readonly effectKnown: boolean | null;
+    readonly reportAlreadyRecorded: boolean;
+    readonly parentDelivered: boolean;
+}
+export type RecoveryDecision = {
+    action: 'retry-prepare';
+    child: SessionId;
+} | {
+    action: 'resume-child';
+    child: SessionId;
+} | {
+    action: 'return-stored-result';
+} | {
+    action: 'needs-repair';
+    code: typeof NEEDS_REPAIR;
+} | {
+    action: 'outcome-unknown';
+    code: typeof OUTCOME_UNKNOWN;
+} | {
+    action: 'idle';
+};
+export declare function reconcile(scan: RecoveryScan): RecoveryDecision;

package/lib/types/review/dispatch.d.ts

@@ -0,0 +1,20 @@
+import type { ReviewTicket, TaskId } from '../contracts.js';
+import type { ReviewClassification } from './protocol.js';
+import type { FusionStore } from '../task/store.js';
+/**
+ * Offline producer: persist the captured ticket and outbox row before any adapter send.
+ * The model callback may read the latest TaskState only for seq/CAS.
+ */
+export declare function persistReviewRequest(store: FusionStore, taskId: TaskId, ids: {
+    ticketId: string;
+    requestId: string;
+}, payloadRef: string): Readonly<ReviewTicket>;
+export declare function loadReviewOutboxByRequestId(store: FusionStore, taskId: TaskId, requestId: string): {
+    row: import("../contracts.js").OutboxRow;
+    ticket: Readonly<ReviewTicket>;
+};
+export declare function appendCapturedReviewResult(store: FusionStore, taskId: TaskId, ticket: Readonly<ReviewTicket>, outcome: {
+    requestId: string;
+    terminalEvidenceRef: string;
+    classification: ReviewClassification;
+}): ReturnType<FusionStore['append']>;

package/lib/types/review/protocol.d.ts

@@ -0,0 +1,51 @@
+export type ReviewStatus = 'complete' | 'incomplete' | 'not_required' | 'failed';
+export type ReviewDecision = 'approve' | 'rework' | 'needs-decision' | 'REVIEW_INCOMPLETE';
+export type ExecutionPath = 'direct' | 'forced_fusion' | 'fusion_auto';
+export type ReviewTermination = 'success' | 'truncated' | 'aborted' | 'error' | 'filtered' | 'unknown';
+export interface ReviewClassification {
+    reviewStatus: ReviewStatus;
+    decision: ReviewDecision | 'not_required';
+    protocolComplete: boolean;
+    /** True only after a substitute artifact was actually delivered. */
+    fallbackUsed: boolean;
+    /** True when a fallback or retry is still required. */
+    fallbackRequired: boolean;
+    termination: ReviewTermination;
+    reasons: readonly string[];
+}
+export interface ReviewAttemptFields {
+    artifactPass: boolean;
+    executionPath: ExecutionPath;
+    leadReviewStatus: ReviewStatus;
+    finishReason: string | null;
+    protocolComplete: boolean;
+    fallbackUsed: boolean;
+    deliveredArtifactSource: string | null;
+}
+export declare function normalizeTermination(input: {
+    finishReason?: string | null;
+    termination?: ReviewTermination;
+    completeEvidence?: boolean;
+}): ReviewTermination;
+/**
+ * Lead review is fail-closed. Only an explicit success termination plus a
+ * versioned accept/rework/needs-decision structure can complete the protocol.
+ * DIRECT skips review.
+ */
+export declare function classifyReview(input: {
+    executionPath: ExecutionPath;
+    finishReason?: string | null;
+    termination?: ReviewTermination;
+    completeEvidence?: boolean;
+    rawText?: string | null;
+    parsed?: unknown;
+}): ReviewClassification;
+/** Map classifier output onto the reducer event decision. */
+export declare function toReducerReviewDecision(classification: ReviewClassification): 'accept' | 'rework' | 'needs-decision' | 'REVIEW_INCOMPLETE';
+export declare function reviewAttemptFields(input: {
+    artifactPass: boolean;
+    executionPath: ExecutionPath;
+    classification: ReviewClassification;
+    finishReason?: string | null;
+    deliveredArtifactSource?: string | null;
+}): ReviewAttemptFields;

package/lib/types/review/ticket.d.ts

@@ -0,0 +1,32 @@
+import type { FusionEvent, OutboxRow, ReportSubject, ReviewReadinessReceipt, ReviewTicket, TaskId, WorkerReport } from '../contracts.js';
+import type { ReviewClassification } from './protocol.js';
+import type { TaskState } from '../task/state.js';
+export declare function reportSubject(taskId: TaskId, report: WorkerReport): ReportSubject;
+export declare function sameSubject(left: ReportSubject, right: ReportSubject): boolean;
+export declare function reviewReadinessReceipt(subject: ReportSubject): ReviewReadinessReceipt;
+export declare function captureTicket(ticket: ReviewTicket): Readonly<ReviewTicket>;
+export declare function createReviewTicket(state: TaskState, ids: {
+    ticketId: string;
+    requestId: string;
+}): ReviewTicket;
+export declare function reviewRequestedEvent(state: TaskState, seq: number, ids: {
+    ticketId: string;
+    requestId: string;
+}, extras?: Partial<Pick<FusionEvent, 'id' | 'revision' | 'createdAt' | 'causeId'>>): Extract<FusionEvent, {
+    type: 'review/requested';
+}>;
+export declare function reviewOutboxRow(ticket: Readonly<ReviewTicket>, payloadRef: string): OutboxRow;
+/** Callback constructor. No TaskState argument: the producer cannot rebind to the latest task. */
+export declare function resultFromCapturedTicket(ticket: Readonly<ReviewTicket>, outcome: {
+    requestId: string;
+    terminalEvidenceRef: string;
+    classification: ReviewClassification;
+}, envelope: {
+    eventId: string;
+    seq: number;
+    createdAt: string;
+}): Extract<FusionEvent, {
+    type: 'review/completed';
+}>;
+/** Call at review dispatch AND immediately before committing verified completion. */
+export declare function assertCurrentSubject(state: TaskState, ticket: ReviewTicket, actualSnapshot: ReportSubject['snapshot']): void;

package/lib/types/status.d.ts

@@ -0,0 +1,88 @@
+import type { ControlView } from './host/native-model-control.js';
+import type { PhysicalRoute, Role, TokenMeasurement, VerificationLevel } from './contracts.js';
+/** Bounded, read-only UI projection. No prompts, tool arguments or credentials. */
+export interface FusionStatus {
+    schemaVersion: 1;
+    sessionId: string;
+    selected: boolean;
+    observedAt: string;
+    task?: {
+        id: string;
+        revision: number;
+        stage: string;
+        detail: string | null;
+        /** English copies for an English DSH; optional so older records still read. */
+        stageEn?: string;
+        detailEn?: string | null;
+        attention: boolean;
+        verification: VerificationLevel;
+        workerId: string | null;
+        modelControl?: ControlView;
+        models: {
+            lead: PhysicalRoute;
+            worker: PhysicalRoute;
+            compactor: PhysicalRoute | null;
+        };
+        usage: {
+            calls: number;
+            finalCalls: number;
+            provisionalCalls: number;
+            unreportedCalls: number;
+            compactionCalls: number;
+            keepaliveCalls: number;
+            /** Known subtotals only; missing request fields never become zero totals. */
+            input: UsageSubtotal;
+            cacheRead: UsageSubtotal;
+            output: UsageSubtotal;
+            actualBilledUsd: null;
+            upstreamHttpCalls: null;
+            /** Where the tokens went: the point of Fusion is that most land on the cheaper Worker. */
+            byRole: Record<Role, RoleUsage>;
+        };
+        /** Checks frozen on the current work order; 0 means the Lead review was the only verification. */
+        automatedChecks: number | null;
+        requests: {
+            id: string;
+            role: Role;
+            purpose: string;
+            provider: string;
+            model: string;
+            outcome: string;
+            authority: 'none' | 'provisional' | 'final';
+            startedAt: string;
+        }[];
+        tools: {
+            id: string;
+            role: Role;
+            name: string;
+            state: string;
+            failed: boolean;
+            startedAt: string;
+        }[];
+        contexts: {
+            role: Role;
+            purpose: string;
+            inputTokens: number;
+            budget: number;
+            quality: TokenMeasurement['quality'];
+            admitted: boolean;
+            checkedAt: string;
+        }[];
+        pendingApprovals: number;
+        unsettledTools: number;
+        /** True while a human inspection is required before continue, model switch, or leaving Fusion. */
+        recovering?: boolean;
+        outcomeUnknown?: boolean;
+    };
+}
+export interface RoleUsage {
+    calls: number;
+    input: UsageSubtotal;
+    cacheRead: UsageSubtotal;
+    output: UsageSubtotal;
+}
+export interface UsageSubtotal {
+    knownTokens: number;
+    reportedRequests: number;
+    totalRequests: number;
+}

package/lib/types/store-migration.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Copy a database and its open sidecar files into a new directory.
+ *
+ * This is the fallback for an installation whose old and new plugin
+ * directories sit on different filesystems, where a directory move cannot
+ * work. Only the files this plugin owns are copied and removed; anything else
+ * a user left in the directory stays where it is.
+ *
+ * @param legacy - directory the previous name used.
+ * @param next - directory the current name uses.
+ * @param filename - database file name inside both directories.
+ * @returns whether the database was copied.
+ */
+export declare function copyLegacyStateFile(legacy: string, next: string, filename?: string): boolean;
+/**
+ * Carry a plugin-owned directory over to the name this release uses.
+ *
+ * A rename must keep the state it already has: the Fusion ledger holds every
+ * task, brief and artifact, so an upgrade that starts an empty store beside
+ * the old one silently loses the user's work. A directory move is tried first
+ * so a live database is never copied while another process has it open; a
+ * cross-device installation falls back to {@link copyLegacyStateFile}.
+ *
+ * @param legacy - directory the previous name used.
+ * @param next - directory the current name uses.
+ * @param filename - database file name inside both directories.
+ * @returns whether a legacy directory was adopted.
+ */
+export declare function adoptLegacyStateDirectory(legacy: string, next: string, filename?: string): boolean;

package/lib/types/task/deletion.d.ts

@@ -0,0 +1,64 @@
+import { FusionError } from '../errors.js';
+/**
+ * Whether a task record may be cleared out of the history.
+ *
+ * The question is not "what phase did this task reach" but "is anything still
+ * writing into the rows a deletion removes". A phase is a projection of the
+ * last event a running process appended; a process that was replaced (Host
+ * restart, HMR reload, crash) never appends the event that would have moved
+ * the phase on, so a finished task keeps the phase and `control.mode` of its
+ * last living moment forever. Deciding on those fields makes such a record
+ * permanently undeletable even though nothing owns it any more.
+ *
+ * So the decision is taken from evidence of a live writer, in two classes:
+ *
+ * - `live`: the Host in this process still owns an Agent, tool call, write
+ *   lease or stop for the task. This is the only authority that can see
+ *   in-process work, and it is what actually keeps a running task undeletable.
+ * - `foreign`: a durable row (native effect, approval, check invocation) left
+ *   in a pending state by a *different* process that is provably still alive.
+ *   Rows written by this process are not evidence: if the in-process authority
+ *   says nothing is live, the row is the residue of an interrupted call.
+ */
+export interface DeletionEvidence {
+    /** Why this task still owns live work in this process, or `undefined` when it owns none. */
+    readonly live: DeletionBlocker | undefined;
+    /** Pending durable rows written by another process whose pid still exists. */
+    readonly foreign: readonly string[];
+}
+/** What still holds the task, named so the panel can explain it in either language. */
+export type DeletionBlocker = 
+/** A native Agent for this task is not idle. */
+'agent'
+/** A native tool call is still in flight. */
+ | 'tool'
+/** A native job or background stop has not proved quiescence. */
+ | 'job'
+/** The task still holds (or is releasing) the workspace write lease. */
+ | 'lease'
+/** Only another, still-living process holds it. */
+ | 'foreign-process';
+export type DeletionVerdict = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly blocker: DeletionBlocker;
+    readonly detail: string;
+};
+export declare const DELETION_ALLOWED: DeletionVerdict;
+/** The one refusal the panel already knows how to translate; the blocker rides alongside it. */
+export declare class DeletionBlocked extends FusionError {
+    readonly blocker: DeletionBlocker;
+    readonly detail: string;
+    constructor(blocker: DeletionBlocker, detail: string);
+}
+/** Pure decision, so the rule is testable without a Host, a process table or a database. */
+export declare function deletionVerdict(evidence: DeletionEvidence): DeletionVerdict;
+/** Recorded owner of a durable row, when the row carries a usable pid. */
+export declare function recordedProcessId(value: unknown): number | undefined;
+/**
+ * A row is unfinished when its own state says so. The families disagree on
+ * where they record that, so each one is read through its own field and an
+ * unrecognized shape counts as settled rather than pinning the record forever.
+ */
+export declare function unfinishedDocument(family: string, value: unknown): boolean;

package/lib/types/task/reducer.d.ts

@@ -0,0 +1,6 @@
+import type { FusionEvent } from '../contracts.js';
+import type { TaskState } from './state.js';
+declare function assertControlAllowsExecution(state: TaskState): void;
+export declare function reduce(state: TaskState | undefined, event: FusionEvent): TaskState;
+export declare function reduceAll(events: readonly FusionEvent[]): TaskState;
+export { assertControlAllowsExecution };

package/lib/types/task/sqlite-store.d.ts

@@ -0,0 +1,71 @@
+import { StatusIndex } from './status-index.js';
+import type { ArtifactRef, FusionEvent, OutboxRow, OutboxState, TaskId } from '../contracts.js';
+import type { PersistedTask, TaskState } from './state.js';
+import type { ArtifactRecord, FusionStore } from './store.js';
+import type { DeletionBlocker } from './deletion.js';
+/** Durable Host backend. Every read is fresh; CAS and outbox writes share one transaction. */
+export interface DeletionAuthority {
+    /**
+     * Why this task still owns live work in this process, or `undefined` when it
+     * owns none. Only the Host can answer this: it holds the Agent, tool call,
+     * lease and stop registries. A caller without a Host passes nothing live.
+     */
+    liveReason(taskId: TaskId): DeletionBlocker | undefined;
+}
+export declare class SqliteFusionStore implements FusionStore {
+    #private;
+    readonly filename: string;
+    constructor(filename: string);
+    statusSnapshot<T>(read: (index: StatusIndex) => T, backfill?: boolean): T;
+    /** HTTP reads yield between committed batches; cancellation retains resumable progress. */
+    statusSnapshotAsync<T>(read: (index: StatusIndex) => T, signal?: AbortSignal): Promise<T>;
+    close(): void;
+    listTaskIds(): readonly TaskId[];
+    listDocumentIds(prefix: string): readonly string[];
+    load(taskId: TaskId): TaskState | undefined;
+    /**
+     * Remove one task record and everything that belongs to it.
+     *
+     * Liveness comes from `authority`, the in-process Host that owns the Agents,
+     * tool calls, leases and stops, plus durable rows a *different living* process
+     * left open. The persisted phase is deliberately not consulted: it describes
+     * where an interrupted process stopped, not whether anything still runs. See
+     * `deletion.ts` for why that distinction decides this bug.
+     */
+    deleteTask(taskId: string, authority: DeletionAuthority): void;
+    events(taskId: TaskId): readonly FusionEvent[];
+    replay(taskId: TaskId): TaskState;
+    create(event: Extract<FusionEvent, {
+        type: 'task/created';
+    }>): TaskState;
+    transact(taskId: TaskId, expectedSeq: number, mutate: (current: PersistedTask) => {
+        events?: readonly FusionEvent[];
+        outbox?: readonly OutboxRow[];
+    }): TaskState;
+    append(taskId: TaskId, expectedRevision: number, events: readonly FusionEvent[]): TaskState;
+    putArtifact(taskId: TaskId, bytes: Uint8Array, mediaType: string): ArtifactRef;
+    /** One atomic metadata update for a bounded workspace evidence batch. */
+    putArtifacts(taskId: TaskId, inputs: readonly {
+        bytes: Uint8Array;
+        mediaType: string;
+    }[]): ArtifactRef[];
+    /** Load owned evidence bytes and verify content before trusting the reference. */
+    readArtifact(taskId: TaskId, digest: string): Uint8Array;
+    readArtifacts(taskId: TaskId, digests: readonly string[]): Uint8Array[];
+    prepareOutbox(row: OutboxRow): OutboxRow;
+    advanceOutbox(taskId: TaskId, operationId: string, from: OutboxState, to: OutboxState, patch?: Partial<OutboxRow>): OutboxRow;
+    outbox(taskId: TaskId): readonly OutboxRow[];
+    artifacts(taskId: TaskId): readonly ArtifactRecord[];
+    /** Host binding / usage documents require caller-side schema validation after loading. */
+    readDocument(id: string): {
+        revision: number;
+        value: unknown;
+    } | undefined;
+    /** Compare-and-swap prevents an old Host instance overwriting a newer selection or bill. */
+    writeDocument(id: string, expectedRevision: number, value: unknown): number;
+    writeDocuments(rows: readonly {
+        id: string;
+        expectedRevision: number;
+        value: unknown;
+    }[]): number[];
+}

package/lib/types/task/state.d.ts

@@ -0,0 +1,51 @@
+import type { ControlState, Digest, ExecutionIntent, ExplorationReport, FusionEvent, LogicalApproval, OutboxRow, Phase, ReviewGate, ReviewReadinessReceipt, ReviewResultV2, ReviewTicket, RunSelection, SessionId, SnapshotId, TaskId, VerificationLevel, WorkOrder, WorkerReport, WriteLease } from '../contracts.js';
+export interface AcceptedReview {
+    readonly ticket: ReviewTicket;
+    readonly resultDigest: Digest;
+}
+export interface TaskState {
+    readonly schemaVersion: 1;
+    readonly taskId: TaskId;
+    readonly revision: number;
+    readonly seq: number;
+    readonly phase: Phase;
+    readonly parent: SessionId;
+    readonly selection: RunSelection;
+    readonly profileDigest?: Digest;
+    readonly intent?: ExecutionIntent;
+    readonly reservedChild?: SessionId;
+    readonly acceptedChild?: SessionId;
+    readonly acceptedMessageId?: string;
+    readonly currentWorkOrder?: WorkOrder;
+    readonly exploration?: ExplorationReport;
+    readonly candidateReport?: WorkerReport;
+    readonly validatedReport?: WorkerReport;
+    readonly validatedReceipt?: ReviewReadinessReceipt;
+    readonly activeReviewTicket?: ReviewTicket;
+    readonly reviewResult?: ReviewResultV2;
+    readonly reviewResultDigest?: Digest;
+    readonly acceptedReview?: AcceptedReview;
+    readonly reviewGeneration: number;
+    readonly ignoredReviewResults: readonly ReviewResultV2[];
+    readonly staleValidations: readonly {
+        readonly reportDigest: Digest;
+        readonly reason: string;
+    }[];
+    /** Candidate if unvalidated, otherwise the validated report. Compatibility projection. */
+    readonly lastReport?: WorkerReport;
+    readonly reviewGate?: ReviewGate;
+    readonly verification: VerificationLevel;
+    readonly pendingApprovalIds: readonly string[];
+    readonly pendingApprovals: Readonly<Record<string, LogicalApproval>>;
+    readonly control: ControlState;
+    readonly outcomeUnknown: boolean;
+    readonly resumePhase?: Phase;
+    readonly lease?: WriteLease;
+    readonly lastSnapshot?: SnapshotId;
+    readonly appliedEventIds: readonly string[];
+}
+export interface PersistedTask {
+    readonly state: TaskState;
+    readonly events: readonly FusionEvent[];
+    readonly outbox: readonly OutboxRow[];
+}

package/lib/types/task/status-index.d.ts

@@ -0,0 +1,28 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { FusionStatus } from '../status.js';
+type TaskStatus = NonNullable<FusionStatus['task']>;
+export declare class StatusDataError extends Error {
+}
+export declare class StatusPending extends Error {
+    readonly task: string;
+    constructor(task: string);
+}
+/** Rebuildable read model. Triggers also track writes/deletes by older plugin processes. */
+export declare class StatusIndex {
+    #private;
+    readonly db: DatabaseSync;
+    constructor(db: DatabaseSync);
+    /** Call inside the document transaction, after the source row is written. */
+    sync(id: string): void;
+    /** Each batch is its own transaction, so a legacy backfill does not monopolize the writer lock. */
+    flushBatch(task: string): boolean;
+    /** Bounded memory even for a legacy database; the surrounding transaction is atomic. */
+    flush(task?: string): void;
+    rebuild(): void;
+    read(task: string): Pick<TaskStatus, 'usage' | 'requests' | 'tools' | 'contexts' | 'unsettledTools'> & {
+        checking: boolean;
+    };
+    workerConversations(task: string): number;
+    hasConversation(task: string, session: string): boolean;
+}
+export {};

package/lib/types/task/store.d.ts

@@ -0,0 +1,48 @@
+import type { ArtifactRef, FusionEvent, OutboxRow, OutboxState, TaskId } from '../contracts.js';
+import type { PersistedTask, TaskState } from './state.js';
+export interface StoreIo {
+    existsSync(path: string): boolean;
+    mkdirSync(path: string): void;
+    readFileSync(path: string): string;
+    writeFileSync(path: string, data: string | Uint8Array): void;
+    renameSync(from: string, to: string): void;
+    rmSync(path: string): void;
+}
+export declare const nodeIo: StoreIo;
+export interface ArtifactRecord extends ArtifactRef {
+    readonly storageRef: string;
+}
+export declare const STORE_PROJECTION_VERSION = 2;
+export interface DiskSnapshot {
+    readonly projectionVersion: typeof STORE_PROJECTION_VERSION;
+    readonly checksum: string;
+    readonly persisted: PersistedTask;
+    readonly artifacts: readonly ArtifactRecord[];
+}
+/** The reducer and review producer share this port across file and transactional stores. */
+export type FusionStore = Pick<FileFusionStore, 'load' | 'replay' | 'create' | 'transact' | 'append' | 'putArtifact' | 'prepareOutbox' | 'advanceOutbox' | 'outbox' | 'artifacts'>;
+export declare class FileFusionStore {
+    #private;
+    readonly root: string;
+    readonly io: StoreIo;
+    constructor(root: string, io?: StoreIo);
+    load(taskId: TaskId): TaskState | undefined;
+    replay(taskId: TaskId): TaskState;
+    create(event: Extract<FusionEvent, {
+        type: 'task/created';
+    }>): TaskState;
+    transact(taskId: TaskId, expectedSeq: number, mutate: (current: PersistedTask) => {
+        events?: readonly FusionEvent[];
+        outbox?: readonly OutboxRow[];
+    }): TaskState;
+    append(taskId: TaskId, expectedRevision: number, events: readonly FusionEvent[]): TaskState;
+    putArtifact(taskId: TaskId, bytes: Uint8Array, mediaType: string): ArtifactRef;
+    prepareOutbox(row: OutboxRow): OutboxRow;
+    advanceOutbox(taskId: TaskId, operationId: string, from: OutboxState, to: OutboxState, patch?: Partial<OutboxRow>): OutboxRow;
+    outbox(taskId: TaskId): readonly OutboxRow[];
+    artifacts(taskId: TaskId): readonly ArtifactRecord[];
+}
+/** Validate before either backend admits a persisted execution projection. */
+export declare function decodeStoreSnapshot(raw: string, taskId: TaskId): DiskSnapshot;
+export declare function requireStorageProjectionVersion(raw: unknown): asserts raw is DiskSnapshot;
+export declare function failingRenameIo(base: StoreIo, failOnce?: boolean): StoreIo;

package/lib/types/usage/budget.d.ts

@@ -0,0 +1,27 @@
+import type { UsdDecimal } from '../contracts.js';
+export interface SpendingAuthorization {
+    schemaVersion: 1;
+    approved: boolean;
+    authorizationId: string | null;
+    currency: string;
+    maximumTotal: string | null;
+    allowedModels: readonly string[];
+    expiresAt: string | null;
+    approvedBy: string | null;
+}
+export interface Reservation {
+    readonly authorizationId: string;
+    readonly reserved: UsdDecimal;
+    readonly remaining: UsdDecimal | null;
+}
+export declare class BudgetLedger {
+    #private;
+    readonly authorization: SpendingAuthorization;
+    constructor(authorization: SpendingAuthorization);
+    assertAuthorized(model?: string): void;
+    reserve(estimatedUsd: number, model?: string): Reservation;
+    settle(reserved: Reservation, actualUsd: number | null): void;
+    get reserved(): number;
+    get spent(): number;
+}
+export declare function loadSpendingAuthorization(raw: unknown): SpendingAuthorization;