@wrenai/genbi 0.0.1

package/dist-server/server/db.d.ts

@@ -0,0 +1,862 @@
+import type { ArtifactKind, BlastRadius, ComponentScore, ContextFileNode, EvalRun, KnowledgeStatus, PublishScope, RuntimeSettings, SemanticMeasure, SemanticModel, SemanticRelationship, SessionEvent, SetupMode, SetupStep, SetupStatusEvent } from "./wire-types.js";
+import type { EnrichmentApprovalAttestation, EnrichmentBinding, EnrichmentMode, EnrichmentOperation, EnrichmentOperationState, EnrichmentRunStatus, ProjectIdentity, UnversionedEnrichmentBinding } from "./enrichment.js";
+import type { NativeRuntimeBinding } from "./native-dispatch-registry.js";
+export declare function newId(prefix: string): string;
+export type SessionStatus = "active" | "awaiting_clarify" | "streaming" | "awaiting_decision";
+export type TurnResultKind = "clarify" | "answer" | "refusal" | "error";
+export type SetupContextLifecyclePrefix = "none" | "discovery" | "validate" | "build";
+/**
+ * Opaque, non-secret evidence retained only while a context step is being
+ * corrected. `identityFingerprint` binds it to the canonical project and its
+ * selected/profile source declaration; no project path or credentials are
+ * persisted here.
+ */
+export interface SetupContextLifecycleEvidence {
+    readonly sessionId: string;
+    readonly identityFingerprint: string;
+    readonly completed: SetupContextLifecyclePrefix;
+}
+/** Deliberately separate from Ask's `sessions` table and wire contract. */
+export type NativeSessionStatus = "creating" | "running" | "detached" | "exited" | "stopped" | "interrupted" | "failed" | "stale";
+export type NativeSessionPurpose = "analysis" | "setup" | "context_enrichment";
+export type NativeSessionVendor = "claude" | "codex";
+export type NativeSessionScopeKind = "bootstrap" | "bound_project";
+export type NativeSetupRecoveryPhase = "connect" | "context";
+export type NativeSetupRecoveryState = "working" | "needs_input" | "needs_decision" | "retryable_failure" | "reported_complete";
+export type NativeSetupRecoveryCode = "in_progress" | "user_action_required" | "continue_or_stop" | "retryable" | "completion_reported";
+export interface NativeSessionRow {
+    readonly id: string;
+    readonly purpose: NativeSessionPurpose;
+    readonly vendor: NativeSessionVendor;
+    readonly agent: string;
+    readonly scopeKind: NativeSessionScopeKind;
+    readonly scopeId: string;
+    readonly projectIdentity: string | null;
+    readonly bindingGeneration: number | null;
+    readonly projectRevision: string | null;
+    readonly dispatchProfile: string | null;
+    readonly dispatchTarget: string | null;
+    readonly runtimeGeneration: number | null;
+    readonly status: NativeSessionStatus;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly startedAt: string | null;
+    readonly endedAt: string | null;
+    readonly exitCode: number | null;
+    readonly failure: string | null;
+}
+/**
+ * Opaque, sealed provider continuation material. The handle is never joined
+ * into a browser-facing native-session row.
+ */
+export interface NativeSessionResumeHandle {
+    readonly sessionId: string;
+    readonly provider: NativeSessionVendor;
+    readonly sealedHandle: string;
+    readonly consumedAt: string | null;
+}
+/** Durable idempotency fence for a provider continuation attempt. */
+export interface NativeSessionResumeAction {
+    readonly sourceSessionId: string;
+    readonly idempotencyKey: string;
+    readonly scopeFingerprint: string;
+    readonly resumedSessionId: string;
+}
+/**
+ * Session-scoped, typed answer material retained for native follow-up tools.
+ * `envelopeJson` is limited by the native-artifact contract to table and
+ * definition blocks; it deliberately never contains terminal bytes or a
+ * driver/subagent transcript.
+ */
+export interface NativeStructuredAnswerRow {
+    readonly id: string;
+    readonly nativeSessionId: string;
+    /** Caller retry authority only; canonical answer provenance is host-minted. */
+    readonly idempotencyKey: string;
+    readonly envelopeJson: string;
+    readonly digest: string;
+    readonly createdAt: string;
+}
+/** Retained answers are intentionally bounded without a global cleanup job. */
+export declare const MAX_NATIVE_STRUCTURED_ANSWERS_PER_SESSION = 32;
+/** Durable, redacted projection of the producer-owned Setup recovery report. */
+export interface NativeSetupRecoveryRow {
+    readonly sessionId: string;
+    readonly phase: NativeSetupRecoveryPhase;
+    readonly state: NativeSetupRecoveryState;
+    readonly code: NativeSetupRecoveryCode;
+    readonly sequence: number;
+    readonly decision: "continue_or_stop" | null;
+    /** Host-owned completion result; never inferred from a report or PTY exit. */
+    readonly completionValidated: boolean;
+    /** Monotonic compare-and-swap token for browser recovery actions. */
+    readonly version: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface SessionRow {
+    readonly id: string;
+    readonly title: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly status: SessionStatus;
+    readonly pendingQuestion: string | null;
+    /** JSON-serialized `PendingDecisionPayload`, set alongside `status: "awaiting_decision"` — mirrors `pendingQuestion`'s `awaiting_clarify` pairing. */
+    readonly pendingDecision: string | null;
+}
+/**
+ * JSON-serialized shape of `SessionRow.pendingDecision`, one variant per
+ * decision `kind` this BFF knows how to resume (see `wire-types.ts`'s
+ * `SetupDecision.kind`, which is the UI-facing side of the same checkpoint —
+ * this is the BFF-internal "how to resume" half). `POST /api/setup/decision`
+ * reads this back out to know which action to drive for a given `choiceId`.
+ */
+export type PendingDecisionPayload = {
+    readonly kind: "max_turns_continue";
+    readonly stepKey: "context";
+    /**
+     * Plan A session resume: the SDK session id the failed turn ran under (captured from a
+     * `DispatchedSessionError`, `harness/route/dispatched.ts`), if the runner reported one. When present,
+     * `POST /api/setup/decision`'s "continue" branch resumes this SAME agent-sdk conversation
+     * instead of recomposing a disk-state prompt (`composeSetupPrompt`'s `resumeFromDisk`).
+     * `undefined` for decisions recorded before this field existed, or when the runner never
+     * reported a session id at all; `null` when the runner reported the line but the SDK itself
+     * produced no session id to resume.
+     */
+    readonly sessionId?: string | null;
+    /** Server-only origin identity; both fields are required to resume. */
+    readonly sessionProvider?: string;
+    readonly sessionRunner?: string;
+    /** Preserves an adopted context turn's cwd across the decision. */
+    readonly workspaceRoot?: string;
+} | {
+    /** One explicit recovery from a terminal context turn with no successful schema discovery. */
+    readonly kind: "schema_discovery_retry";
+    readonly stepKey: "context";
+    /** Captured from the completed Mode-B turn when available, so retry can continue the same conversation. */
+    readonly sessionId?: string | null;
+    /** Server-only origin identity; both fields are required to resume. */
+    readonly sessionProvider?: string;
+    readonly sessionRunner?: string;
+    /** Carries an adopted project's dirname across the decision, when this was not the bootstrap workspace root. */
+    readonly workspaceRoot?: string;
+} | {
+    readonly kind: "name_conflict";
+    readonly projectName: string;
+    readonly sourceType: string;
+    /** The chosen connection shape, so "clean" rebuilds the same one the user picked. */
+    readonly variant?: string;
+} | {
+    readonly kind: "build_context";
+    /** Absolute path to the adopted project (see `SetupAdoptRequest.projectPath`) — reconstructed into `{workspaceRoot: dirname, projectName: basename}` for `composeSetupPrompt`/the resumed turn's `TurnRow.workspaceRoot`. */
+    readonly projectPath: string;
+    readonly sourceType: string;
+};
+export interface StoredEvent {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly seq: number;
+    readonly kind: SessionEvent["kind"];
+    readonly payload: SessionEvent;
+    readonly createdAt: string;
+    readonly turnId: string | null;
+}
+export interface TurnRow {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly question: string;
+    readonly composedInput: string | null;
+    readonly backend: string | null;
+    readonly resultKind: TurnResultKind | null;
+    readonly answerSummary: string | null;
+    readonly traceJson: string | null;
+    readonly errorMessage: string | null;
+    readonly createdAt: string;
+    /** The intent router's chosen agent id for this turn (see `classifyIntent`). NULL for rows created before intent routing existed. */
+    readonly agentId: string | null;
+    /**
+     * Marks this turn as a step of the agentic setup/connect flow (`"connect"`
+     * | `"connect_resume"`, see `server/compose.ts`'s `SetupStepKey`) rather
+     * than a normal Ask turn. NULL for every non-setup turn (the overwhelming
+     * majority). `executeTurn` (`server/turn.ts`) branches on this being
+     * non-null to dispatch via `SetupStepRunner` instead of `deps.route(...)`.
+     */
+    readonly setupStepKey: string | null;
+    /**
+     * Plan A session resume: an SDK session id this turn should resume (forwarded to
+     * `SetupStepRunOptions.resumeSessionId`, `harness/setup/runner.ts`) instead of dispatching a fresh
+     * agent-sdk conversation. Set only on a turn created by `POST /api/setup/decision`'s
+     * "continue" branch when the prior failed turn reported a resumable session id. NULL for every
+     * other turn, and for turns created before this column existed.
+     */
+    readonly resumeSessionId: string | null;
+    /** Subscription provider that created `resumeSessionId`; required before an explicit retry may reuse it. */
+    readonly resumeSessionProvider: string | null;
+    /** Canonical selected setup-runner identity that created `resumeSessionId` (for example `subscription:claude`). */
+    readonly resumeRunner: string | null;
+    /**
+     * A bounded setup workflow recovery already consumed by this turn. NULL for
+     * ordinary setup/Ask turns. "lifecycle" marks a retained-proof corrective
+     * turn; "schema_discovery" additionally prevents that bounded retry from
+     * offering the same retry or a chained max-turn continuation again.
+     */
+    readonly contextRecovery: string | null;
+    /**
+     * Per-turn override for `TurnDeps.workspaceRoot`, used ONLY by the adopt
+     * flow's `build_context` decision resolution (`POST /api/setup/decision`,
+     * `server/app.ts`): an adopted project can live anywhere on disk, not just
+     * under the BFF's configured bootstrap `workspaceRoot`, so its context-step
+     * turn carries its own root (`path.dirname(<adopted project path>)`) rather
+     * than relying on the process-wide config. `executeSetupTurn`
+     * (`server/turn.ts`) resolves `turn.workspaceRoot ?? deps.workspaceRoot` so
+     * every pre-existing create-flow turn (this column NULL) is unaffected.
+     */
+    readonly workspaceRoot: string | null;
+}
+export interface ArtifactRow {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly name: string;
+    readonly kind: ArtifactKind;
+    readonly location: string;
+    readonly verified: boolean;
+    readonly createdAt: string;
+    /**
+     * Set when the user explicitly saved this artifact to the Artifacts
+     * page (`Store.saveArtifact`), else `null`. Auto-created artifacts (Mode
+     * A/B) always start with this unset — only `listArtifacts()` filters on
+     * it; `getArtifact()` stays unfiltered so the content read-back route
+     * and the save endpoint itself can still reach an unsaved row.
+     */
+    readonly savedAt: string | null;
+    /** Native-session provenance is additive; legacy Ask artifacts leave these null. */
+    readonly nativeSessionId: string | null;
+    readonly projectIdentity: string | null;
+    readonly bindingGeneration: number | null;
+    readonly projectRevision: string | null;
+    readonly nativeVendor: NativeSessionVendor | null;
+    readonly nativeAgent: string | null;
+    readonly contentDigest: string | null;
+    /** Opaque retry key, never returned on an artifact DTO. */
+    readonly idempotencyKey: string | null;
+    /** Source provenance for a reference-backed native save; legacy/payload saves leave these null. */
+    readonly sourceAnswerId: string | null;
+}
+export interface PublicationRow {
+    readonly artifactId: string;
+    readonly link: string;
+    readonly scope: PublishScope;
+    readonly createdAt: string;
+}
+export interface EvalRunWithScores extends EvalRun {
+    readonly componentScores: readonly ComponentScore[];
+}
+export interface PriorTurn {
+    readonly question: string;
+    readonly answerSummary: string | undefined;
+}
+export interface EnrichmentRunRow {
+    readonly id: string;
+    readonly mode: EnrichmentMode;
+    readonly projectPath: string;
+    readonly projectIdentity: string;
+    readonly projectRevision: string;
+    readonly proposalId: string;
+    readonly proposalHash: string;
+    readonly status: EnrichmentRunStatus;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly validationDigest: string | null;
+    readonly buildDigest: string | null;
+    readonly errorMessage: string | null;
+    readonly bindingGeneration: number;
+    /** Monotonic optimistic-concurrency token; never use `updatedAt` as authority. */
+    readonly version: number;
+}
+export interface EnrichmentOperationRow extends EnrichmentOperation {
+    readonly decision: "accept" | "edit" | "skip" | null;
+    readonly completed: boolean;
+    readonly state: import("./enrichment.js").EnrichmentOperationState;
+    readonly attempt: number;
+    readonly leaseToken: string | null;
+    readonly leaseExpiresAt: string | null;
+    readonly idempotencyKey: string;
+}
+export interface EnrichmentEventRow {
+    readonly id: string;
+    readonly runId: string;
+    readonly kind: string;
+    readonly message: string;
+    readonly createdAt: string;
+}
+/** A single optimistic, binding-fenced metadata mutation for a run. */
+export interface EnrichmentMetadataTransition {
+    readonly runId: string;
+    readonly expectedVersion: number;
+    readonly binding: EnrichmentBinding;
+    readonly operation?: {
+        readonly id: string;
+        readonly expectedState: EnrichmentOperationState;
+        readonly expectedDecision?: "accept" | "edit" | "skip" | null;
+        readonly decision?: "accept" | "edit" | "skip";
+        readonly nextState: EnrichmentOperationState;
+    };
+    readonly status?: EnrichmentRunStatus;
+    readonly errorMessage?: string | null;
+    /** A callback-minted record; browser input can never supply this object. */
+    readonly attestation?: EnrichmentApprovalAttestation;
+    readonly event?: {
+        readonly kind: string;
+        readonly message: string;
+    };
+    /** Additional events share this exact operation/run/version transaction. */
+    readonly additionalEvents?: readonly {
+        readonly kind: string;
+        readonly message: string;
+    }[];
+}
+/** The authoritative transaction for every apply/reconcile/lease mutation. */
+export interface EnrichmentExecutionTransition {
+    readonly runId: string;
+    readonly expectedVersion: number;
+    readonly binding: EnrichmentBinding;
+    readonly operationId: string;
+    readonly expectedStates: readonly EnrichmentOperationState[];
+    readonly expectedAttempt?: number;
+    readonly expectedLeaseToken?: string | null;
+    readonly nextState: EnrichmentOperationState;
+    readonly nextAttempt?: number;
+    readonly leaseToken?: string | null;
+    readonly leaseExpiresAt?: string | null;
+    readonly completed?: boolean;
+    readonly status: EnrichmentRunStatus;
+    readonly validationDigest?: string | null;
+    readonly buildDigest?: string | null;
+    readonly errorMessage?: string | null;
+    readonly event: {
+        readonly kind: string;
+        readonly message: string;
+    };
+}
+/**
+ * Replaces a browser-edited draft only after the host has canonicalized it.
+ * This keeps the operation, proposal hash, run version, and audit event in
+ * one binding-fenced transaction.
+ */
+export interface EnrichmentEditTransition {
+    readonly runId: string;
+    readonly expectedVersion: number;
+    readonly binding: EnrichmentBinding;
+    readonly operationId: string;
+    readonly operation: EnrichmentOperation;
+    readonly proposalId: string;
+    readonly proposalHash: string;
+    readonly event: {
+        readonly kind: string;
+        readonly message: string;
+    };
+}
+export interface StoreOptions {
+    /**
+     * Test-only fault seam for the atomic context-success transaction. It runs
+     * after the named write while the SQLite transaction is still open, so a
+     * thrown error verifies that every preceding write is rolled back too.
+     */
+    readonly onContextSuccessWrite?: (phase: "after_steps" | "after_event" | "after_turn") => void;
+    /** Test-only fault seam for enrichment's run/op/event CAS transaction. */
+    readonly onEnrichmentTransitionWrite?: (phase: "after_operation" | "after_run" | "after_event") => void;
+    /** Test-only fault seam for atomic enrichment-run creation. */
+    readonly onEnrichmentCreationWrite?: (phase: "after_run" | "after_operations" | "after_event") => void;
+    /** Test-only clock so lease-expiry behavior is deterministic. */
+    readonly now?: () => Date;
+}
+export interface ContextSetupSuccessPersistence {
+    readonly sessionId: string;
+    readonly turnId: string;
+    readonly steps: SetupStep[];
+    readonly statusEvent: SetupStatusEvent;
+    readonly backend: string | null;
+    readonly answerSummary: string | null;
+    readonly traceJson: string | null;
+    readonly errorMessage: string | null;
+}
+export declare class Store {
+    private readonly db;
+    private readonly onContextSuccessWrite;
+    private readonly onEnrichmentTransitionWrite;
+    private readonly onEnrichmentCreationWrite;
+    private readonly now;
+    constructor(path: string, options?: StoreOptions);
+    /**
+     * A setup turn is executed only by the owning BFF process. If that process
+     * exits, a NULL result cannot still represent running work after restart.
+     * Convert only setup turns (never ordinary Ask turns) to a bounded, public
+     * recovery error. The old trace is deliberately discarded: it may predate
+    * the setup-boundary redaction rules and must not be replayed to the UI.
+    */
+    private reconcileOrphanedSetupTurns;
+    /**
+     * An enrichment draft is executed only by the owning BFF process. If that
+     * process exits mid-draft, a 'drafting' row cannot still represent running
+     * work after restart -- convert it to a terminal, classifiable state
+     * (mirrors `reconcileOrphanedSetupTurns` above) so the UI never shows a
+     * run stuck at "in progress" forever after a crash or redeploy.
+     */
+    private reconcileOrphanedEnrichmentRuns;
+    /** A PTY belongs to this BFF process, so it cannot survive a restart. */
+    private reconcileOrphanedNativeSessions;
+    /**
+     * Additive, idempotent migrations for columns added after a DB file may
+     * already exist on disk. `CREATE TABLE IF NOT EXISTS` above only defines
+     * the schema for a BRAND NEW file — an existing sqlite file's `turns`
+     * table predates `agent_id` and needs it added explicitly. Guarded by a
+     * `PRAGMA table_info` check so re-running this on an already-migrated (or
+     * brand-new, already-current) file is a no-op rather than an error.
+     */
+    private migrateSchema;
+    private addColumnIfMissing;
+    close(): void;
+    createSession(title: string): SessionRow;
+    createNativeSession(params: {
+        id: string;
+        purpose: NativeSessionPurpose;
+        vendor: NativeSessionVendor;
+        agent: string;
+        scopeKind: NativeSessionScopeKind;
+        scopeId: string;
+        projectIdentity?: string;
+        bindingGeneration?: number;
+        projectRevision?: string;
+        dispatchProfile?: string;
+        dispatchTarget?: string;
+        runtimeGeneration?: number;
+    }): NativeSessionRow;
+    /** Stores a sealed provider handle only; callers must never pass plaintext. */
+    saveNativeSessionResumeHandle(sessionId: string, provider: NativeSessionVendor, sealedHandle: string): void;
+    getNativeSessionResumeHandle(sessionId: string): NativeSessionResumeHandle | undefined;
+    /** Browser-safe availability bit; the opaque sealed value never leaves Store. */
+    hasAvailableNativeSessionResume(sessionId: string, provider: NativeSessionVendor): boolean;
+    getNativeSessionResumeAction(sourceSessionId: string, idempotencyKey: string): NativeSessionResumeAction | undefined;
+    invalidateNativeSessionResume(sessionId: string): void;
+    /**
+     * Atomically consumes a source conversation authority and creates its child
+     * process row. A duplicate action returns its original child, while another
+     * click can never fork the same provider conversation.
+     */
+    reserveNativeSessionResume(params: {
+        readonly sourceSessionId: string;
+        readonly idempotencyKey: string;
+        readonly scopeFingerprint: string;
+        readonly child: {
+            readonly id: string;
+            readonly purpose: NativeSessionPurpose;
+            readonly vendor: NativeSessionVendor;
+            readonly agent: string;
+            readonly scopeKind: NativeSessionScopeKind;
+            readonly scopeId: string;
+            readonly projectIdentity?: string;
+            readonly bindingGeneration?: number;
+            readonly projectRevision?: string;
+            readonly dispatchProfile?: string;
+            readonly dispatchTarget?: string;
+            readonly runtimeGeneration?: number;
+        };
+        readonly sealedHandle: string;
+    }): {
+        readonly row: NativeSessionRow;
+        readonly created: boolean;
+    } | undefined;
+    getNativeSession(id: string): NativeSessionRow | undefined;
+    createNativeStructuredAnswer(params: {
+        readonly id: string;
+        readonly nativeSessionId: string;
+        readonly idempotencyKey: string;
+        readonly envelopeJson: string;
+        readonly digest: string;
+    }): {
+        readonly row: NativeStructuredAnswerRow;
+        readonly created: boolean;
+    };
+    getNativeStructuredAnswer(id: string): NativeStructuredAnswerRow | undefined;
+    getNativeStructuredAnswerByIdempotency(nativeSessionId: string, idempotencyKey: string): NativeStructuredAnswerRow | undefined;
+    getLatestNativeStructuredAnswer(nativeSessionId: string): NativeStructuredAnswerRow | undefined;
+    listNativeSessions(): NativeSessionRow[];
+    transitionNativeSession(id: string, status: NativeSessionStatus, patch?: {
+        exitCode?: number | null;
+        failure?: string | null;
+        started?: boolean;
+        ended?: boolean;
+    }): NativeSessionRow | undefined;
+    getNativeSetupRecovery(sessionId: string): NativeSetupRecoveryRow | undefined;
+    /**
+     * Accepts one already-validated closed v1 report when its producer sequence
+     * moves forward. An identical producer replay at the current sequence is an
+     * idempotent acknowledgement; any other replay or stale report fails closed.
+     */
+    recordNativeSetupRecovery(input: {
+        readonly sessionId: string;
+        readonly phase: NativeSetupRecoveryPhase;
+        readonly state: NativeSetupRecoveryState;
+        readonly code: NativeSetupRecoveryCode;
+        readonly sequence: number;
+        readonly decision: "continue_or_stop" | null;
+        readonly completionValidated: boolean;
+    }): NativeSetupRecoveryRow | undefined;
+    /** Creates a restart-safe, browser-held action secret without persisting it raw. */
+    issueNativeSetupRecoveryAction(sessionId: string, capability: string): void;
+    /**
+     * Claims one recovery action atomically after checking its salted verifier
+     * and the browser's exact recovery version. A missing report has version 0
+     * so a BFF-restart interruption can still be retried honestly.
+     */
+    claimNativeSetupRecoveryAction(sessionId: string, capability: string, expectedVersion: number): boolean;
+    /** Releases a failed launch claim so the same browser-held secret can retry. */
+    releaseNativeSetupRecoveryAction(sessionId: string): void;
+    /** Atomically make a native row stopped and consume any durable recovery verifier. */
+    stopNativeSessionAndRevokeRecoveryAction(id: string, patch?: {
+        failure?: string | null;
+    }): NativeSessionRow | undefined;
+    listSessions(): SessionRow[];
+    getSession(id: string): SessionRow | undefined;
+    updateSessionStatus(id: string, status: SessionStatus, pendingQuestion: string | null): void;
+    /** Mirrors `updateSessionStatus`, but for the `pendingDecision` column (`status: "awaiting_decision"` checkpoints) — kept as a separate method/column so a pending clarify and a pending decision can never silently clobber each other. */
+    updateSessionDecision(id: string, status: SessionStatus, pendingDecision: string | null): void;
+    touchSession(id: string): void;
+    /**
+     * Deletes a session row along with everything scoped to it — turns, events, artifacts, and any
+     * publications for those artifacts — so no dangling rows survive the session itself. No FK
+     * cascade is configured on this schema (see SCHEMA_SQL above), so each child table needs its
+     * own explicit DELETE. Used by `resetSetup()` to remove an orphaned tracked setup session
+     * rather than merely forgetting its id.
+     */
+    deleteSession(id: string): void;
+    nextSeq(sessionId: string): number;
+    insertEvent(params: {
+        sessionId: string;
+        kind: SessionEvent["kind"];
+        payload: SessionEvent;
+        turnId: string | null;
+    }): StoredEvent;
+    listEventsForSession(sessionId: string): StoredEvent[];
+    listEventsForTurn(turnId: string): StoredEvent[];
+    createTurn(params: {
+        id: string;
+        sessionId: string;
+        question: string;
+        composedInput: string | null;
+        agentId?: string | null;
+        /** Pre-seed the work log with the turn's decision entries (Route, and Clarify for a clarify turn), so they persist and replay. */
+        traceJson?: string | null;
+        /** Marks this as a setup-wizard turn (see `TurnRow.setupStepKey`). Undefined/null for a normal Ask turn. */
+        setupStepKey?: string | null;
+        /** Plan A session resume anchor for this turn (see `TurnRow.resumeSessionId`). Undefined/null when the turn should dispatch fresh. */
+        resumeSessionId?: string | null;
+        /** Provider/runner identity that created `resumeSessionId`; retained only for an explicit same-backend retry. */
+        resumeSessionProvider?: string | null;
+        resumeRunner?: string | null;
+        /** Bounded context workflow recovery marker. */
+        contextRecovery?: "lifecycle" | "schema_discovery" | null;
+        /** Per-turn workspace root override for the adopt flow (see `TurnRow.workspaceRoot`). Undefined/null for every non-adopt turn — falls back to `TurnDeps.workspaceRoot`. */
+        workspaceRoot?: string | null;
+    }): TurnRow;
+    /**
+     * Atomically coalesces duplicate setup dispatches for one session/step.
+     * A second tab can attach to the same pending turn, but cannot create a
+     * competing mutation of the project.
+     */
+    createOrGetActiveSetupTurn(params: {
+        id: string;
+        sessionId: string;
+        question: string;
+        composedInput: string | null;
+        agentId?: string | null;
+        traceJson?: string | null;
+        setupStepKey: string;
+        resumeSessionId?: string | null;
+        resumeSessionProvider?: string | null;
+        resumeRunner?: string | null;
+        contextRecovery?: "lifecycle" | "schema_discovery" | null;
+        workspaceRoot?: string | null;
+    }): {
+        readonly turn: TurnRow;
+        readonly created: boolean;
+    };
+    getTurn(id: string): TurnRow | undefined;
+    resolveTurn(id: string, patch: {
+        backend: string | null;
+        resultKind: TurnResultKind;
+        answerSummary: string | null;
+        traceJson: string | null;
+        errorMessage: string | null;
+    }): void;
+    /**
+     * Retains the dispatcher session anchor after a completed setup turn's
+     * host-contract recovery ultimately fails. A later explicit retry can use
+     * this durable anchor; it is never sent over the REST/SSE wire.
+     */
+    setTurnResumeAnchor(id: string, anchor: {
+        readonly sessionId: string;
+        readonly provider: string;
+        readonly runner: string;
+    }): void;
+    markTurnClarify(id: string): void;
+    /** Most recent turn (any result kind) for a session — drives the Ask page's current work log. */
+    getLatestTurn(sessionId: string): TurnRow | undefined;
+    /** Resolved turns newest-first, used to recover an earlier safe setup pause after a later retry fails. */
+    listTurnsForSession(sessionId: string): TurnRow[];
+    /** D3 context composition source: last `limit` resolved (answer/refusal) turns, chronological ascending. */
+    listRecentResolvedTurns(sessionId: string, limit: number): PriorTurn[];
+    createArtifact(params: {
+        sessionId: string;
+        name: string;
+        kind: ArtifactKind;
+        location: string;
+        verified: boolean;
+    }): ArtifactRow;
+    /**
+     * Inserts a host-persisted native artifact as already Saved. The unique
+     * native-session/idempotency pair is the retry authority; callers receive
+     * the original row when another request won the race.
+     */
+    createNativeArtifact(params: {
+        id: string;
+        sessionId: string;
+        nativeSessionId: string;
+        name: string;
+        location: string;
+        projectIdentity: string;
+        bindingGeneration: number;
+        projectRevision: string;
+        vendor: NativeSessionVendor;
+        agent: string;
+        digest: string;
+        idempotencyKey: string;
+        sourceAnswerId?: string;
+    }): {
+        readonly row: ArtifactRow;
+        readonly created: boolean;
+    };
+    getNativeArtifactByIdempotency(nativeSessionId: string, idempotencyKey: string): ArtifactRow | undefined;
+    getArtifact(id: string): ArtifactRow | undefined;
+    /** Only artifacts the user explicitly saved — see `saveArtifact`. Auto-created (in-process/B) rows stay off the Artifacts page until saved. `getArtifact` stays unfiltered for direct-id lookups (content route, save route). */
+    listArtifacts(): ArtifactRow[];
+    /**
+     * Marks an artifact saved (visible via `listArtifacts()`). Idempotent: a
+     * repeat call on an already-saved artifact is a no-op that returns the
+     * existing row unchanged — it never overwrites the original `saved_at`.
+     * Returns `undefined` if the artifact doesn't exist.
+     */
+    saveArtifact(artifactId: string): ArtifactRow | undefined;
+    /**
+     * The mirror of `saveArtifact`: clears `saved_at` back to
+     * `null`, removing the artifact from `listArtifacts()` while leaving its
+     * row and envelope file untouched (Unpin is fully reversible — see
+     * `unsaveArtifactForSession`). Idempotent: a repeat call on an
+     * already-unsaved artifact is a no-op that returns the existing row
+     * unchanged. Returns `undefined` if the artifact doesn't exist.
+     */
+    unsaveArtifact(artifactId: string): ArtifactRow | undefined;
+    publishArtifact(artifactId: string, link: string, scope: PublishScope): PublicationRow;
+    getPublication(artifactId: string): PublicationRow | undefined;
+    listEvalRuns(): EvalRun[];
+    getEvalRun(id: string): EvalRunWithScores | undefined;
+    getConfigJson<T>(key: string): T | undefined;
+    setConfigJson(key: string, value: unknown): void;
+    /** Removes a config key entirely (so its getter falls back to `undefined`). Used by `resetSetup`. */
+    deleteConfig(key: string): void;
+    getRuntimeSettings(): RuntimeSettings;
+    /**
+     * Persists a user-validated runtime choice. The separate marker matters:
+     * seeded display defaults are not authority to replace environment/CLI boot
+     * routing. Only a successful PUT (or an explicit programmatic equivalent)
+     * may supersede those boot flags.
+     */
+    setRuntimeSettings(settings: RuntimeSettings, explicit?: boolean): void;
+    getRuntimeGeneration(): number;
+    getNativeRuntimeBinding(): NativeRuntimeBinding;
+    /** Atomically persist a new runtime fence and stop every incompatible live row. */
+    setRuntimeSettingsAndRevokeIncompatibleNativeSessions(settings: RuntimeSettings, explicit?: boolean): readonly string[];
+    /** Whether runtime.settings came from an explicit validated save, not seed data. */
+    hasExplicitRuntimeSettings(): boolean;
+    getSetupSteps(): SetupStep[];
+    setSetupSteps(steps: SetupStep[]): void;
+    /**
+     * Commits the context foundation's accepted lifecycle as one SQLite unit.
+     * The caller has already completed parser/artifact/compile gates; this
+     * method makes its visible success state reload-safe by never exposing a
+     * partial step/event/turn/session transition.
+     */
+    completeContextSetupSuccess(params: ContextSetupSuccessPersistence): void;
+    /**
+     * Which of the wizard's two entry paths the user picked (`SetupMode`,
+     * `POST /api/setup/mode`) — `undefined` before they've picked either,
+     * which the frontend reads as "show the create-vs-adopt choice screen"
+     * (see `GET /api/setup/mode`). Not seeded (no `SEED_*` constant): a fresh
+     * DB simply has no value here until the user chooses.
+     */
+    getSetupMode(): SetupMode | undefined;
+    setSetupMode(mode: SetupMode): void;
+    getVerifyGatePassed(): boolean;
+    setVerifyGatePassed(value: boolean): void;
+    /**
+     * The single dedicated session the setup wizard's connect/resume turns run
+     * in (get-or-create — see `POST /api/setup/connect`). Kept separate from
+     * the Ask page's session list so setup dispatches never appear there.
+     *
+     * Single-bootstrap-per-process assumption: this is a process-wide singleton
+     * (one row in config), not scoped per browser tab/user — fine for the
+     * one-BFF-per-project bootstrap flow, but would need to become session- or
+     * request-scoped if this BFF ever serves multiple concurrent setup wizards.
+     */
+    getSetupSessionId(): string | undefined;
+    setSetupSessionId(id: string): void;
+    /**
+     * The connect form's structured values (project name + source type),
+     * persisted at `POST /api/setup/connect` time so the `connect_resume` turn
+     * doesn't require the frontend to resend them, and so `executeSetupTurn`
+     * (`server/turn.ts`) has the `{root, name}` context `parseSetupTerminal`
+     * needs without having to parse it back out of `composedInput` prose.
+     */
+    getSetupConnectForm(): {
+        projectName: string;
+        sourceType: string;
+        variant?: string;
+    } | undefined;
+    setSetupConnectForm(form: {
+        projectName: string;
+        sourceType: string;
+        variant?: string;
+    }): void;
+    getSetupContextLifecycleEvidence(sessionId: string, identityFingerprint: string): SetupContextLifecycleEvidence | undefined;
+    mergeSetupContextLifecycleEvidence(input: SetupContextLifecycleEvidence): SetupContextLifecycleEvidence;
+    clearSetupContextLifecycleEvidence(): void;
+    getContextModels(): SemanticModel[];
+    getContextRelationships(): SemanticRelationship[];
+    getContextMeasures(): SemanticMeasure[];
+    getContextKnowledge(): KnowledgeStatus;
+    getContextFiles(): ContextFileNode[];
+    getBlastRadius(entityKey: string): BlastRadius | undefined;
+    getVerifiedPairs(): {
+        question: string;
+        refs: string[];
+    }[];
+    /**
+     * Persists a run BEFORE any model turn is dispatched, in a running
+     * ('drafting') state, with the bound revision and generation locked for
+     * the lifetime of the draft. This is the enrichment analogue of
+     * `postTurn` creating a turn row (`resultKind: null`) ahead of `route()`:
+     * the row -- and therefore `GET /api/context/enrichment`'s visibility of
+     * it -- exists for the entire ~minutes-long dispatch, not only after it
+     * resolves. Every exit path from that dispatch must resolve this row to a
+     * terminal status via `finalizeEnrichmentDraft` or `failEnrichmentRun`
+     * (or, after a process restart, `reconcileOrphanedEnrichmentRuns`).
+     */
+    createDraftingEnrichmentRun(params: {
+        readonly id: string;
+        readonly mode: EnrichmentMode;
+        readonly binding: EnrichmentBinding;
+    }): EnrichmentRunRow;
+    /**
+     * Transitions a 'drafting' run to 'awaiting_decision' once the draft
+     * callback has resolved AND been independently canonicalized by the host.
+     * Fenced on `status = 'drafting'` plus the CAS version, so a run that a
+     * restart already reconciled to 'failed' (or that was somehow already
+     * finalized) cannot be resurrected by a late completion.
+     */
+    finalizeEnrichmentDraft(params: {
+        readonly runId: string;
+        readonly expectedVersion: number;
+        readonly proposalId: string;
+        readonly proposalHash: string;
+        readonly operations: readonly EnrichmentOperation[];
+        readonly validationDigest?: string;
+        readonly buildDigest?: string;
+    }): boolean;
+    /**
+     * Resolves a 'drafting' run to the terminal 'failed' status -- the
+     * enrichment analogue of `resolveTurn(..., { resultKind: "error" })` in
+     * every catch clause of `executeTurn`. Called on a thrown draft/contract
+     * error, a stale post-draft binding, or (via
+     * `reconcileOrphanedEnrichmentRuns`) a BFF restart. Fenced on
+     * `status = 'drafting'` so it can never clobber a run that already
+     * finalized.
+     */
+    failEnrichmentRun(params: {
+        readonly runId: string;
+        readonly expectedVersion: number;
+        readonly message: string;
+    }): boolean;
+    createEnrichmentRun(params: {
+        readonly id: string;
+        readonly mode: EnrichmentMode;
+        readonly binding: EnrichmentBinding;
+        readonly proposalId: string;
+        readonly proposalHash: string;
+        readonly operations: readonly EnrichmentOperation[];
+        readonly validationDigest?: string;
+        readonly buildDigest?: string;
+    }): EnrichmentRunRow;
+    /**
+     * Every bind, including the same canonical directory, creates a new
+     * generation. `bindProject` (the foundation path) never has a built
+     * project's revision to offer — binding must succeed for an unbuilt
+     * project — so it activates identity alone; the stored placeholder
+     * revision is never read as a trusted value. Every consumer re-resolves
+     * the revision fresh from disk before treating a binding as current (see
+     * `currentEnrichmentBinding` in app.ts), so a placeholder here cannot
+     * leak into a fencing decision.
+     */
+    activateEnrichmentBinding(binding: UnversionedEnrichmentBinding | ProjectIdentity): EnrichmentBinding;
+    /**
+     * Advances the project binding and stops every live project-scoped native
+     * session in one transaction. The caller must immediately discard the
+     * corresponding in-memory PTY and MCP capabilities using the returned ids.
+     * Bootstrap Setup sessions deliberately remain outside this project fence.
+     */
+    activateEnrichmentBindingAndRevokeBoundNativeSessions(binding: UnversionedEnrichmentBinding | ProjectIdentity): {
+        readonly binding: EnrichmentBinding;
+        readonly revokedNativeSessionIds: readonly string[];
+    };
+    getEnrichmentBinding(): EnrichmentBinding | undefined;
+    getEnrichmentRun(id: string): EnrichmentRunRow | undefined;
+    getLatestEnrichmentRun(): EnrichmentRunRow | undefined;
+    listEnrichmentOperations(runId: string): EnrichmentOperationRow[];
+    getEnrichmentOperation(runId: string, operationId: string): EnrichmentOperationRow | undefined;
+    appendEnrichmentEvent(runId: string, kind: string, message: string): void;
+    listEnrichmentEvents(runId: string): EnrichmentEventRow[];
+    /**
+     * The authority for non-lease enrichment mutations. It checks both the
+     * caller's snapshot and the DB version before making *any* write; operation,
+     * attestation, run metadata and event then commit or roll back together.
+     */
+    transitionEnrichmentMetadata(params: EnrichmentMetadataTransition): boolean;
+    transitionEnrichmentEdit(params: EnrichmentEditTransition): boolean;
+    transitionEnrichmentExecution(params: EnrichmentExecutionTransition): boolean;
+    hasExactEnrichmentAttestation(runId: string, operationId: string): boolean;
+    private seedIfEmpty;
+    /**
+     * Restores the setup wizard to its first-run state (for the "Reset setup"
+     * action): steps back to step 1, runtime settings back to defaults, verify
+     * gate off, and the connect form + setup session cleared. Non-destructive —
+     * this only touches wizard STATE; it never deletes scaffolded project files
+     * on disk (the caller unbinds the bootstrap project separately). Leaves the
+     * seeded eval/context fixtures alone (they aren't part of the wizard).
+     *
+     * Clearing `setup.sessionId` used to leave the tracked
+     * setup session's ROW behind. `GET /api/sessions` filters the list by id
+     * against `getSetupSessionId()`, so once the id was forgotten that row
+     * matched nothing and leaked back into the Ask sidebar as an orphaned
+     * "Setup: <name>" session. Delete the row (and its turns/events/artifacts)
+     * BEFORE forgetting the id, so no orphan is ever left behind.
+     */
+    resetSetup(): readonly string[];
+    private seedEvalRuns;
+    /**
+     * Fixture data: two `BlastRadius` seeds (`customers`, `products`) and
+     * three verified Q-SQL pairs whose `refs` deliberately intersect one seed's
+     * downstream set and miss the other's, so `server/impact.ts`'s live join
+     * (see that file's doc comment) is actually exercised both ways — not
+     * vacuously "always non-empty".
+     */
+    private seedContext;
+}