@full-self-browsing/lattice 1.3.0-rc.0 → 1.4.0

package/dist/index.d.ts

@@ -1,6 +1,15 @@
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region src/policy/policy.d.ts
+type GatewayMetadataValue = string | number | boolean | null | readonly GatewayMetadataValue[] | {
+  readonly [key: string]: GatewayMetadataValue;
+};
+interface GatewayPolicy {
+  readonly routeTags?: readonly string[];
+  readonly providerPreferences?: readonly string[];
+  readonly metadata?: Record<string, GatewayMetadataValue>;
+  readonly allowFallbacks?: boolean;
+}
 interface PolicySpec {
   readonly maxCostUsd?: number;
   readonly latency?: "interactive" | "batch";
@@ -10,6 +19,8 @@ interface PolicySpec {
   readonly noUpload?: boolean;
   readonly noPublicUrl?: boolean;
   readonly noLogging?: boolean;
+  readonly stream?: boolean;
+  readonly gateway?: GatewayPolicy;
   readonly metadata?: Record<string, unknown>;
 }
 //#endregion
@@ -115,7 +126,7 @@ interface TracerLike {
   readonly span?: <T>(name: string, fn: () => T | Promise<T>, attributes?: Record<string, unknown>) => T | Promise<T>;
   readonly event?: (name: string, attributes?: Record<string, unknown>) => void;
 }
-type RunEventKind = "run.start" | "artifact.ingested" | "context.packed" | "router.candidates" | "stage.start" | "stage.complete" | "provider.attempt" | "fallback.activated" | "validation.complete" | "validation.failed" | "artifact.created" | "run.complete" | "run.failed" | "tool.call" | "replay.offline" | "replay.live" | "step.transition" | "recovery.start" | "recovery.complete" | "recovery.failed";
+type RunEventKind = "run.start" | "artifact.ingested" | "context.packed" | "router.candidates" | "stage.start" | "stage.complete" | "provider.attempt" | "stream.start" | "stream.complete" | "stream.failed" | "fallback.activated" | "validation.complete" | "validation.failed" | "artifact.created" | "run.complete" | "run.failed" | "tool.call" | "replay.offline" | "replay.live" | "step.transition" | "recovery.start" | "recovery.complete" | "recovery.failed" | "capabilities.negotiation.fallback";
 interface RunEvent {
   readonly kind: RunEventKind;
   readonly timestamp: string;
@@ -373,6 +384,137 @@ type TripwireResult = {
  */
 declare function evaluateTripwires(output: unknown, invariants: readonly InvariantDeclaration[], detectors?: readonly PiiDetector[]): Promise<TripwireResult>;
 //#endregion
+//#region src/capabilities/profile.d.ts
+/**
+ * Closed enum of the 8 Lattice transport adapters (D-06). Adding a new
+ * adapter is a typed breaking change. Phase 34 quirk dispatch reads this
+ * field.
+ */
+type CapabilityAdapter = "openrouter" | "anthropic" | "openai" | "openai-compat" | "xai" | "gemini" | "lm-studio" | "litellm";
+/**
+ * Closed enum of the 5 training-lineage buckets (D-14). Receipt v1.2
+ * (Phase 38) carries this value verbatim via the `modelClass` field.
+ * Stable across model patches — gpt-4o-2024-05-13 and gpt-4o-2024-08-06
+ * share a trainingClass so receipts remain comparable across rebuilds.
+ */
+type TrainingClass = "frontier_rlhf" | "mid_tier_rlhf" | "open_weight_instruct" | "open_weight_base" | "local_quantized";
+/**
+ * Closed enum of the 5 recommended prompt-tuning buckets (research open
+ * question 2). DISTINCT from `TrainingClass`: `reasoning` is orthogonal
+ * to lineage (a frontier RLHF model with hidden_cot routes to the
+ * `reasoning` strategy bucket); `local` is the granularity boundary
+ * for the deployed-locally strategy bucket (vs the `local_quantized`
+ * lineage signal). Phase 35 prompt-scaffold dispatch reads this field.
+ */
+type RecommendedPromptStrategy = "frontier" | "mid_tier" | "open_weight" | "reasoning" | "local";
+/**
+ * Closed enum of the 7 known model-class output-shape failure modes at
+ * v1.3.0 (D-12). Adding a member in v1.4+ is an intentional typed
+ * breaking change — Phase 36 sanitizer dispatch enforces exhaustiveness
+ * via a `_exhaustive: never` switch (see test-d/capabilities.test-d.ts).
+ */
+type KnownFailureMode = "internal_envelope_leak" | "reasoning_tag_leak" | "system_prompt_echo" | "template_artifact_leak" | "hallucinated_tool_name" | "malformed_tool_arguments" | "premature_termination";
+/**
+ * Closed enum of the 5 reasoning-surface shapes a model exposes. Drives
+ * the Phase 36 sanitizer's choice of leak-cleanup pass (e.g., `<think>`
+ * tag stripping for `inlined_tags`).
+ */
+type ReasoningSurface = "none" | "hidden_cot" | "inlined_tags" | "interleaved_thinking" | "streamed_reasoning";
+/**
+ * Closed enum of the 5 tool-call surface shapes a model exposes. Drives
+ * the Phase 37 tool-call validator's choice of arguments parser.
+ */
+type ToolCallSurface = "none" | "native_strict" | "native_lenient" | "json_only" | "text_only";
+type ModelCapabilityProfilePricingKey = "prompt" | "completion" | "image" | "audio" | "web_search" | "internal_reasoning" | "input_cache_read" | "input_cache_write";
+type ModelCapabilityProfilePricing = Partial<Record<ModelCapabilityProfilePricingKey, string>>;
+type ModelCapabilityProfileModality = "text" | "image" | "audio" | "video" | "file" | "embeddings";
+/**
+ * Phase 33 — D-05 / D-08 — Capability profile for one (adapter, model)
+ * pair. Sibling to `ModelCapability`, not a replacement. Built-time baked
+ * via the OpenRouter snapshot generator (Phase 33-03) plus hand-edited
+ * supplemental static profiles (Phase 33-04).
+ *
+ * Canonical key: `${adapter}:${modelId}` — one profile per (adapter,
+ * model) pair. `openrouter:openai/gpt-oss-120b` and `openai:gpt-oss-120b`
+ * are two distinct entries with the same `originFamily: "openai"`.
+ */
+interface ModelCapabilityProfile {
+  /**
+   * The model identifier as the adapter sees it. For OpenRouter this is
+   * the `vendor/model` shape (e.g., `openai/gpt-oss-120b`); for direct
+   * adapters this is the provider's native id (e.g., `claude-opus-4`).
+   * Combined with `adapter` to form the canonical lookup key `${adapter}:${id}` (D-08).
+   */
+  readonly id: string;
+  /**
+   * The Lattice transport adapter that ships this profile (D-05 /
+   * D-06). Phase 34 adapter-quirk dispatch reads this field. Closed
+   * union of 8 values.
+   */
+  readonly adapter: CapabilityAdapter;
+  /**
+   * The model creator (D-07). Open extensible string — new orgs emerge
+   * frequently and should not break the type. Examples: `openai`,
+   * `anthropic`, `meta`, `mistral`, `google`, `xai`, `deepseek`, `qwen`.
+   * Phase 35 prompt-scaffold dispatch falls back to
+   * `recommendedPromptStrategy` for unknown originFamily values.
+   */
+  readonly originFamily: string;
+  /**
+   * Training-lineage classification (D-14). Receipt v1.2 `modelClass`
+   * (Phase 38) carries this value verbatim. Drives the failure-mode
+   * default set in the classifier.
+   */
+  readonly trainingClass: TrainingClass;
+  /**
+   * Shape of the model's reasoning output. Drives the Phase 36
+   * sanitizer's reasoning-leak cleanup pass.
+   */
+  readonly reasoningSurface: ReasoningSurface;
+  /**
+   * Shape of the model's tool-call output. Drives the Phase 37
+   * tool-call validator's arguments parser.
+   */
+  readonly toolCallSurface: ToolCallSurface;
+  /**
+   * The actual context window the adapter will accept on a request, in
+   * tokens. For OpenRouter this is `top_provider.context_length ?? context_length`
+   * (Phase 33 Pitfall 2) — what OpenRouter routing actually offers, not
+   * the model card's aspirational maximum.
+   */
+  readonly contextWindow: number;
+  readonly pricing?: ModelCapabilityProfilePricing;
+  readonly inputModalities?: readonly ModelCapabilityProfileModality[];
+  readonly outputModalities?: readonly ModelCapabilityProfileModality[];
+  readonly supportedParameters?: readonly string[];
+  /**
+   * Failure modes this model class is known to exhibit (D-14). Class-
+   * derived defaults plus per-family overrides. Phase 36 sanitizer
+   * dispatch exhaustively switches on each entry.
+   */
+  readonly knownFailureModes: readonly KnownFailureMode[];
+  /**
+   * Recommended prompt-tuning bucket (research open question 2). Phase
+   * 35 prompt-scaffold dispatch reads this field. Distinct from
+   * `trainingClass` — see `RecommendedPromptStrategy` JSDoc.
+   */
+  readonly recommendedPromptStrategy: RecommendedPromptStrategy;
+}
+/**
+ * Frozen list of every `KnownFailureMode` member. Useful for exhaustive
+ * iteration in downstream tests and Phase 36 sanitizer registration.
+ * Adding a new mode requires updating this array AND the
+ * `KnownFailureMode` union AND the Phase 36 exhaustive switch — the
+ * `satisfies` clause enforces array-vs-union parity at compile time.
+ */
+declare const ALL_KNOWN_FAILURE_MODES: readonly ["internal_envelope_leak", "reasoning_tag_leak", "system_prompt_echo", "template_artifact_leak", "hallucinated_tool_name", "malformed_tool_arguments", "premature_termination"];
+/**
+ * Frozen list of every `TrainingClass` member. Useful for exhaustive
+ * iteration when constructing the failure-mode defaults table (D-14)
+ * and for Phase 38 receipt-class enumeration.
+ */
+declare const ALL_TRAINING_CLASSES: readonly ["frontier_rlhf", "mid_tier_rlhf", "open_weight_instruct", "open_weight_base", "local_quantized"];
+//#endregion
 //#region src/outputs/contracts.d.ts
 type TextOutputContract = "text";
 interface CitationRef {
@@ -469,1478 +611,2322 @@ interface ContextSummarizer {
   }): Promise<readonly ArtifactRef[]> | readonly ArtifactRef[];
 }
 //#endregion
-//#region src/providers/provider.d.ts
-type CapabilityModality = "text" | "json" | "image" | "audio" | "video" | "document" | "file" | "url" | "tool";
-type ProviderTransportMode = "inline" | "json" | "url" | "base64" | "provider-upload" | "file-id" | "extracted-text" | "transcript";
-type ProviderLatencyClass = "interactive" | "batch";
-interface ProviderPricingHint {
-  /** @deprecated prefer `inputPer1kTokens` — kept for backward compatibility */
-  readonly inputCostPer1M?: number;
-  /** @deprecated prefer `outputPer1kTokens` — kept for backward compatibility */
-  readonly outputCostPer1M?: number;
-  /** Per-1000-prompt-token cost in USD. Preferred field for Phase 7+ pricing. */
-  readonly inputPer1kTokens?: number;
-  /** Per-1000-completion-token cost in USD. Preferred field for Phase 7+ pricing. */
-  readonly outputPer1kTokens?: number;
-}
+//#region src/runtime/survivability.d.ts
 /**
- * Normalized per-run usage at the result layer.
+ * MV3-survivability adapter contract -- Phase 5 (FSB v0.10.0-attempt-2).
  *
- * `costUsd` is `number | null` (not optional, not `0`) so downstream
- * consumers can distinguish "free" (`0`) from "unmeasured" (`null`) when
- * provider pricing is unknown — see 07-CONTEXT.md "Cost Normalization & Usage".
+ * This module is a SIBLING of create-ai.ts (the Lattice runtime facade) and
+ * a SIBLING of contract/bands.ts (the hook pipeline factory) and
+ * contract/checkpoint.ts (the per-step receipt hook). It does NOT modify
+ * any of them; the SurvivabilityAdapter contract is composed from those
+ * surfaces by the consumer (FSB's lattice-runtime-adapter.js in Plan 05-05).
  *
- * Distinct from `UsageRecord` on `ProviderAttemptRecord`: `UsageRecord`
- * is the per-attempt record, `Usage` is the per-run normalized shape
- * surfaced on `RunSuccess` / `RunFailure`.
+ * What is the survivability problem?
+ *   Some host runtimes can evict the execution context mid-flow with no
+ *   synchronous shutdown signal:
+ *     - Chrome MV3 service workers: evicted after 30s silence OR 5min idle.
+ *     - Cloudflare Workers: evicted at end of each request unless waitUntil.
+ *     - AWS Lambda: process freeze + thaw across invocations.
+ *   Lattice's existing runtime (create-ai.ts) assumes the process stays
+ *   live for the duration of a run. The SurvivabilityAdapter contract is
+ *   the seam where a host runtime tells Lattice "here is how to serialize
+ *   my state, here is how to deserialize it back, here is how to resume
+ *   work after I get evicted and recreated."
+ *
+ * What this module SHIPS:
+ *   - SurvivabilityAdapter<TState> interface (4 methods)
+ *   - SerializedSnapshot type (string-encodable opaque envelope)
+ *   - EvictionHook<TState> type (pre-eviction callback signature)
+ *   - ResumePolicy literal-union (post-restore reconstruction verdict)
+ *   - UnsubscribeFn type
+ *   - createNoopSurvivabilityAdapter() reference implementation
+ *
+ * What this module DOES NOT ship:
+ *   - chrome.storage.session integration (FSB-side; Plan 05-05).
+ *   - offscreen-document message bus (FSB-side; Plan 05-04).
+ *   - Auto-wiring into create-ai.ts runtime (deferred indefinitely; the
+ *     contract is consumer-controlled).
+ *   - Mid-API-request / mid-tool-dispatch recovery dispatcher (CONSERVATIVE
+ *     recovery wiring is deferred to a follow-on FSB milestone per
+ *     CONTEXT.md D-22; only the ResumePolicy taxonomy lands here).
+ *
+ * Composition conventions (NOT enforced; documented for callers):
+ *   D-09: onEviction hooks SHOULD register in BAND.SAFETY band on the
+ *         caller's HookPipeline so they run FIRST per Phase 2 priority
+ *         ordering. This module does NOT auto-register; it ships the
+ *         contract only.
+ *   D-10: serialize(state) MAY include the latest checkpoint receipt
+ *         envelope (Phase 3 createCheckpointHook output) inside the
+ *         SerializedSnapshot.payload; deserialize() reconstructs session
+ *         identifiers from the v1.1 receipt body's step-marker fields
+ *         (stepName, stepIndex, parentStepName, previousStepName,
+ *         sessionId, timestamp). The payload is opaque to Lattice -- the
+ *         host runtime defines the shape.
+ *
+ * ResumePolicy taxonomy (CD-E resolution per attempt-1 02-04-PLAN.md):
+ *   - SAFE: the snapshot was captured at a safe boundary (BEFORE_ITERATION
+ *     or BEFORE_NEXT_ITERATION_SCHEDULE step markers) and can be replayed
+ *     deterministically. The host runtime may re-arm the loop.
+ *   - RECOVERY_AMBIGUOUS: the snapshot was captured during a tool dispatch
+ *     where re-execution risk is non-zero (file write, network POST without
+ *     Idempotency-Key, side-effecting browser action). Host should escalate
+ *     to the user before deciding.
+ *   - ON_ERROR_SW_EVICTION_MID_REQUEST: the eviction happened mid-API-call
+ *     (the provider request was in flight). 6 of 7 FSB providers do NOT
+ *     document Idempotency-Key headers; replay risks duplicate charges +
+ *     duplicate responses. Host should treat the run as failed and surface
+ *     the error to the user.
+ *   - ON_ERROR_SW_EVICTION_MID_TOOL_DISPATCH: the eviction happened mid-
+ *     tool-dispatch (a browser action was in progress). Re-execution risk
+ *     is similar to mid-API-call but lands in a different recovery branch
+ *     (the host may inspect the page state before deciding).
+ *
+ * SerializedSnapshot is intentionally opaque + string-encodable. The
+ * host runtime defines the payload shape; Lattice's only requirement
+ * is that serialize() followed by deserialize() round-trips the state.
+ *
+ * Ed25519 receipt envelope contract (carries forward from Phase 1-3):
+ *   Callers MAY embed a v1.1 ReceiptEnvelope inside SerializedSnapshot.payload
+ *   for signed checkpoint round-trip. verifyReceipt against the embedded
+ *   envelope MUST return result.ok === true after a serialize -> deserialize
+ *   cycle (Test 12). This validates that JSON.stringify + JSON.parse over
+ *   the envelope preserves the JCS-canonical body bytes used by DSSE PAE.
+ *
+ * Threat model (Phase 5 CONTEXT.md security block):
+ *   - PII via serialized state: callers MUST ensure SerializedSnapshot.payload
+ *     contains only stable identifiers + user-controlled state the user has
+ *     already consented to persist. Mirrors Phase 2 D-04 receipt-body contract
+ *     (step-marker fields are stable identifiers, not free-form user input).
+ *   - Snapshot tampering: the noop adapter does NOT sign the snapshot.
+ *     Callers that need cryptographic integrity SHOULD embed a signed
+ *     ReceiptEnvelope inside the payload + verify it on deserialize.
+ *     Phase 5 ships the contract; signature wrapping is a follow-on.
+ *
+ * Vocabulary separation (carries forward Phase 2 D-12 + Phase 3 D-02):
+ *   ResumePolicy is the survivability vocabulary -- separate from
+ *   RunEventKind (tracing) AND separate from HookLifecycleEvent (bands).
+ *   The three vocabularies meet only when a host runtime composes them.
  */
-interface Usage {
-  readonly promptTokens: number;
-  readonly completionTokens: number;
-  readonly costUsd: number | null;
-}
-interface ProviderDataPolicyHints {
-  readonly privacy: readonly ("standard" | "sensitive" | "restricted")[];
-  readonly uploadRetention?: "none" | "ephemeral" | "provider-default";
-  readonly supportsNoLogging?: boolean;
-  readonly supportsNoTraining?: boolean;
-}
-interface ModelCapability {
-  readonly providerId: string;
-  readonly modelId: string;
-  readonly inputModalities: readonly CapabilityModality[];
-  readonly outputModalities: readonly CapabilityModality[];
-  readonly fileTransport: readonly ProviderTransportMode[];
-  readonly contextWindow: number;
-  readonly structuredOutput: boolean;
-  readonly toolUse: boolean;
-  readonly streaming: boolean;
-  readonly pricing?: ProviderPricingHint;
-  readonly latency: ProviderLatencyClass;
-  readonly dataPolicy: ProviderDataPolicyHints;
-  readonly available?: boolean;
+/**
+ * String-encodable opaque snapshot. The host runtime defines the payload
+ * shape; Lattice's only requirement is that serialize() followed by
+ * deserialize() round-trips the original state object.
+ *
+ * Why string-encodable? MV3's chrome.storage.session and most cross-process
+ * storage layers accept structured-clone-safe values. JSON-string payloads
+ * are the lowest-common-denominator that survives MV3 SW eviction +
+ * Cloudflare Worker freeze + Lambda thaw. Callers MAY use a richer payload
+ * shape (Uint8Array, Blob) IF the host runtime supports it; the contract
+ * does not constrain payload format beyond "deserialize round-trips it".
+ */
+interface SerializedSnapshot {
+  readonly kind: "survivability-snapshot";
+  readonly version: "lattice-survivability/v1";
+  readonly payload: string;
+  readonly capturedAt: string;
 }
-interface ProviderRef {
+/**
+ * Pre-eviction callback. The host runtime CAN attempt to call this hook
+ * before the execution context is evicted, but MAY NOT be able to in
+ * every case (MV3 eviction has no synchronous signal -- the SW just
+ * stops). Callers should treat onEviction as best-effort: useful for
+ * gathering final state when the eviction is announced (e.g., user-
+ * initiated stop) but not load-bearing for involuntary eviction.
+ *
+ * The hook receives the current TState by reference. Mutations on the
+ * hook side leak to the caller's state -- this is deliberate (the hook
+ * is the LAST chance to update state before eviction). Callers who want
+ * structuredClone semantics SHOULD wrap state in their own freeze layer.
+ */
+type EvictionHook<TState> = (state: TState) => void | Promise<void>;
+/**
+ * Return value of onEviction(); calling unsubscribes the hook.
+ *
+ * Idempotent -- calling twice has the same effect as calling once.
+ */
+type UnsubscribeFn = () => void;
+/**
+ * Resume policy taxonomy. The host runtime calls adapter.resume(snapshot)
+ * after eviction + restore; the returned policy tells the host runtime
+ * how to react.
+ *
+ * The 4 literal members carry forward from FSB v0.10.0-attempt-1's
+ * 02-04-PLAN.md CONSERVATIVE recovery dispatch (preserved at
+ * .planning/milestones/v0.10.0-attempt-1-pre-pivot/02-state-inspectability-
+ * carve-out/02-04-PLAN.md). Per CONTEXT.md CD-E this is the locked union.
+ */
+type ResumePolicy = "SAFE" | "RECOVERY_AMBIGUOUS" | "ON_ERROR_SW_EVICTION_MID_REQUEST" | "ON_ERROR_SW_EVICTION_MID_TOOL_DISPATCH";
+/**
+ * The SurvivabilityAdapter contract. Host runtimes implement this; Lattice
+ * runs against the interface.
+ *
+ * 4 methods (D-08 locked):
+ *   - serialize(state): convert in-memory state to SerializedSnapshot
+ *   - deserialize(snapshot): inverse of serialize
+ *   - onEviction(hook): register a best-effort pre-eviction callback
+ *   - resume(snapshot): return ResumePolicy verdict for the post-restore
+ *     reconstruction. The host runtime acts on the policy.
+ *
+ * Adapters are POLYMORPHIC over TState -- the host runtime parameterizes
+ * the type. Lattice's vitest covers the contract surface with a noop
+ * adapter where TState = Record<string, unknown> for ergonomics.
+ */
+interface SurvivabilityAdapter<TState> {
+  readonly kind: "survivability-adapter";
   readonly id: string;
-  readonly kind?: "provider-ref";
+  serialize(state: TState): SerializedSnapshot;
+  deserialize(snapshot: SerializedSnapshot): TState;
+  onEviction(hook: EvictionHook<TState>): UnsubscribeFn;
+  resume(snapshot: SerializedSnapshot): Promise<ResumePolicy>;
 }
-interface ProviderRunRequest {
-  readonly task: string;
-  readonly artifacts: readonly ArtifactInput[];
-  readonly outputs: readonly string[];
-  readonly outputContracts?: OutputContractMap;
-  readonly policy?: unknown;
+/**
+ * Factory options for the reference noop adapter.
+ *
+ * - id: optional. Defaults to "noop-survivability". Useful when callers
+ *   want to distinguish multiple adapter instances in test fixtures.
+ * - policy: optional. Sets the default ResumePolicy returned by resume().
+ *   Defaults to "SAFE" (matches noop adapter semantics: no recovery
+ *   ambiguity if nothing was ever persisted).
+ */
+interface NoopSurvivabilityAdapterOptions {
+  readonly id?: string;
+  readonly policy?: ResumePolicy;
+}
+/**
+ * Reference implementation of SurvivabilityAdapter<TState>. Records
+ * eviction events but does NOT persist; serialize / deserialize round-
+ * trip via JSON.stringify / JSON.parse. Analog to createFakeProvider
+ * in the providers/ module -- gives Lattice's vitest a complete shape-
+ * conformance target before the real (FSB-side) adapter ships in
+ * Plan 05-05.
+ *
+ * Per CONTEXT.md D-11 the noop adapter ships in Lattice (not FSB)
+ * because it covers the contract surface in Lattice's own test suite;
+ * FSB's real chrome.storage.session-backed adapter is glue layer.
+ */
+declare function createNoopSurvivabilityAdapter<TState = Record<string, unknown>>(options?: NoopSurvivabilityAdapterOptions): SurvivabilityAdapter<TState>;
+//#endregion
+//#region src/tools/tools.d.ts
+interface ToolExecutionContext {
   readonly signal?: AbortSignal;
-  readonly plan?: ExecutionPlan;
-  readonly contextPack?: ContextPack;
-  readonly providerPackaging?: ProviderPackagingPlan;
-  readonly packagedArtifacts?: readonly ArtifactRef[];
+  readonly emit?: RunEventSink;
 }
-interface ProviderRunResponse {
-  readonly rawOutputs: Record<string, unknown>;
-  readonly artifactRefs?: readonly (ArtifactInput | ArtifactRef)[];
+interface ToolDefinition<TSchema extends StandardSchemaV1 = StandardSchemaV1> {
+  readonly kind: "tool";
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema: TSchema;
+  readonly execute: (input: StandardSchemaV1.InferOutput<TSchema>, context: ToolExecutionContext) => Promise<unknown> | unknown;
+}
+interface ToolCallResult {
+  readonly callId: string;
+  readonly toolName: string;
+  readonly artifact: ArtifactInput;
+}
+declare function defineTool<TSchema extends StandardSchemaV1>(definition: Omit<ToolDefinition<TSchema>, "kind">): ToolDefinition<TSchema>;
+declare function runTool<TSchema extends StandardSchemaV1>(tool: ToolDefinition<TSchema>, input: unknown, context?: ToolExecutionContext): Promise<ToolCallResult>;
+interface McpLikeClient {
+  readonly listTools?: () => Promise<readonly McpToolDescriptor[]> | readonly McpToolDescriptor[];
+  readonly callTool: (input: {
+    readonly name: string;
+    readonly arguments: unknown;
+  }) => Promise<unknown> | unknown;
+}
+interface McpToolDescriptor {
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema: StandardSchemaV1;
+}
+declare function importMcpTools(client: McpLikeClient, toolNames?: readonly string[]): Promise<readonly ToolDefinition[]>;
+declare function toolArtifactRef(result: ToolCallResult): ArtifactRef;
+//#endregion
+//#region src/agent/format-tools.d.ts
+/**
+ * One turn in the running conversation.
+ *
+ * `role: "tool"` is used for tool-result turns; `toolCallId` and `toolName`
+ * are populated so the model can correlate the result with its prior
+ * `tool_call` envelope.
+ */
+interface ConversationTurn {
+  readonly role: "user" | "assistant" | "tool";
+  readonly content: string;
+  readonly toolCallId?: string;
+  readonly toolName?: string;
+}
+type FormatToolsMode = "native" | "prompt-reencoded" | "auto";
+interface FormatToolsOptions {
   /**
-   * @deprecated Legacy per-attempt usage shape. Phase 7+ adapters should
-   * populate `normalizedUsage` instead — Plan 04 will prefer `normalizedUsage`
-   * when wiring `RunResult.usage`. Kept here for backward compatibility with
-   * v1.0 adapters that already report this field.
+   * Tool-use protocol mode. Defaults to `"auto"`, which currently resolves
+   * to `"prompt-reencoded"` for ALL 7 providers (Phase 19 simplification —
+   * native tool_use deferred to a follow-on milestone). Reserved for
+   * forward compatibility.
    */
-  readonly usage?: UsageRecord;
+  readonly mode?: FormatToolsMode;
   /**
-   * Phase 7 normalized usage shape for `RunResult.usage`. Populated by all
-   * Phase 7+ adapters (openai, openai-compat, ai-sdk, fake). `costUsd` is
-   * `null` when pricing is unknown (per the cost-normalization decision in
-   * 07-CONTEXT.md — distinguishes "free" from "unmeasured").
+   * Optional system prompt to prepend. Useful for setting persona /
+   * domain-specific instructions on top of the tool-use envelope.
    */
-  readonly normalizedUsage?: Usage;
-  readonly rawResponse?: unknown;
+  readonly system?: string;
 }
-interface ProviderAdapter {
-  readonly id: string;
-  readonly kind: "provider-adapter";
-  readonly capabilities?: readonly ModelCapability[];
-  readonly execute?: (request: ProviderRunRequest) => Promise<ProviderRunResponse>;
+interface FormattedToolsHandle {
+  /**
+   * Builds the single `task` string passed to `ProviderAdapter.execute()`.
+   * Encodes the conversation, available tools, and response-envelope
+   * instructions.
+   */
+  readonly buildTask: (conversation: readonly ConversationTurn[]) => string;
+  /**
+   * Phase 39 (v1.3): body-only sibling of `buildTask` — identical turn
+   * rendering minus the leading system block, so the byte-stable
+   * `describeForSystem()` prefix can be hoisted once per crew for
+   * prompt-cache sharing without duplication (39-05).
+   *
+   * Invariant: `describeForSystem() + "\n" + buildTaskBody(conversation)`
+   * reconstructs `buildTask(conversation)` byte-for-byte.
+   */
+  readonly buildTaskBody: (conversation: readonly ConversationTurn[]) => string;
+  /**
+   * Parses the assistant's response text. Returns:
+   *   - `ToolUseRequest[]` when the response contains one or more tool-call
+   *     envelopes (parsed in declaration order).
+   *   - `null` when the response is a final answer (no tool-call envelopes
+   *     detected).
+   *
+   * The parser is forgiving: it tolerates extra prose around the JSON
+   * envelope (markdown fences, leading explanations) and the model
+   * occasionally drifting on whitespace.
+   */
+  readonly parseToolUse: (responseText: string) => ReadonlyArray<ToolUseRequest> | null;
+  /**
+   * Returns the static system block describing available tools. Useful for
+   * tracing / logging the exact tool-description text fed to the model.
+   */
+  readonly describeForSystem: () => string;
+  /**
+   * Effective mode this handle resolved to (`"prompt-reencoded"` for all
+   * v1.2 providers). Exposed for inspectability.
+   */
+  readonly mode: "prompt-reencoded";
 }
-type ProviderRegistryInput = readonly (ProviderRef | ProviderAdapter | string)[];
+/**
+ * Convert a Standard Schema to a JSON Schema-shaped descriptor suitable for
+ * inclusion in an LLM tool description. Standard Schema vendors can
+ * optionally expose `toJSONSchema` on their schema objects; when absent,
+ * we fall back to a minimal structural description that lists the schema
+ * vendor + version + a placeholder. Models tolerate placeholder schemas in
+ * practice because the tool description is supplementary — what matters
+ * is the envelope contract (`{tool_call: {name, args}}`).
+ */
+declare function toolSchemaToJsonSchema(schema: StandardSchemaV1): unknown;
+/**
+ * Builds the prompt-reencoded tool-use protocol handle for any provider.
+ *
+ * Phase 19 ships a uniform implementation across all 7 logical providers
+ * (openai, openai-compat, anthropic, gemini, xai, openrouter, lm-studio).
+ * The `providerName` argument is accepted for forward compatibility but
+ * does not branch the implementation in v1.2.
+ */
+declare function formatToolsForProvider(providerName: string, tools: ReadonlyArray<ToolDefinition<StandardSchemaV1>>, options?: FormatToolsOptions): FormattedToolsHandle;
+declare function parseToolUseEnvelope(responseText: string): ReadonlyArray<ToolUseRequest> | null;
 //#endregion
-//#region src/plan/plan.d.ts
-type ExecutionPlanStatus = "stub" | "planned" | "no-route" | "running" | "completed" | "failed";
-type ExecutionStageKind = "analysis" | "transforms" | "context-packing" | "provider-packaging" | "tool-execution" | "execution" | "validation" | "tripwire" | "persistence" | "replay";
-type ExecutionStageStatus = "pending" | "running" | "completed" | "skipped" | "failed";
-interface ExecutionPlanStage {
-  readonly id: string;
-  readonly kind: ExecutionStageKind;
-  readonly status: ExecutionStageStatus;
-  readonly inputArtifacts?: readonly string[];
-  readonly outputArtifacts?: readonly string[];
-  readonly warnings: readonly string[];
-  readonly metadata?: Record<string, unknown>;
+//#region src/agent/host.d.ts
+/**
+ * Snapshot shape the agent loop serializes between iterations. The full
+ * shape is opaque to callers (they only see it through SerializedSnapshot
+ * via the configured SurvivabilityAdapter) but it's exported so reference
+ * implementations and tests can inspect the round-trip.
+ */
+interface AgentSnapshot {
+  readonly version: "agent-snapshot/v1";
+  readonly iterationIndex: number;
+  readonly conversation: readonly ConversationTurn[];
+  readonly cumulativeUsage: Usage;
+  readonly providerName: string;
+  readonly capturedAt: string;
+  /**
+   * Phase 39 (v1.3): dispatch ancestry chain of crew `AgentSpec` ids
+   * (root-first). Absent = root agent (single-agent runs never set it).
+   * Optional so existing serialized `agent-snapshot/v1` snapshots
+   * deserialize unchanged — the version literal stays `"agent-snapshot/v1"`
+   * (D-05; Pitfall 8). The crew dispatcher threads the chain through
+   * dispatch context in 39-05; cycle prevention rejects any dispatch whose
+   * target id already appears in the chain.
+   */
+  readonly ancestry?: readonly string[];
 }
-interface RouteRejectReason {
-  readonly code: string;
-  readonly message: string;
+/**
+ * Scheduler seam — controls how the agent loop yields between iterations.
+ *
+ * `scheduleNext(iterationIndex)` is called AFTER an AFTER_AGENT_ITERATION
+ * emission and BEFORE the next iteration's BEFORE_AGENT_ITERATION. The
+ * scheduler decides when to resume — synchronously (sync loop), on next
+ * tick (setTimeout/queueMicrotask), via a queue (Durable Object), or any
+ * other strategy.
+ *
+ * Default (noop): resolves immediately.
+ */
+interface AgentScheduler {
+  scheduleNext(iterationIndex: number): Promise<void>;
 }
-interface RouteCandidate {
-  readonly providerId: string;
-  readonly modelId: string;
-  readonly capability: ModelCapability;
-  readonly score: number;
-  readonly accepted: boolean;
-  readonly reasons: readonly RouteRejectReason[];
-  readonly estimates: RouteEstimates;
+/**
+ * Transport seam — controls how a provider call is dispatched.
+ *
+ * `call(provider, request)` wraps the provider's `execute()` invocation.
+ * Default (noop): pass-through (`provider.execute!(request)`). Cross-process
+ * bridges (FSB's offscreen-document host) override to dispatch via
+ * `chrome.runtime.sendMessage`.
+ *
+ * Per the Phase 19 INV-03 parity invariant, the transport seam does NOT
+ * modify the `ProviderAdapter` interface — it operates on top of the
+ * existing `execute()` method.
+ */
+interface AgentTransport {
+  call(provider: ProviderAdapter, request: ProviderRunRequest): Promise<ProviderRunResponse>;
 }
-interface RouteEstimates {
-  readonly inputTokens: number;
-  readonly outputTokens: number;
-  readonly costUsd?: number;
-  readonly latencyMs?: number;
+/**
+ * Storage seam — controls how agent state persists between iterations for
+ * resume after host eviction.
+ *
+ * Phase 20 composes this with the Phase 18 `SurvivabilityAdapter`:
+ *   - The adapter serializes `AgentSnapshot` to `SerializedSnapshot` on
+ *     each AFTER_AGENT_ITERATION; storage.save() persists the snapshot.
+ *   - On run start, the agent loop calls storage.load(). If a non-null
+ *     snapshot is returned, the adapter deserializes it; the loop resumes
+ *     at the recorded iteration index.
+ *   - On success, the loop calls storage.clear() so the next run starts
+ *     fresh.
+ *
+ * Default (noop): save() is a no-op, load() returns null, clear() is a
+ * no-op. Suitable for Node tests where eviction never occurs.
+ */
+interface AgentStorage {
+  save(snapshot: SerializedSnapshot): Promise<void>;
+  load(): Promise<SerializedSnapshot | null>;
+  clear(): Promise<void>;
 }
-interface SelectedRoute {
-  readonly providerId: string;
-  readonly modelId: string;
-  readonly score: number;
-  readonly estimates: RouteEstimates;
-  readonly inputModalities: readonly CapabilityModality[];
-  readonly outputModalities: readonly CapabilityModality[];
-  readonly fileTransport: readonly ProviderTransportMode[];
-}
-interface FallbackRoute {
-  readonly providerId: string;
-  readonly modelId: string;
-  readonly score: number;
-  readonly reason: "policy-preserving-fallback";
-}
-interface RouteDecision {
-  readonly catalogVersion: string;
-  readonly selected?: SelectedRoute;
-  readonly candidates: readonly RouteCandidate[];
-  readonly rejected: readonly RouteCandidate[];
-  readonly fallbackChain: readonly FallbackRoute[];
-  readonly noRouteReasons: readonly RouteRejectReason[];
+/**
+ * The host adapter — three optional seams, all swappable independently.
+ *
+ * Callers pass `host` on `AgentIntent`. The agent runtime falls back to
+ * `createNoopAgentHost()` when `intent.host` is absent (so Phase 19
+ * single-shot Node usage continues to work without explicit configuration).
+ */
+interface AgentHost {
+  readonly kind: "agent-host";
+  readonly scheduler?: AgentScheduler;
+  readonly transport?: AgentTransport;
+  readonly storage?: AgentStorage;
 }
-interface ContextPackPlan {
-  readonly id: string;
-  readonly tokenBudget: number;
-  readonly estimatedTokens: number;
-  readonly included: readonly ContextPackItemPlan[];
-  readonly summarized: readonly ContextPackItemPlan[];
-  readonly archived: readonly ContextPackItemPlan[];
-  readonly omitted: readonly ContextPackItemPlan[];
-  readonly warnings: readonly string[];
+/**
+ * Reference implementation suitable for Node tests + the Phase 19 default
+ * behavior.
+ *
+ * - scheduler: resolves immediately (no yield between iterations).
+ * - transport: pass-through to provider.execute().
+ * - storage: save() / clear() are no-ops; load() always returns null.
+ *
+ * Equivalent to passing no host at all.
+ */
+declare function createNoopAgentHost(): AgentHost;
+//#endregion
+//#region src/contract/contract.d.ts
+/**
+ * Budget invariant declaration attached to a CapabilityContract.
+ *
+ * Phase 7 implements `maxCostUsd` enforcement at pre-flight. The
+ * `p95LatencyMs` field is declared per CONTRACT-02 but is informational
+ * only in Phase 7 — latency observations are wired in a later phase.
+ *
+ * Phase 19 (v1.2) adds `maxIterations` and `maxWallTimeMs` for the agent
+ * runtime. Both are additive and optional; non-agent callers ignore them.
+ * `maxIterations` caps the number of `runAgent` iterations; `maxWallTimeMs`
+ * caps wall-clock duration per `runAgent` invocation. Both are enforced
+ * pre-iteration in the agent loop.
+ */
+interface BudgetInvariant {
+  readonly maxCostUsd?: number;
+  readonly maxIterations?: number;
+  readonly maxWallTimeMs?: number;
+  readonly p95LatencyMs?: number;
 }
-interface ContextPackItemPlan {
-  readonly artifactId?: string;
-  readonly sessionTurnId?: string;
-  readonly reason: string;
-  readonly estimatedTokens: number;
-  readonly trust: "developer" | "user" | "tool" | "model-summary";
+/**
+ * Quality-floor invariant.
+ *
+ * `suite` is a fixture-directory path string; `minScore` is in 0..1.
+ * Phase 7 forwards this into the pre-flight evaluator but only enforces
+ * capability-side rejects. Full enforcement lives in Phase 12 (`lattice eval`).
+ */
+interface QualityFloorInvariant {
+  readonly suite: string;
+  readonly minScore: number;
 }
-interface ProviderPackagingPlan {
-  readonly providerId: string;
-  readonly modelId: string;
-  readonly artifacts: readonly ProviderPackagedArtifactPlan[];
-  readonly warnings: readonly string[];
+/**
+ * The full Capability Contract attached to `RunIntent.contract`.
+ *
+ * All fields are optional. v1.0 callers compile and run unchanged when
+ * the field is omitted entirely. PROJECT.md explicitly rejects mandatory
+ * contracts.
+ */
+interface CapabilityContract {
+  readonly kind: "capability-contract";
+  readonly budget?: BudgetInvariant;
+  readonly invariants?: readonly InvariantDeclaration[];
+  readonly qualityFloor?: QualityFloorInvariant;
+  readonly requiredModalities?: readonly CapabilityModality[];
+  readonly requiredPrivacy?: "standard" | "sensitive" | "restricted";
 }
-interface ProviderPackagedArtifactPlan {
-  readonly artifactId: string;
-  readonly transport: ProviderTransportMode;
-  readonly mediaType?: string;
-  readonly lineageTransform: "provider-packaging";
-  readonly warnings: readonly string[];
+/**
+ * Reject-reason taxonomy added to `RouteRejectReason.code` by Phase 7's
+ * pre-flight evaluator. Closed four-value union per the locked decisions
+ * in 07-CONTEXT.md.
+ */
+type ContractRejectReasonCode = "contract-budget-exceeded" | "contract-quality-floor" | "contract-modality-missing" | "contract-privacy-mismatch";
+/** Input shape accepted by `contract()`. Mirrors `CapabilityContract` minus `kind`. */
+interface CapabilityContractInput {
+  readonly budget?: BudgetInvariant;
+  readonly invariants?: readonly InvariantDeclaration[];
+  readonly qualityFloor?: QualityFloorInvariant;
+  readonly requiredModalities?: readonly CapabilityModality[];
+  readonly requiredPrivacy?: "standard" | "sensitive" | "restricted";
 }
-interface ProviderAttemptRecord {
-  readonly providerId: string;
-  readonly modelId: string;
-  readonly status: "pending" | "running" | "succeeded" | "failed" | "cancelled";
-  readonly startedAt?: string;
-  readonly completedAt?: string;
-  readonly error?: string;
-  readonly usage?: UsageRecord;
+/**
+ * Factory for `CapabilityContract` values.
+ *
+ * Mirrors the `output()` and adapter factory style — exact-optional safe
+ * (does not emit `field: undefined` properties under `exactOptionalPropertyTypes`).
+ * Returns a frozen value with frozen nested objects so downstream code can
+ * rely on structural immutability when canonicalizing in Phase 9.
+ */
+declare function contract(input?: CapabilityContractInput): CapabilityContract;
+//#endregion
+//#region src/outputs/infer.d.ts
+type InferOutput<C> = C extends "text" ? string : C extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<C> : C extends CitationsOutputContract ? readonly CitationRef[] : C extends ArtifactRefsOutputContract ? readonly ArtifactRef[] : never;
+type InferOutputMap<T extends OutputContractMap> = { readonly [K in keyof T]: InferOutput<T[K]> };
+//#endregion
+//#region src/results/errors.d.ts
+interface ValidationIssue {
+  readonly message: string;
+  readonly path?: readonly (string | number | symbol)[];
 }
-interface UsageRecord {
-  readonly inputTokens?: number;
-  readonly outputTokens?: number;
-  readonly totalTokens?: number;
-  readonly costUsd?: number;
-  readonly latencyMs?: number;
+interface ValidationError {
+  readonly kind: "validation";
+  readonly message: string;
+  readonly output?: string;
+  readonly issues: readonly ValidationIssue[];
 }
-interface ExecutionPlan {
-  readonly id: string;
-  readonly kind: "execution-plan";
-  readonly version: 1;
-  readonly createdAt: string;
-  readonly status: ExecutionPlanStatus;
-  readonly task: string;
-  readonly outputNames: readonly string[];
-  readonly artifactRefs: readonly ArtifactRef[];
-  readonly route: RouteDecision;
-  readonly stages: readonly ExecutionPlanStage[];
-  readonly context?: ContextPackPlan;
-  readonly providerPackaging?: ProviderPackagingPlan;
-  readonly attempts: readonly ProviderAttemptRecord[];
-  readonly warnings: readonly string[];
-  readonly metadata?: Record<string, unknown>;
+interface ExecutionUnavailableError {
+  readonly kind: "execution_unavailable";
+  readonly message: string;
 }
-interface ExecutionPlanStub {
-  readonly id: string;
-  readonly kind: "plan-stub";
-  readonly createdAt: string;
-  readonly status: "stub";
-  readonly stages: readonly [];
-  readonly warnings: readonly string[];
+interface NoRouteError {
+  readonly kind: "no_route";
+  readonly message: string;
+  readonly reasons: readonly string[];
 }
-type ResultPlan = ExecutionPlan | ExecutionPlanStub;
-//#endregion
-//#region src/receipts/types.d.ts
-type ContractVerdict = "success" | "tripwire-violated" | "no-contract-match" | "execution-failed" | "validation-failed";
-interface ReceiptUsageCanonical {
-  readonly promptTokens: number;
-  readonly completionTokens: number;
-  readonly costUsd: string | null;
+interface ProviderExecutionError {
+  readonly kind: "provider_execution";
+  readonly message: string;
+  readonly providerId?: string;
+  readonly modelId?: string;
 }
-interface ReceiptModel {
-  readonly requested: string;
-  readonly observed: string | null;
+interface TimeoutError {
+  readonly kind: "timeout";
+  readonly message: string;
 }
-interface ReceiptRoute {
-  readonly providerId: string;
-  readonly capabilityId: string;
-  readonly attemptNumber: number;
+/**
+ * Phase 7 addition: emitted by the runtime when no candidate route can
+ * satisfy the caller-supplied `CapabilityContract` (budget, modality,
+ * privacy, or quality-floor invariants).
+ *
+ * `noRouteReasons` carries the full deterministic-router rejection list
+ * so callers can inspect per-candidate detail. Phase 9 (receipts) will
+ * persist this array for deterministic verdict reconstruction.
+ */
+interface NoContractMatchError {
+  readonly kind: "no-contract-match";
+  readonly message: string;
+  readonly noRouteReasons: readonly RouteRejectReason[];
 }
-interface ReceiptRedaction {
-  readonly path: string;
-  readonly reason: string;
+/**
+ * Phase 8 addition: emitted when a `CapabilityContract.invariants` tripwire
+ * fires after the provider returned a schema-valid output. Carries the
+ * `TripwireEvidence` produced by `evaluateTripwires`.
+ *
+ * `terminal: true` is a structural marker — combined with the `isTerminal()`
+ * predicate it tells the fallback chain in `runWithConfig` to refuse retry.
+ * `NoContractMatchError` does NOT carry the field (to avoid breaking Phase 7
+ * callers) but `isTerminal()` still returns true for it via the kind check.
+ */
+interface TripwireViolationError {
+  readonly kind: "tripwire-violated";
+  readonly message: string;
+  readonly invariantId: string;
+  readonly evidence: TripwireEvidence;
+  readonly terminal: true;
 }
-interface CapabilityReceiptBody {
-  readonly version: "lattice-receipt/v1" | "lattice-receipt/v1.1";
-  readonly receiptId: string;
-  readonly runId: string;
-  readonly issuedAt: string;
-  readonly kid: string;
-  readonly model: ReceiptModel;
-  readonly route: ReceiptRoute;
-  readonly usage: ReceiptUsageCanonical;
-  readonly contractVerdict: ContractVerdict;
-  readonly contractHash: string | null;
-  readonly inputHashes: readonly string[];
-  readonly outputHash: string | null;
-  readonly redactionPolicyId: string;
-  readonly redactions: readonly ReceiptRedaction[];
-  readonly noRouteReasons?: readonly RouteRejectReason[];
-  readonly tripwireEvidence?: TripwireEvidence;
-  readonly stepName?: string;
-  readonly stepIndex?: number;
-  readonly parentStepName?: string;
-  readonly previousStepName?: string;
-  readonly sessionId?: string;
-  readonly timestamp?: string;
+type LatticeRunError = ValidationError | ExecutionUnavailableError | NoRouteError | ProviderExecutionError | TimeoutError | NoContractMatchError | TripwireViolationError;
+/**
+ * Returns `true` for run errors that MUST NOT be retried by the fallback
+ * chain. Phase 8 covers two kinds:
+ *
+ *   - `tripwire-violated` — the contract's invariants rejected the output;
+ *     a different provider will not change the verdict, so retry burns
+ *     budget for no gain (T-08-06 in 08-02-PLAN threat register).
+ *   - `no-contract-match` — no route satisfies the contract at all; the
+ *     run never executed and no retry will help.
+ *
+ * All other error kinds return `false` and remain eligible for fallback.
+ * The predicate is exported so Phase 12's eval gate and any user-side
+ * retry wrappers can share one source of truth.
+ */
+declare function isTerminal(error: LatticeRunError): boolean;
+//#endregion
+//#region src/agent/types.d.ts
+/**
+ * Per-iteration record stored on `AgentSuccess.iterations` for inspectability.
+ *
+ * `toolCalls` carries content-addressed args/result hashes (sha256) so
+ * downstream receipts can reference them without inlining the bodies.
+ *
+ * `deniedReason` is populated on iterations whose `BEFORE_AGENT_ITERATION`
+ * SAFETY-band handler set `controls.deny(...)`.
+ */
+interface IterationRecord {
+  readonly index: number;
+  readonly provider: string;
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly costUsd: number | null;
+  readonly durationMs: number;
+  readonly toolCalls: ReadonlyArray<{
+    readonly id: string;
+    readonly name: string;
+    readonly argsHash: string;
+    readonly resultHash: string;
+  }>;
+  readonly deniedReason?: string;
+  readonly receipt?: ReceiptEnvelope;
 }
-interface ReceiptSignature {
-  readonly keyid: string;
-  readonly sig: string;
+/**
+ * Input shape accepted by `ai.runAgent(intent)`.
+ *
+ * All fields except `task` and `tools` are optional. The runtime supplies
+ * sensible defaults (in-process host, fresh pipeline, no signer, no tracer).
+ *
+ * `TOutputs` parameterizes the final-answer schema map; defaults to a free-form
+ * `{ answer: "text" }` shape when the field is omitted. Validation runs once
+ * against the final assistant message (no intermediate iteration validation).
+ */
+interface AgentIntent<TOutputs extends OutputContractMap = OutputContractMap> {
+  readonly task: string;
+  readonly tools: ReadonlyArray<ToolDefinition<StandardSchemaV1>>;
+  readonly host?: AgentHost;
+  /**
+   * Phase 20 (v1.2): when the agent loop resumes from a host.storage snapshot,
+   * the configured SurvivabilityAdapter handles the serialize/deserialize
+   * round-trip. When absent, runtime defaults to
+   * `createNoopSurvivabilityAdapter<AgentSnapshot>()`.
+   */
+  readonly survivabilityAdapter?: SurvivabilityAdapter<AgentSnapshot>;
+  readonly contract?: CapabilityContract;
+  readonly policy?: PolicySpec;
+  readonly outputs?: TOutputs;
+  readonly pipeline?: HookPipeline;
+  readonly signer?: ReceiptSigner;
+  readonly tracer?: TracerLike;
+  /**
+   * When `false`, the runtime will NOT auto-register `createCheckpointHook`
+   * even if `signer` is provided. Callers who want full manual control over
+   * receipt minting set this to `false` and register their own hook.
+   * Defaults to `true` (auto-register when signer present).
+   */
+  readonly autoRegisterCheckpoint?: boolean;
 }
-interface ReceiptEnvelope {
-  readonly payloadType: "application/vnd.lattice.receipt+json";
-  readonly payload: string;
-  readonly signatures: readonly ReceiptSignature[];
+/**
+ * Success result returned by `ai.runAgent` when the loop reaches a final
+ * answer and (when `outputs` is declared) the final answer validates.
+ *
+ * `iterations[]` records every iteration that ran — including the one that
+ * produced the final answer. `receipt` is the outermost receipt minted at
+ * loop close when `signer` is configured (separate from per-iteration
+ * receipts on `iterations[i].receipt`).
+ */
+interface AgentSuccess<TOutputs extends OutputContractMap = OutputContractMap> {
+  readonly kind: "success";
+  readonly output: InferOutputMap<TOutputs>;
+  readonly artifacts?: readonly ArtifactRef[];
+  readonly usage: Usage;
+  readonly iterations: ReadonlyArray<IterationRecord>;
+  readonly receipt?: ReceiptEnvelope;
 }
-interface ReceiptSigner {
-  readonly kid: string;
-  sign(bytes: Uint8Array): Promise<Uint8Array>;
-  readonly publicKeyJwk: JsonWebKey;
+/**
+ * Failure kinds specific to the agent loop. v1.1 `LatticeRunError.kind`
+ * values remain valid (provider errors, no-contract-match, validation-failed,
+ * tripwire-violated) and are reused verbatim. Phase 19 adds three
+ * agent-specific kinds. Phase 39 (v1.3) adds `crew-budget-exceeded` —
+ * crew-level shared-pool exhaustion, terminal across the parent/child
+ * boundary (D-10).
+ */
+type AgentFailureKind = LatticeRunError["kind"] | "agent-iteration-denied" | "agent-max-iterations" | "agent-wall-time-exceeded" | "crew-budget-exceeded";
+/**
+ * Failure result returned by `ai.runAgent`. Discriminates via `kind`.
+ *
+ * `iterations[]` carries any iterations that completed before the failure
+ * (empty if the failure occurred pre-iteration). For `agent-iteration-denied`,
+ * the failing iteration is the LAST entry and carries `deniedReason`.
+ */
+interface AgentFailure {
+  readonly kind: AgentFailureKind;
+  readonly usage: Usage;
+  readonly iterations: ReadonlyArray<IterationRecord>;
+  readonly reason?: string;
+  readonly cause?: unknown;
+  readonly receipt?: ReceiptEnvelope;
 }
-type KeyState = "active" | "retired" | "revoked";
-interface KeyEntry {
-  readonly kid: string;
-  readonly publicKeyJwk: JsonWebKey;
-  readonly state: KeyState;
+/**
+ * Discriminated union returned by `ai.runAgent`.
+ */
+type AgentResult<TOutputs extends OutputContractMap = OutputContractMap> = AgentSuccess<TOutputs> | AgentFailure;
+/**
+ * Typed error raised when a SAFETY-band handler sets `controls.deny(reason)`
+ * during `BEFORE_AGENT_ITERATION`. Carries `terminal: true` semantics to
+ * align with v1.1 `TripwireViolationError`: the failure is NOT retried by
+ * the fallback chain.
+ *
+ * Surfaced via `AgentFailure { kind: "agent-iteration-denied", reason, ... }`
+ * — callers can also catch the typed error if they prefer.
+ */
+declare class AgentDeniedError extends Error {
+  readonly kind: "agent-iteration-denied";
+  readonly terminal: true;
+  readonly reason: string;
+  readonly iterationIndex: number;
+  constructor(reason: string, iterationIndex: number);
 }
-interface KeySet {
-  lookup(kid: string): KeyEntry | undefined;
+/**
+ * Returned by `formatToolsForProvider` (Phase 19 Plan 19-03). Re-exported
+ * here for convenience; the canonical declaration lives in format-tools.ts.
+ */
+interface ToolUseRequest {
+  readonly id: string;
+  readonly name: string;
+  readonly args: unknown;
 }
-type VerifyErrorKind = "key-not-found" | "key-revoked" | "canonicalization-mismatch" | "signature-invalid" | "envelope-malformed" | "version-mismatch" | "schema-version-too-low";
-interface VerifyError {
-  readonly kind: VerifyErrorKind;
-  readonly message: string;
+//#endregion
+//#region src/tools/tool-call-validation.d.ts
+type ToolCallValidationFailureReason = "unknown_tool" | "invalid_args" | "extra_fields";
+interface ValidatedToolCall {
+  readonly id: string;
+  readonly name: string;
+  readonly args: unknown;
 }
-interface VerifyOk {
-  readonly ok: true;
-  readonly body: CapabilityReceiptBody;
-  readonly keyState: KeyState;
+type ToolCallValidationTool = Pick<ToolDefinition, "name" | "inputSchema">;
+interface ValidateToolCallsOption {
+  readonly tools: readonly ToolCallValidationTool[];
+  readonly onFailure?: "throw" | "drop" | "callback";
+  readonly onValidationFailure?: (error: ToolCallValidationError) => void | Promise<void>;
+  readonly allowExtraFields?: boolean;
 }
-interface VerifyFail {
-  readonly ok: false;
-  readonly error: VerifyError;
+declare class ToolCallValidationError extends Error {
+  readonly kind: "tool-call-validation";
+  readonly reason: ToolCallValidationFailureReason;
+  readonly toolName: string;
+  readonly attemptedArgs: unknown;
+  readonly validationIssues: readonly ValidationIssue[];
+  readonly requestId: string;
+  constructor(input: {
+    readonly reason: ToolCallValidationFailureReason;
+    readonly toolName: string;
+    readonly attemptedArgs: unknown;
+    readonly validationIssues?: readonly ValidationIssue[];
+    readonly requestId: string;
+  });
 }
-type VerifyResult = VerifyOk | VerifyFail;
 //#endregion
-//#region src/receipts/receipt.d.ts
+//#region src/providers/quirks.d.ts
 /**
- * Public input to createReceipt. Mirrors CapabilityReceiptBody minus:
- *   - `version` (forced to "lattice-receipt/v1.1" per CRYPTO-01)
- *   - `kid` (forced from signer.kid — caller cannot mismatch)
- *   - `redactions[]` (populated by redactReceiptBody)
- *   - `usage.costUsd` (converted to canonical string by usageToCanonical)
+ * Universal 5-boolean shape every first-party adapter populates (SC-1 / D-03).
  *
- * receiptId and issuedAt default to runtime-generated values when omitted.
- * redactionPolicyId defaults to DEFAULT_REDACTION_POLICY_ID.
+ * - `supportsToolChoice`     — adapter supports tool_choice / forced-tool-call mode
+ * - `parallelToolCalls`      — adapter supports parallel (multi-tool) calls in one turn
+ * - `structuredOutputs`      — adapter honors response_format JSON schema binding
+ * - `responseFormatHonored`  — adapter treats response_format as authoritative (false
+ *                              for vanilla openai-compat servers; true for OpenAI/Anthropic/Gemini)
+ * - `streamingDiverges`      — streamed output differs from buffered output (true for
+ *                              some self-hosted servers; false for OpenAI/Anthropic/Gemini)
  */
-interface CreateReceiptInput {
-  readonly runId: string;
-  readonly issuedAt?: string;
-  readonly receiptId?: string;
-  readonly model: ReceiptModel;
-  readonly route: ReceiptRoute;
-  readonly usage: Usage;
-  readonly contractVerdict: ContractVerdict;
-  readonly contractHash: string | null;
-  readonly inputHashes: readonly string[];
-  readonly outputHash: string | null;
-  readonly redactionPolicyId?: string;
-  readonly noRouteReasons?: readonly RouteRejectReason[];
-  readonly tripwireEvidence?: TripwireEvidence;
-  readonly stepName?: string;
-  readonly stepIndex?: number;
-  readonly parentStepName?: string;
-  readonly previousStepName?: string;
-  readonly sessionId?: string;
-  readonly timestamp?: string;
+interface AdapterQuirks {
+  readonly supportsToolChoice: boolean;
+  readonly parallelToolCalls: boolean;
+  readonly structuredOutputs: boolean;
+  readonly responseFormatHonored: boolean;
+  readonly streamingDiverges: boolean;
 }
 /**
- * Build, redact, canonicalize, sign, and envelope a CapabilityReceipt.
- *
- * Ordering INVARIANT (09-CONTEXT.md, PITFALLS.md Pitfall #1):
- *   redact -> canonicalize -> PAE -> sign -> encode
+ * Anthropic adapter quirks (extends AdapterQuirks with 3 Anthropic-specific flags).
  *
- * The signed digest commits to canonicalize(redact(body)). The function
- * structure makes any other ordering impossible to write by accident —
- * canonicalizeReceiptBody is ONLY called on the output of redactReceiptBody.
+ * CITED: Anthropic prompt caching docs — https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+ *   - `promptCachingSupported`: cache_control on system and user turns is supported on
+ *     all active Claude models (claude-3-* and claude-*-4 families).
  *
- * Defense in depth:
- *   - body.kid is assigned from signer.kid, never from input (input has no
- *     kid field). The signed body and the envelope keyid CANNOT disagree by
- *     construction.
- *   - signer.kid is also written to envelope.signatures[0].keyid, so the
- *     verifier can cross-check (Step 7 of verifyReceipt).
+ * CITED: Anthropic extended thinking docs — https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking
+ *   - `extendedThinkingSupported`: thinking blocks (claude-3-7-sonnet+ and claude-*-4) available
+ *     via the "thinking" request parameter.
  *
- * I-JSON guarantees: usage.costUsd is converted to string (or null) via
- * usageToCanonical. Receipts NEVER carry raw floats in the canonical form.
+ * CITED: Anthropic tool use docs — https://docs.anthropic.com/en/docs/build-with-claude/tool-use
+ *   - `toolUseInputSchemaStrict`: Anthropic tool_use blocks require strict JSON Schema in
+ *     the input_schema field; the adapter enforces this at call time.
  */
-declare function createReceipt(input: CreateReceiptInput, signer: ReceiptSigner): Promise<ReceiptEnvelope>;
-//#endregion
-//#region src/contract/checkpoint.d.ts
+interface AnthropicQuirks extends AdapterQuirks {
+  readonly promptCachingSupported: boolean;
+  readonly extendedThinkingSupported: boolean;
+  readonly toolUseInputSchemaStrict: boolean;
+}
 /**
- * The tracer event name Lattice's checkpoint hook emits per step transition.
- * Identical to the literal added to RunEventKind in tracing.ts.
+ * OpenAI adapter quirks (extends AdapterQuirks with 2 OpenAI-specific flags).
+ *
+ * CITED: OpenAI structured outputs docs — https://platform.openai.com/docs/guides/structured-outputs
+ *   - `strictModeSupported`: function-calling strict:true mode available on
+ *     gpt-4o-2024-08-06+ and o1+ series.
+ *   - `structuredOutputsTier2`: json_schema response_format mode (tier-2 structured outputs)
+ *     available on gpt-4o and gpt-4o-mini series.
  */
-declare const STEP_TRANSITION_EVENT_NAME: "step.transition";
+interface OpenAIQuirks extends AdapterQuirks {
+  readonly strictModeSupported: boolean;
+  readonly structuredOutputsTier2: boolean;
+}
 /**
- * Default band convention for the checkpoint hook (D-06). The caller is
- * free to register in a different band but the documented convention is
- * OBSERVABILITY -- between SAFETY (runs first) and EXTENSION (runs last).
+ * OpenAI-compatible adapter quirks (same 5 base booleans, no new fields).
+ *
+ * Conservative defaults: openai-compat servers (vLLM, TGI, Ollama, custom)
+ * vary widely in which response_format and tool_choice features they implement.
+ * The factory populates the base fields conservatively (responseFormatHonored:
+ * false, structuredOutputs: false) because the endpoint could be anything.
+ * Consumers pointing at a known-good server should verify quirk values manually.
  */
-declare const DEFAULT_CHECKPOINT_BAND: Band;
+interface OpenAICompatQuirks extends AdapterQuirks {}
 /**
- * Per-step context the caller passes through the hook pipeline.
+ * Gemini adapter quirks (extends AdapterQuirks with 3 Gemini-specific flags).
  *
- * Fields are stable identifiers (D-04 carryforward); do NOT populate with
- * user content -- they appear cleartext in the signed receipt body.
+ * CITED: Gemini API docs — https://ai.google.dev/api/generate-content#v1beta.GenerationConfig
+ *   - `responseSchemaSupported`: responseSchema / responseJsonSchema on generateContent
+ *     is available on gemini-1.5-pro+ and gemini-2.x models.
+ *   - `safetySettingsConfigurable`: all 4 harm categories (HARASSMENT, HATE_SPEECH,
+ *     SEXUALLY_EXPLICIT, DANGEROUS_CONTENT) can be set to BLOCK_NONE — verified in
+ *     gemini.ts:50-55.
  *
- * - stepName: required. Stable identifier for this step.
- * - stepIndex: required. Monotonically increasing ordinal; caller-owned.
- * - parentStepName: optional. Names the enclosing step when nested.
- * - previousStepName: optional. Names the immediately-prior step in the
- *   linked-list timeline (D-09 linked-list threading).
- * - timestamp: required. ISO-8601 RFC 3339.
+ * CITED: Gemini API system instruction docs — https://ai.google.dev/api/generate-content#v1beta.GenerateContentRequest
+ *   - `systemInstructionSupported`: systemInstruction field on GenerateContentRequest
+ *     available on gemini-1.5+ series and later.
  */
-interface CheckpointHookContext {
-  readonly stepName: string;
-  readonly stepIndex: number;
-  readonly parentStepName?: string;
-  readonly previousStepName?: string;
-  readonly timestamp: string;
+interface GeminiQuirks extends AdapterQuirks {
+  readonly responseSchemaSupported: boolean;
+  readonly safetySettingsConfigurable: boolean;
+  readonly systemInstructionSupported: boolean;
 }
 /**
- * The factory's options.
+ * xAI adapter quirks (extends AdapterQuirks with 2 xAI-specific flags).
  *
- * - runId: required. Threaded into every receipt body + every tracer event.
- * - tracer: optional. When omitted, the handler still mints (when signer
- *   present) but does NOT emit a tracer event. When provided, the handler
- *   ALWAYS emits exactly one event per invocation (independent of mint
- *   success/failure per D-10).
- * - signer: optional. When omitted, the handler emits a tracer event only
- *   (no mint attempted). When provided, the handler attempts to mint via
- *   createReceipt(...) inside a try/catch (D-07 best-effort).
- * - sessionId: optional. Threaded into receipt body and event metadata.
- * - model: optional. ReceiptModel descriptor for the receipt body; the
- *   factory provides a sensible "step" default when omitted.
- * - route: optional. ReceiptRoute descriptor for the receipt body; the
- *   factory provides a sensible "step" default when omitted.
- * - contractVerdict: optional. Defaults to "success" -- step transitions
- *   are observability events, not contract evaluations.
+ * CITED: xAI API docs — https://docs.x.ai/api/endpoints
+ *   - `reasoningTokensReported`: completion_tokens_details.reasoning_tokens reported
+ *     in xAI API responses — verified in xai.ts:46-72.
+ *   - `logprobsSupported`: grok-4.20 silently ignores logprobs param per observed
+ *     behavior; flag indicates whether logprobs fields will be populated.
  */
-interface CheckpointHookOptions {
-  readonly runId: string;
-  readonly tracer?: TracerLike;
-  readonly signer?: ReceiptSigner;
-  readonly sessionId?: string;
-  readonly model?: ReceiptModel;
-  readonly route?: ReceiptRoute;
-  readonly contractVerdict?: CreateReceiptInput["contractVerdict"];
+interface XaiQuirks extends AdapterQuirks {
+  readonly reasoningTokensReported: boolean;
+  readonly logprobsSupported: boolean;
 }
 /**
- * Build a checkpoint hook handler.
- *
- * The returned handler is suitable for registration on a HookPipeline
- * created via createHookPipeline (see ./bands.ts). The handler does not
- * auto-register; the caller passes it to pipeline.register(...) with the
- * desired lifecycle event (typically AFTER_TOOL or BEFORE_TOOL) and band
- * (typically BAND.OBSERVABILITY, exported as DEFAULT_CHECKPOINT_BAND).
- *
- * Per-invocation behavior:
- *   1. Build event metadata from options + per-call context.
- *   2. If signer is configured, attempt createReceipt(...) inside a
- *      try/catch. On success, set metadata.receiptId + metadata.envelope.
- *      On failure, set metadata.mintError (string from caught error).
- *   3. If tracer is configured, emit exactly one tracer.event?.(
- *      STEP_TRANSITION_EVENT_NAME, metadata) call.
- *   4. Return void.
+ * OpenRouter adapter quirks (extends AdapterQuirks with 3 OpenRouter-specific flags).
  *
- * NO upstream throw (D-07). NO global mutation (D-05).
+ * CITED: OpenRouter provider routing docs — https://openrouter.ai/docs/provider-routing
+ *   - `providerRoutingArraySupported`: the `provider.order` / `provider.only` /
+ *     `provider.ignore` arrays are supported for explicit routing control.
+ *   - `floorPricingHints`: `max_price`, `sort: "throughput" | "price"` hints on
+ *     GenerationConfig for cost-aware routing.
+ *   - `allowFallbacks`: `provider.allow_fallbacks: boolean` controls whether OpenRouter
+ *     retries with a different upstream provider on failure.
  */
-declare function createCheckpointHook(options: CheckpointHookOptions): HookHandler<CheckpointHookContext>;
-//#endregion
-//#region src/contract/contract.d.ts
+interface OpenRouterQuirks extends AdapterQuirks {
+  readonly providerRoutingArraySupported: boolean;
+  readonly floorPricingHints: boolean;
+  readonly allowFallbacks: boolean;
+}
 /**
- * Budget invariant declaration attached to a CapabilityContract.
+ * LM Studio adapter quirks (extends AdapterQuirks with 2 LM Studio-specific flags).
  *
- * Phase 7 implements `maxCostUsd` enforcement at pre-flight. The
- * `p95LatencyMs` field is declared per CONTRACT-02 but is informational
- * only in Phase 7 — latency observations are wired in a later phase.
+ * CITED: lmstudio-bug-tracker — Jinja template mismatches between model training and
+ * LM Studio server defaults cause output format corruption.
+ *   - `customChatTemplateRiskFlag`: LM Studio servers can ship with broken chat templates
+ *     that don't match the model's training template; flag signals this risk.
  *
- * Phase 19 (v1.2) adds `maxIterations` and `maxWallTimeMs` for the agent
- * runtime. Both are additive and optional; non-agent callers ignore them.
- * `maxIterations` caps the number of `runAgent` iterations; `maxWallTimeMs`
- * caps wall-clock duration per `runAgent` invocation. Both are enforced
- * pre-iteration in the agent loop.
+ * VERIFIED: lm-studio.ts:35-37 — apiKey is optional for LM Studio local servers.
+ *   - `noAuthRequired`: apiKey is NOT required for local LM Studio instances (no
+ *     authentication by default on localhost:1234).
  */
-interface BudgetInvariant {
-  readonly maxCostUsd?: number;
-  readonly maxIterations?: number;
-  readonly maxWallTimeMs?: number;
-  readonly p95LatencyMs?: number;
+interface LmStudioQuirks extends AdapterQuirks {
+  readonly customChatTemplateRiskFlag: boolean;
+  readonly noAuthRequired: boolean;
 }
 /**
- * Quality-floor invariant.
+ * LiteLLM adapter quirks (extends AdapterQuirks with gateway-specific flags).
  *
- * `suite` is a fixture-directory path string; `minScore` is in 0..1.
- * Phase 7 forwards this into the pre-flight evaluator but only enforces
- * capability-side rejects. Full enforcement lives in Phase 12 (`lattice eval`).
+ * LiteLLM is consumed as an OpenAI-compatible gateway. Lattice does not start,
+ * embed, or depend on a LiteLLM gateway process; these flags describe the
+ * helper's supported gateway metadata contract over HTTP.
  */
-interface QualityFloorInvariant {
-  readonly suite: string;
-  readonly minScore: number;
+interface LiteLLMQuirks extends AdapterQuirks {
+  readonly gatewayMetadataSupported: boolean;
+  readonly gatewayFallbacksSupported: boolean;
+  readonly openAIErrorMapping: boolean;
 }
+//#endregion
+//#region src/capabilities/sanitizer-recommendations.d.ts
 /**
- * The full Capability Contract attached to `RunIntent.contract`.
+ * D-13 — Phase 36 sanitizer registration keys. Closed string-literal union;
+ * adding a 4th sanitizer in v1.4 is an intentional typed breaking change
+ * that mirrors the `KnownFailureMode` discipline.
  *
- * All fields are optional. v1.0 callers compile and run unchanged when
- * the field is omitted entirely. PROJECT.md explicitly rejects mandatory
- * contracts.
- */
-interface CapabilityContract {
-  readonly kind: "capability-contract";
-  readonly budget?: BudgetInvariant;
-  readonly invariants?: readonly InvariantDeclaration[];
-  readonly qualityFloor?: QualityFloorInvariant;
-  readonly requiredModalities?: readonly CapabilityModality[];
-  readonly requiredPrivacy?: "standard" | "sensitive" | "restricted";
-}
-/**
- * Reject-reason taxonomy added to `RouteRejectReason.code` by Phase 7's
- * pre-flight evaluator. Closed four-value union per the locked decisions
- * in 07-CONTEXT.md.
+ * Phase 36 registers implementations under EXACTLY these 3 ids:
+ *   - "stripReasoningTags"          — strips <think>/</think> (and model-specific) reasoning tags
+ *   - "stripChatTemplateArtifacts"  — removes chat-template artifact leaks from output
+ *   - "unwrapInternalEnvelope"      — extracts the user-visible payload from internal wrapper
  */
-type ContractRejectReasonCode = "contract-budget-exceeded" | "contract-quality-floor" | "contract-modality-missing" | "contract-privacy-mismatch";
-/** Input shape accepted by `contract()`. Mirrors `CapabilityContract` minus `kind`. */
-interface CapabilityContractInput {
-  readonly budget?: BudgetInvariant;
-  readonly invariants?: readonly InvariantDeclaration[];
-  readonly qualityFloor?: QualityFloorInvariant;
-  readonly requiredModalities?: readonly CapabilityModality[];
-  readonly requiredPrivacy?: "standard" | "sensitive" | "restricted";
-}
+type SanitizerKey = "stripReasoningTags" | "stripChatTemplateArtifacts" | "unwrapInternalEnvelope";
 /**
- * Factory for `CapabilityContract` values.
+ * D-14 + D-16 — Exhaustive mapping from KnownFailureMode to SanitizerKey
+ * (or null when the failure mode is not a sanitizer concern). The
+ * `Record<KnownFailureMode, ...>` annotation enforces compile-time
+ * exhaustiveness — adding a new mode to KnownFailureMode in v1.4+ will
+ * cause a type-check failure here until the planner decides on a mapping.
  *
- * Mirrors the `output()` and adapter factory style — exact-optional safe
- * (does not emit `field: undefined` properties under `exactOptionalPropertyTypes`).
- * Returns a frozen value with frozen nested objects so downstream code can
- * rely on structural immutability when canonicalizing in Phase 9.
+ * Null semantics per D-16:
+ *   - system_prompt_echo     -> null (consumer-side prompt engineering, not a sanitizer)
+ *   - hallucinated_tool_name -> null (Phase 37 tool-call validator territory)
+ *   - malformed_tool_arguments -> null (Phase 37 tool-call validator territory)
+ *   - premature_termination  -> null (consumer-side max_tokens config)
  */
-declare function contract(input?: CapabilityContractInput): CapabilityContract;
-//#endregion
-//#region src/contract/preflight.d.ts
+declare const SANITIZER_BY_FAILURE_MODE: Record<KnownFailureMode, SanitizerKey | null>;
 /**
- * Result of a single pre-flight contract evaluation against a candidate
- * capability. `reasons` is empty when `ok` is true and contains one or more
- * `RouteRejectReason` entries when `ok` is false.
+ * D-14 / D-15 — Maps a list of known failure modes through the recommendation
+ * table and filters nulls. `recommendedSanitizers` always contains real keys.
  *
- * The evaluator surfaces ALL failing reasons in a single pass — not the
- * first-failing only — so the deterministic router can aggregate per-candidate
- * rejection detail (CONTEXT.md "Pre-flight surfaces ALL failed candidates
- * with per-candidate rejection reasons").
- */
-interface ContractPreflightResult {
-  readonly ok: boolean;
-  readonly reasons: readonly RouteRejectReason[];
-}
-/**
- * Input for the pure cost estimator. Token counts come from the router's
- * existing `estimateRoute()` helper so preflight and router agree on the
- * projected output size (one source of truth — see `evaluateContractAgainstRoute`).
+ * Implementation:
+ *   - Iterates modes in input order (Set insertion order)
+ *   - Skips null entries (D-16)
+ *   - Deduplicates via Set (so repeated modes yield one key)
+ *   - Returns a readonly array (frozen via spread)
+ *
+ * Consumers use this to populate `NegotiatedCapabilities.recommendedSanitizers`.
+ * Phase 36 registers implementations under the same key ids.
  */
-interface EstimateRouteCostInput {
-  readonly capability: ModelCapability;
-  readonly estimatedInputTokens: number;
-  readonly estimatedOutputTokens: number;
+declare function getRecommendedSanitizers(modes: readonly KnownFailureMode[]): readonly SanitizerKey[];
+//#endregion
+//#region src/capabilities/negotiate.d.ts
+/**
+ * Phase 34 — SC-3 — Consumer-facing capability shape returned by
+ * `adapter.negotiateCapabilities()` and the top-level `negotiateCapabilities()`
+ * helper. Simplified relative to `ModelCapabilityProfile` (the registry
+ * profile); consumers needing the full enum (e.g., native_strict vs
+ * native_lenient) should look up the profile directly via `getCapabilityProfile`.
+ *
+ * Source values (D-09):
+ *   - "live"               — /models endpoint hit, registry profile intersected
+ *   - "registry-fallback"  — /models hit failed transiently (5xx/network/timeout),
+ *                            fell back to Phase 33 static registry (D-09)
+ *   - "registry"           — adapter intentionally has no /models endpoint
+ *                            (LM Studio, openai-compat), OR consumer-adapter
+ *                            fallback path (D-04)
+ */
+interface NegotiatedCapabilities {
+  readonly modelId: string;
+  readonly contextWindow: number;
+  readonly supports: {
+    readonly nativeToolCalling: boolean;
+    readonly structuredOutputs: boolean;
+    readonly parallelToolCalls: boolean;
+    readonly extendedThinking: boolean;
+    readonly streaming: boolean;
+  };
+  readonly knownFailureModes: readonly KnownFailureMode[];
+  readonly recommendedSanitizers: readonly SanitizerKey[];
+  readonly source: "live" | "registry-fallback" | "registry";
 }
 /**
- * Pure cost estimator. Returns `null` when pricing is unknown (so downstream
- * gates can distinguish "free / zero" from "unmeasured" per the Phase 7
- * cost-normalization decision). Uses static catalog metadata only — no probes,
- * no external pricing APIs.
+ * D-10 — Typed error thrown by `negotiateCapabilities` when the adapter's
+ * /models endpoint returns 401 or 403. Mirrors `AgentDeniedError` shape
+ * (the only existing v1.2 `class extends Error` precedent in agent/types.ts).
+ *
+ * Why throw (vs return-as-error-union):
+ *   - Auth errors indicate a broken apiKey config — it is the caller's bug
+ *   - Silently falling back would hide the misconfiguration
+ *   - `try/catch` ergonomics work cleanly with `class extends Error`
+ *   - `instanceof NegotiationAuthError` is the consumer ergonomic
+ *
+ * IMPORTANT: `NegotiationAuthError` is throwable from `negotiateCapabilities`
+ * ONLY — never from `execute()`. Auth errors from /models do NOT contaminate
+ * the request path.
+ *
+ * T-34-01-02: message field set by adapter implementations in Plans 02-04
+ * MUST NOT include the apiKey. Only adapter, modelId, and httpStatus are carried.
  */
-declare function estimateRouteCost(input: EstimateRouteCostInput): number | null;
-/** Input for the pre-flight evaluator. */
-interface EvaluateContractInput {
-  readonly capability: ModelCapability;
-  readonly estimatedInputTokens: number;
-  readonly estimatedOutputTokens: number;
+declare class NegotiationAuthError extends Error {
+  readonly kind: "negotiation-auth-failed";
+  readonly adapter: CapabilityAdapter;
+  readonly modelId: string;
+  readonly httpStatus: 401 | 403;
+  constructor(adapter: CapabilityAdapter, modelId: string, httpStatus: 401 | 403, message: string);
 }
 /**
- * Pure pre-flight evaluator. Phase 9 receipts will reuse this for deterministic
- * verdict reconstruction.
+ * Phase 34 — D-02 / D-04 — Top-level helper for capability negotiation.
  *
- * Token estimation: Phase 7 does NOT define a separate token estimator. Output-
- * token projection is the canonical responsibility of the router's existing
- * `estimateRoute()` helper (in `routing/router.ts`), which already produces an
- * `estimatedOutputTokens` value. The router passes that same value into this
- * evaluator via `EvaluateContractInput.estimatedOutputTokens`, so preflight
- * and the router always agree on the projected output size. Phase 9 receipts
- * will pin the router's estimate as the deterministic input — intentionally
- * one source of truth.
+ * Pitfall 5 (zero live-path logic): delegates verbatim to
+ * `adapter.negotiateCapabilities(modelId)` when the adapter implements it.
+ * No inflight-coalescing, no cache, no source value transformation. The
+ * adapter owns all of that.
  *
- * Reject taxonomy (Phase 7 emits three of four codes):
- *  - `contract-budget-exceeded` (CONTRACT-04 + COST-03)
- *  - `contract-modality-missing` (CONTRACT-06)
- *  - `contract-privacy-mismatch` (CONTRACT-06)
- *  - `contract-quality-floor` (reserved for Phase 12 `lattice eval`; NEVER emitted here)
+ * When the adapter has NO `negotiateCapabilities` (consumer-provided v1.2
+ * adapters, third-party adapters), falls back to the Phase 33 registry
+ * via `synthesizeNegotiatedCapabilitiesFromRegistry` with source "registry"
+ * (D-04). Consumer adapters get useful behavior out of the box without any
+ * migration code.
+ *
+ * Verifiable per Pitfall 5: grep for `new Map<` in this function body should
+ * return zero matches; LOC count of the function body is < 10 lines.
  */
-declare function evaluateContractAgainstRoute(contract: CapabilityContract | undefined, input: EvaluateContractInput): ContractPreflightResult;
-//#endregion
-//#region src/receipts/keyset.d.ts
+declare function negotiateCapabilities(adapter: ProviderAdapter, modelId: string): Promise<NegotiatedCapabilities>;
 /**
- * In-memory KeySet factory.
+ * Phase 34 — D-04 / D-09 — Synthesizes a `NegotiatedCapabilities` shape from
+ * the Phase 33 static registry. Used by:
+ *   1. The top-level helper (above) for consumer-adapter fallback (D-04).
+ *   2. Per-adapter negotiate() implementations (Plans 02-05) when /models
+ *      fails transiently (D-09, source "registry-fallback").
  *
- * Verification flow (plan 09-03):
- *   - keySet.lookup(kid) returns undefined  → VerifyError {kind: "key-not-found"}
- *   - entry.state === "revoked"             → VerifyError {kind: "key-revoked"}
- *   - entry.state === "retired"             → VerifyOk + keyState: "retired" (caller may warn)
- *   - entry.state === "active"              → VerifyOk + keyState: "active"
+ * Exported as a named export so Plans 02-05 can reuse the fallback synthesis
+ * without duplicating the mapping logic.
  *
- * Duplicate kids: last write wins (deterministic — callers control entry order).
- * Empty entries array is legal — every lookup returns undefined.
- * Returned KeySet exposes only `lookup` — no enumeration.
+ * Implementation note: the boolean derivations are intentionally minimal
+ * (heuristic, not definitive). The per-adapter negotiate() implementations
+ * in Plans 02-05 own the richer derivation from live /models data.
+ * This helper is a SAFETY NET for adapters without /models endpoints and
+ * for transient-fallback cases.
  *
- * See 09-CONTEXT.md "Key Management (UNRETROFITTABLE)".
+ * Anti-shape (documented in CONTEXT.md <specifics>): boolean `nativeToolCalling`
+ * loses the strict-vs-lenient distinction in `toolCallSurface`. Consumers
+ * needing the enum should look up the profile directly via `getCapabilityProfile`.
  */
-declare function createMemoryKeySet(entries: readonly KeyEntry[]): KeySet;
+declare function synthesizeNegotiatedCapabilitiesFromRegistry(adapter: CapabilityAdapter, modelId: string, source: "registry" | "registry-fallback"): NegotiatedCapabilities;
 //#endregion
-//#region src/receipts/sign.d.ts
-interface GeneratedEd25519KeyPair {
-  readonly privateKeyJwk: JsonWebKey;
-  readonly publicKeyJwk: JsonWebKey;
+//#region src/providers/provider.d.ts
+type CapabilityModality = "text" | "json" | "image" | "audio" | "video" | "document" | "file" | "url" | "tool";
+type ProviderTransportMode = "inline" | "json" | "url" | "base64" | "provider-upload" | "file-id" | "extracted-text" | "transcript";
+type ProviderLatencyClass = "interactive" | "batch";
+interface ProviderPricingHint {
+  /** @deprecated prefer `inputPer1kTokens` — kept for backward compatibility */
+  readonly inputCostPer1M?: number;
+  /** @deprecated prefer `outputPer1kTokens` — kept for backward compatibility */
+  readonly outputCostPer1M?: number;
+  /** Per-1000-prompt-token cost in USD. Preferred field for Phase 7+ pricing. */
+  readonly inputPer1kTokens?: number;
+  /** Per-1000-completion-token cost in USD. Preferred field for Phase 7+ pricing. */
+  readonly outputPer1kTokens?: number;
 }
-declare function generateEd25519KeyPairJwk(): Promise<GeneratedEd25519KeyPair>;
-declare function createInMemorySigner(privateKeyJwk: JsonWebKey, options: {
-  readonly kid: string;
-  readonly publicKeyJwk: JsonWebKey;
-}): ReceiptSigner;
-//#endregion
-//#region src/receipts/verify.d.ts
 /**
- * Pure receipt verifier.
+ * Normalized per-run usage at the result layer.
  *
- * Returns a typed VerifyResult — never throws across the verification
- * boundary (PITFALLS.md security: "Verifier panics on malformed receipts
- * -> DoS via crafted input"). All parsing failures become typed errors.
+ * `costUsd` is `number | null` (not optional, not `0`) so downstream
+ * consumers can distinguish "free" (`0`) from "unmeasured" (`null`) when
+ * provider pricing is unknown — see 07-CONTEXT.md "Cost Normalization & Usage".
  *
- * Decision tree (first match wins):
- *   1. decodeEnvelope throws OR signatures[] empty       -> envelope-malformed
- *   2. payload bytes are not valid JSON                  -> envelope-malformed
- *   3. body shape check fails OR version unknown literal -> version-mismatch
- *   4. body.version === undefined OR "lattice-receipt/v1"-> schema-version-too-low (CRYPTO-01)
- *   5. keySet.lookup(keyid) === undefined                -> key-not-found
- *   6. entry.state === "revoked"                         -> key-revoked
- *   7. re-canonicalized body != signed payloadBytes      -> canonicalization-mismatch
- *   8. Ed25519 verification of PAE fails                 -> signature-invalid
- *   9. body.kid !== entry.kid (defense in depth)         -> signature-invalid
- *  10. otherwise                                         -> ok + keyState
+ * Distinct from `UsageRecord` on `ProviderAttemptRecord`: `UsageRecord`
+ * is the per-attempt record, `Usage` is the per-run normalized shape
+ * surfaced on `RunSuccess` / `RunFailure`.
  */
-declare function verifyReceipt(envelope: ReceiptEnvelope, keySet: KeySet): Promise<VerifyResult>;
-//#endregion
-//#region src/results/errors.d.ts
-interface ValidationIssue {
-  readonly message: string;
-  readonly path?: readonly (string | number | symbol)[];
-}
-interface ValidationError {
-  readonly kind: "validation";
-  readonly message: string;
-  readonly output?: string;
-  readonly issues: readonly ValidationIssue[];
+interface Usage {
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly costUsd: number | null;
 }
-interface ExecutionUnavailableError {
-  readonly kind: "execution_unavailable";
-  readonly message: string;
+interface ProviderDataPolicyHints {
+  readonly privacy: readonly ("standard" | "sensitive" | "restricted")[];
+  readonly uploadRetention?: "none" | "ephemeral" | "provider-default";
+  readonly supportsNoLogging?: boolean;
+  readonly supportsNoTraining?: boolean;
 }
-interface NoRouteError {
-  readonly kind: "no_route";
-  readonly message: string;
-  readonly reasons: readonly string[];
+interface ModelCapability {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly inputModalities: readonly CapabilityModality[];
+  readonly outputModalities: readonly CapabilityModality[];
+  readonly fileTransport: readonly ProviderTransportMode[];
+  readonly contextWindow: number;
+  readonly structuredOutput: boolean;
+  readonly toolUse: boolean;
+  readonly streaming: boolean;
+  readonly pricing?: ProviderPricingHint;
+  readonly latency: ProviderLatencyClass;
+  readonly dataPolicy: ProviderDataPolicyHints;
+  readonly available?: boolean;
 }
-interface ProviderExecutionError {
-  readonly kind: "provider_execution";
-  readonly message: string;
-  readonly providerId?: string;
-  readonly modelId?: string;
-}
-interface TimeoutError {
-  readonly kind: "timeout";
-  readonly message: string;
+interface ProviderRef {
+  readonly id: string;
+  readonly kind?: "provider-ref";
 }
-/**
- * Phase 7 addition: emitted by the runtime when no candidate route can
- * satisfy the caller-supplied `CapabilityContract` (budget, modality,
- * privacy, or quality-floor invariants).
- *
- * `noRouteReasons` carries the full deterministic-router rejection list
- * so callers can inspect per-candidate detail. Phase 9 (receipts) will
- * persist this array for deterministic verdict reconstruction.
- */
-interface NoContractMatchError {
-  readonly kind: "no-contract-match";
-  readonly message: string;
-  readonly noRouteReasons: readonly RouteRejectReason[];
+interface ProviderRunRequest {
+  readonly task: string;
+  readonly artifacts: readonly ArtifactInput[];
+  readonly outputs: readonly string[];
+  readonly outputContracts?: OutputContractMap;
+  readonly policy?: unknown;
+  readonly signal?: AbortSignal;
+  readonly plan?: ExecutionPlan;
+  readonly contextPack?: ContextPack;
+  readonly providerPackaging?: ProviderPackagingPlan;
+  readonly packagedArtifacts?: readonly ArtifactRef[];
+  /**
+   * Phase 39 — opt-in prompt-cache prefix (DELEG-04). Adapters that support
+   * block-granular caching (Anthropic) hoist this to a `cache_control`-marked
+   * system content block; adapters that ignore it MUST receive the prefix
+   * folded into `task` by the caller instead (the crew dispatcher gates on
+   * `quirks.promptCachingSupported`). The field is advisory, additive, and
+   * absent for all existing callers — follows the Phase 37 `toolCalls`
+   * additive-field precedent (request/response additive fields accepted;
+   * `ProviderAdapter` METHODS frozen per INV-03).
+   */
+  readonly cacheSystemPrefix?: string;
 }
-/**
- * Phase 8 addition: emitted when a `CapabilityContract.invariants` tripwire
- * fires after the provider returned a schema-valid output. Carries the
- * `TripwireEvidence` produced by `evaluateTripwires`.
- *
- * `terminal: true` is a structural marker — combined with the `isTerminal()`
- * predicate it tells the fallback chain in `runWithConfig` to refuse retry.
- * `NoContractMatchError` does NOT carry the field (to avoid breaking Phase 7
- * callers) but `isTerminal()` still returns true for it via the kind check.
- */
-interface TripwireViolationError {
-  readonly kind: "tripwire-violated";
-  readonly message: string;
-  readonly invariantId: string;
-  readonly evidence: TripwireEvidence;
-  readonly terminal: true;
+interface ProviderGatewayMetadata {
+  readonly used: boolean;
+  readonly requestedModel?: string;
+  readonly observedModel?: string;
+  readonly fallbackModels?: readonly string[];
+  readonly policy?: Record<string, unknown>;
 }
-type LatticeRunError = ValidationError | ExecutionUnavailableError | NoRouteError | ProviderExecutionError | TimeoutError | NoContractMatchError | TripwireViolationError;
-/**
- * Returns `true` for run errors that MUST NOT be retried by the fallback
- * chain. Phase 8 covers two kinds:
- *
- *   - `tripwire-violated` — the contract's invariants rejected the output;
- *     a different provider will not change the verdict, so retry burns
- *     budget for no gain (T-08-06 in 08-02-PLAN threat register).
- *   - `no-contract-match` — no route satisfies the contract at all; the
- *     run never executed and no retry will help.
- *
- * All other error kinds return `false` and remain eligible for fallback.
- * The predicate is exported so Phase 12's eval gate and any user-side
- * retry wrappers can share one source of truth.
- */
-declare function isTerminal(error: LatticeRunError): boolean;
-//#endregion
-//#region src/providers/adapters.d.ts
-interface OpenAICompatibleProviderOptions {
-  readonly id?: string;
-  readonly model: string;
-  readonly baseUrl: string;
-  readonly apiKey?: string;
-  readonly fetch?: typeof fetch;
+interface ProviderRunResponse {
+  readonly rawOutputs: Record<string, unknown>;
+  readonly artifactRefs?: readonly (ArtifactInput | ArtifactRef)[];
   /**
-   * Phase 7 addition: caller-supplied per-1k pricing. When provided, the
-   * adapter computes `normalizedUsage.costUsd` from the API-reported token
-   * counts. When omitted, `normalizedUsage.costUsd` is `null` so downstream
-   * consumers can distinguish "unmeasured" from "free" (per 07-CONTEXT.md).
+   * @deprecated Legacy per-attempt usage shape. Phase 7+ adapters should
+   * populate `normalizedUsage` instead — Plan 04 will prefer `normalizedUsage`
+   * when wiring `RunResult.usage`. Kept here for backward compatibility with
+   * v1.0 adapters that already report this field.
    */
-  readonly pricing?: {
-    readonly inputPer1kTokens?: number;
-    readonly outputPer1kTokens?: number;
-  };
+  readonly usage?: UsageRecord;
+  /**
+   * Phase 7 normalized usage shape for `RunResult.usage`. Populated by all
+   * Phase 7+ adapters (openai, openai-compat, ai-sdk, fake). `costUsd` is
+   * `null` when pricing is unknown (per the cost-normalization decision in
+   * 07-CONTEXT.md — distinguishes "free" from "unmeasured").
+   */
+  readonly normalizedUsage?: Usage;
+  readonly toolCalls?: readonly ValidatedToolCall[];
+  readonly gateway?: ProviderGatewayMetadata;
+  readonly rawResponse?: unknown;
 }
-interface SdkLikeProviderOptions {
-  readonly id?: string;
-  readonly model: string;
-  readonly generate: (input: {
-    readonly task: string;
-    readonly outputNames: readonly string[];
-  }) => Promise<ProviderRunResponse> | ProviderRunResponse;
+interface ProviderStreamTextDeltaChunk {
+  readonly kind: "text-delta";
+  readonly output?: string;
+  readonly text: string;
 }
-declare function createOpenAICompatibleProvider(options: OpenAICompatibleProviderOptions): ProviderAdapter;
-declare function createOpenAIProvider(options: OpenAICompatibleProviderOptions): ProviderAdapter;
-declare function createAISdkProvider(options: SdkLikeProviderOptions): ProviderAdapter;
-//#endregion
-//#region src/providers/anthropic.d.ts
-/**
- * Options for {@link createAnthropicProvider}.
- *
- * Mirrors `OpenAICompatibleProviderOptions` ergonomics (Phase 7 pattern) but
- * for the Anthropic Messages API at `/v1/messages` -- which uses a top-level
- * `system` field and a `content[0].text` response shape that diverges from
- * the OpenAI Chat Completions schema (see FSB v0.9.x `extension/ai/universal-provider.js`
- * lines 280-297 + 566-573 for the production reference).
- *
- * SECURITY: `apiKey` is a runtime parameter -- do NOT hardcode or log it.
- *
- * DEFERRED (Phase 4 carryforward notes):
- *   - prompt caching   (deferred to a follow-on phase)
- *   - streaming        (deferred; this adapter is single-shot Promise -- per CONTEXT.md D-06)
- *   - tool use         (Anthropic tool_use blocks are deferred)
- *   - resume-from-eviction -- see Phase 5 (MV3-survivability adapter contract)
- *
- * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-02 + D-07: full custom adapter; preserve top-level `system`).
- */
-interface AnthropicProviderOptions {
-  readonly id?: string;
-  readonly model: string;
-  readonly apiKey: string;
-  /** Defaults to `https://api.anthropic.com`. Override for proxies. */
-  readonly baseUrl?: string;
-  /** Defaults to `2023-06-01`. Override only if the consumer has tested a newer pinned version. */
-  readonly anthropicVersion?: string;
-  readonly fetch?: typeof fetch;
-  readonly pricing?: {
-    readonly inputPer1kTokens?: number;
-    readonly outputPer1kTokens?: number;
-  };
+interface ProviderStreamOutputChunk {
+  readonly kind: "output";
+  readonly output: string;
+  readonly value: unknown;
 }
-declare function createAnthropicProvider(options: AnthropicProviderOptions): ProviderAdapter;
-//#endregion
-//#region src/providers/fake.d.ts
-interface FakeProviderOptions {
-  readonly id?: string;
-  readonly modelId?: string;
-  readonly response?: ProviderRunResponse | ((request: ProviderRunRequest) => ProviderRunResponse | Promise<ProviderRunResponse>);
-  readonly artifacts?: readonly ArtifactInput[];
+interface ProviderStreamUsageChunk {
+  readonly kind: "usage";
+  readonly usage?: UsageRecord;
+  readonly normalizedUsage?: Usage;
+}
+interface ProviderStreamGatewayChunk {
+  readonly kind: "gateway";
+  readonly gateway: ProviderGatewayMetadata;
+}
+interface ProviderStreamToolCallChunk {
+  readonly kind: "tool-call";
+  readonly toolCall: ValidatedToolCall;
+}
+interface ProviderStreamCompleteChunk {
+  readonly kind: "complete";
+  readonly rawOutputs?: Record<string, unknown>;
+  readonly artifactRefs?: readonly (ArtifactInput | ArtifactRef)[];
+  readonly usage?: UsageRecord;
+  readonly normalizedUsage?: Usage;
+  readonly gateway?: ProviderGatewayMetadata;
+  readonly toolCalls?: readonly ValidatedToolCall[];
+  readonly rawResponse?: unknown;
+}
+type ProviderStreamChunk = ProviderStreamTextDeltaChunk | ProviderStreamOutputChunk | ProviderStreamUsageChunk | ProviderStreamGatewayChunk | ProviderStreamToolCallChunk | ProviderStreamCompleteChunk;
+type ProviderStream = AsyncIterable<ProviderStreamChunk>;
+interface ProviderAdapter {
+  readonly id: string;
+  readonly kind: "provider-adapter";
+  readonly capabilities?: readonly ModelCapability[];
+  readonly execute?: (request: ProviderRunRequest) => Promise<ProviderRunResponse>;
+  readonly executeStream?: (request: ProviderRunRequest) => ProviderStream | Promise<ProviderStream>;
   /**
-   * Phase 7 addition: when provided, REPLACES the default single-capability
-   * array so callers (notably Plan 07-04's modality/privacy reject tests)
-   * can construct a fake adapter with arbitrary
-   * `inputModalities` / `outputModalities` / `dataPolicy` / `pricing`
-   * without mutating the returned adapter's readonly `capabilities` array.
-   * When omitted, the existing default capability is used.
+   * Phase 34 — D-01 — Per-adapter behavioral deviation flags. OPTIONAL on the
+   * base interface so v1.2 consumer adapters (4-field literals) continue to work
+   * without modification (non-breaking). First-party adapter factories narrow the
+   * return type to require `quirks` with the specific sub-interface for their adapter.
+   *
+   * D-03 discriminant-narrowing contract: consumers reading this field get
+   * `AdapterQuirks` autocomplete. To access adapter-specific flags, cast after
+   * an `adapter.id` discriminant check OR use the typed factory return directly.
+   * Example: `(adapter.quirks as AnthropicQuirks).promptCachingSupported`.
    */
-  readonly capabilities?: readonly ModelCapability[];
+  readonly quirks?: AdapterQuirks;
+  /**
+   * Phase 34 — D-02 — Capability negotiation via the provider's /models endpoint.
+   * OPTIONAL on the base interface (non-breaking for v1.2 consumer adapters).
+   * First-party adapters that have a /models endpoint implement this; adapters
+   * without one (LM Studio, openai-compat) fall back to the Phase 33 registry.
+   *
+   * The top-level `negotiateCapabilities(adapter, modelId)` helper in
+   * `capabilities/negotiate.ts` delegates to this method when present and
+   * synthesizes from the registry otherwise (D-04).
+   */
+  readonly negotiateCapabilities?: (modelId: string) => Promise<NegotiatedCapabilities>;
 }
-declare function createFakeProvider(options?: FakeProviderOptions): ProviderAdapter;
+type ProviderRegistryInput = readonly (ProviderRef | ProviderAdapter | string)[];
 //#endregion
-//#region src/providers/gemini.d.ts
-/**
- * Options for {@link createGeminiProvider}.
- *
- * Mirrors `OpenAICompatibleProviderOptions` ergonomics (Phase 7 pattern) but
- * for Google's Generative Language API at
- * `/v1beta/models/{model}:generateContent` -- which uses `contents[].parts[].text`
- * (NOT OpenAI's `messages[]`), `role: "model"` for assistant turns (NOT
- * `"assistant"`), authenticates via `?key=` query string, and applies a
- * 4-category `safetySettings` block at `BLOCK_NONE` thresholds (FSB convention
- * mirrored from `extension/ai/universal-provider.js:255-272`).
- *
- * SECURITY: `apiKey` is a runtime parameter -- do NOT hardcode or log it.
- *
- * DEFERRED (Phase 4 carryforward notes):
- *   - multimodal (vision) -- deferred
- *   - streaming           -- deferred (single-shot Promise per CONTEXT.md D-06)
- *   - tool use            -- deferred
- *   - resume-from-eviction -- see Phase 5 (MV3-survivability adapter contract)
- *
- * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-02 + D-07: full custom adapter; preserve role:"model").
- */
-interface GeminiProviderOptions {
-  readonly id?: string;
-  readonly model: string;
-  readonly apiKey: string;
-  /** Defaults to `https://generativelanguage.googleapis.com`. */
-  readonly baseUrl?: string;
-  readonly fetch?: typeof fetch;
-  readonly pricing?: {
-    readonly inputPer1kTokens?: number;
-    readonly outputPer1kTokens?: number;
-  };
+//#region src/plan/plan.d.ts
+type ExecutionPlanStatus = "stub" | "planned" | "no-route" | "running" | "completed" | "failed";
+type ExecutionStageKind = "analysis" | "transforms" | "context-packing" | "provider-packaging" | "tool-execution" | "execution" | "validation" | "tripwire" | "persistence" | "replay";
+type ExecutionStageStatus = "pending" | "running" | "completed" | "skipped" | "failed";
+interface ExecutionPlanStage {
+  readonly id: string;
+  readonly kind: ExecutionStageKind;
+  readonly status: ExecutionStageStatus;
+  readonly inputArtifacts?: readonly string[];
+  readonly outputArtifacts?: readonly string[];
+  readonly warnings: readonly string[];
+  readonly metadata?: Record<string, unknown>;
+}
+interface RouteRejectReason {
+  readonly code: string;
+  readonly message: string;
+}
+interface RouteCandidate {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly capability: ModelCapability;
+  readonly score: number;
+  readonly accepted: boolean;
+  readonly reasons: readonly RouteRejectReason[];
+  readonly estimates: RouteEstimates;
+}
+interface RouteEstimates {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly costUsd?: number;
+  readonly latencyMs?: number;
+}
+interface SelectedRoute {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly score: number;
+  readonly estimates: RouteEstimates;
+  readonly inputModalities: readonly CapabilityModality[];
+  readonly outputModalities: readonly CapabilityModality[];
+  readonly fileTransport: readonly ProviderTransportMode[];
+}
+interface FallbackRoute {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly score: number;
+  readonly reason: "policy-preserving-fallback";
+}
+interface RouteDecision {
+  readonly catalogVersion: string;
+  readonly selected?: SelectedRoute;
+  readonly candidates: readonly RouteCandidate[];
+  readonly rejected: readonly RouteCandidate[];
+  readonly fallbackChain: readonly FallbackRoute[];
+  readonly noRouteReasons: readonly RouteRejectReason[];
+}
+interface ContextPackPlan {
+  readonly id: string;
+  readonly tokenBudget: number;
+  readonly estimatedTokens: number;
+  readonly included: readonly ContextPackItemPlan[];
+  readonly summarized: readonly ContextPackItemPlan[];
+  readonly archived: readonly ContextPackItemPlan[];
+  readonly omitted: readonly ContextPackItemPlan[];
+  readonly warnings: readonly string[];
+}
+interface ContextPackItemPlan {
+  readonly artifactId?: string;
+  readonly sessionTurnId?: string;
+  readonly reason: string;
+  readonly estimatedTokens: number;
+  readonly trust: "developer" | "user" | "tool" | "model-summary";
+}
+interface ProviderPackagingPlan {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly artifacts: readonly ProviderPackagedArtifactPlan[];
+  readonly warnings: readonly string[];
+}
+interface ProviderPackagedArtifactPlan {
+  readonly artifactId: string;
+  readonly transport: ProviderTransportMode;
+  readonly mediaType?: string;
+  readonly lineageTransform: "provider-packaging";
+  readonly providerRequest?: ProviderPackagedArtifactRequestPlan;
+  readonly warnings: readonly string[];
+}
+type ProviderPackagedArtifactSourceType = ProviderTransportMode | "file-reference";
+interface ProviderPackagedArtifactRequestPlan {
+  readonly shape: string;
+  readonly sourceType: ProviderPackagedArtifactSourceType;
+  readonly reason: string;
+  readonly mediaType?: string;
+  readonly sizeBytes?: number;
+  readonly reference?: ProviderPackagedArtifactReferencePlan;
+}
+interface ProviderPackagedArtifactReferencePlan {
+  readonly kind: "url" | "file-id" | "file-uri" | "storage";
+  readonly metadataKey?: string;
+}
+interface ProviderAttemptRecord {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly status: "pending" | "running" | "succeeded" | "failed" | "cancelled";
+  readonly startedAt?: string;
+  readonly completedAt?: string;
+  readonly error?: string;
+  readonly usage?: UsageRecord;
+  readonly metadata?: Record<string, unknown>;
+}
+interface UsageRecord {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly totalTokens?: number;
+  readonly costUsd?: number;
+  readonly latencyMs?: number;
+}
+interface ExecutionPlan {
+  readonly id: string;
+  readonly kind: "execution-plan";
+  readonly version: 1;
+  readonly createdAt: string;
+  readonly status: ExecutionPlanStatus;
+  readonly task: string;
+  readonly outputNames: readonly string[];
+  readonly artifactRefs: readonly ArtifactRef[];
+  readonly route: RouteDecision;
+  readonly stages: readonly ExecutionPlanStage[];
+  readonly context?: ContextPackPlan;
+  readonly providerPackaging?: ProviderPackagingPlan;
+  readonly attempts: readonly ProviderAttemptRecord[];
+  readonly warnings: readonly string[];
+  readonly metadata?: Record<string, unknown>;
+}
+interface ExecutionPlanStub {
+  readonly id: string;
+  readonly kind: "plan-stub";
+  readonly createdAt: string;
+  readonly status: "stub";
+  readonly stages: readonly [];
+  readonly warnings: readonly string[];
 }
-declare function createGeminiProvider(options: GeminiProviderOptions): ProviderAdapter;
+type ResultPlan = ExecutionPlan | ExecutionPlanStub;
 //#endregion
-//#region src/providers/lm-studio.d.ts
-/**
- * Options for {@link createLmStudioProvider}.
- *
- * Thin wrapper around {@link createOpenAICompatibleProvider} pinned to
- * LM Studio's default local server URL `http://localhost:1234/v1`. Wire
- * shape is OpenAI Chat Completions. LM Studio is no-auth by convention
- * (CD-03): `apiKey` is OPTIONAL; when omitted, the underlying factory
- * sends no `Authorization` header (see
- * `lattice/packages/lattice/src/providers/adapters.ts:53` for the
- * conditional auth-header wiring).
- *
- * DEFERRED (D-16 carryforward):
- *   - latency-tail diagnostics  -- observability concern; LM Studio is
- *                                  the canary for latency tails (INV-03);
- *                                  diagnostics module deferred to a
- *                                  follow-on observability phase.
- *   - streaming                 -- deferred (single-shot per D-06).
- *   - resume-from-eviction      -- see Phase 5 (MV3-survivability adapter).
- *
- * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-03: thin wrapper; D-16: latency-tail deferred; CD-03 no-opt-out).
- */
-interface LmStudioProviderOptions extends Omit<OpenAICompatibleProviderOptions, "id" | "baseUrl" | "apiKey"> {
-  readonly id?: string;
-  /** Defaults to `http://localhost:1234/v1`. Override for non-localhost deployments. */
-  readonly baseUrl?: string;
-  /**
-   * Optional. LM Studio is no-auth by convention (CD-03 default).
-   * When provided, sent as `Authorization: Bearer <apiKey>` (matches the
-   * underlying OpenAI-compat factory). Use only for proxied LM Studio
-   * deployments that have a token gate in front.
-   */
-  readonly apiKey?: string;
+//#region src/receipts/types.d.ts
+type ContractVerdict = "success" | "tripwire-violated" | "no-contract-match" | "execution-failed" | "validation-failed";
+interface ReceiptUsageCanonical {
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly costUsd: string | null;
+}
+interface ReceiptModel {
+  readonly requested: string;
+  readonly observed: string | null;
+}
+interface ReceiptRoute {
+  readonly providerId: string;
+  readonly capabilityId: string;
+  readonly attemptNumber: number;
+}
+interface ReceiptRedaction {
+  readonly path: string;
+  readonly reason: string;
+}
+interface CapabilityReceiptBody {
+  readonly version: "lattice-receipt/v1" | "lattice-receipt/v1.1" | "lattice-receipt/v1.2" | "lattice-receipt/v1.3";
+  readonly receiptId: string;
+  readonly runId: string;
+  readonly issuedAt: string;
+  readonly kid: string;
+  readonly model: ReceiptModel;
+  readonly route: ReceiptRoute;
+  readonly modelClass?: TrainingClass;
+  readonly parentReceiptCid?: string;
+  readonly lineageMerkleRoot?: string;
+  readonly usage: ReceiptUsageCanonical;
+  readonly contractVerdict: ContractVerdict;
+  readonly contractHash: string | null;
+  readonly inputHashes: readonly string[];
+  readonly outputHash: string | null;
+  readonly redactionPolicyId: string;
+  readonly redactions: readonly ReceiptRedaction[];
+  readonly noRouteReasons?: readonly RouteRejectReason[];
+  readonly tripwireEvidence?: TripwireEvidence;
+  readonly stepName?: string;
+  readonly stepIndex?: number;
+  readonly parentStepName?: string;
+  readonly previousStepName?: string;
+  readonly sessionId?: string;
+  readonly timestamp?: string;
+}
+interface ReceiptSignature {
+  readonly keyid: string;
+  readonly sig: string;
+}
+interface ReceiptEnvelope {
+  readonly payloadType: "application/vnd.lattice.receipt+json";
+  readonly payload: string;
+  readonly signatures: readonly ReceiptSignature[];
+}
+interface ReceiptSigner {
+  readonly kid: string;
+  sign(bytes: Uint8Array): Promise<Uint8Array>;
+  readonly publicKeyJwk: JsonWebKey;
+}
+type KeyState = "active" | "retired" | "revoked";
+interface KeyEntry {
+  readonly kid: string;
+  readonly publicKeyJwk: JsonWebKey;
+  readonly state: KeyState;
+}
+interface KeySet {
+  lookup(kid: string): KeyEntry | undefined;
+}
+type VerifyErrorKind = "key-not-found" | "key-revoked" | "canonicalization-mismatch" | "signature-invalid" | "envelope-malformed" | "version-mismatch" | "schema-version-too-low";
+interface VerifyError {
+  readonly kind: VerifyErrorKind;
+  readonly message: string;
+}
+interface VerifyOk {
+  readonly ok: true;
+  readonly body: CapabilityReceiptBody;
+  readonly keyState: KeyState;
+}
+interface VerifyFail {
+  readonly ok: false;
+  readonly error: VerifyError;
 }
-declare function createLmStudioProvider(options: LmStudioProviderOptions): ProviderAdapter;
+type VerifyResult = VerifyOk | VerifyFail;
 //#endregion
-//#region src/providers/openrouter.d.ts
+//#region src/receipts/receipt.d.ts
 /**
- * Options for {@link createOpenRouterProvider}.
- *
- * Thin wrapper around {@link createOpenAICompatibleProvider} pinned to
- * OpenRouter's base URL `https://openrouter.ai/api/v1`. Wire shape is
- * OpenAI Chat Completions; no provider-specific quirks at the
- * single-shot Promise contract level.
- *
- * SECURITY: `apiKey` is a runtime parameter -- do NOT hardcode or log it.
- *
- * DEFERRED (D-17 carryforward; Phase 4 ships the named adapter as a
- * first-class OpenAI-compat wrapper):
- *   - model-routing array  -- caller supplies `model` (single id); OpenRouter's
- *                             `models: [primary, fallback, ...]` array
- *                             feature is deferred to a follow-on phase.
- *   - fallback-array       -- deferred (same phase as model-routing).
- *   - per-message routing  -- deferred.
- *   - streaming            -- deferred (single-shot per CONTEXT.md D-06).
- *   - resume-from-eviction -- see Phase 5 (MV3-survivability adapter).
+ * Public input to createReceipt. Mirrors CapabilityReceiptBody minus:
+ *   - `version` (forced to "lattice-receipt/v1.3" per Phase 46)
+ *   - `kid` (forced from signer.kid — caller cannot mismatch)
+ *   - `redactions[]` (populated by redactReceiptBody)
+ *   - `usage.costUsd` (converted to canonical string by usageToCanonical)
  *
- * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-03: thin wrapper; D-17: model-routing deferred).
+ * receiptId and issuedAt default to runtime-generated values when omitted.
+ * redactionPolicyId defaults to DEFAULT_REDACTION_POLICY_ID.
  */
-interface OpenRouterProviderOptions extends Omit<OpenAICompatibleProviderOptions, "id" | "baseUrl"> {
-  readonly id?: string;
-  /** Defaults to `https://openrouter.ai/api/v1`. Override for proxies. */
-  readonly baseUrl?: string;
+interface CreateReceiptInput {
+  readonly runId: string;
+  readonly issuedAt?: string;
+  readonly receiptId?: string;
+  readonly model: ReceiptModel;
+  readonly route: ReceiptRoute;
+  readonly modelClass?: TrainingClass;
+  readonly parentReceiptCid?: string;
+  readonly lineageMerkleRoot?: string;
+  readonly usage: Usage;
+  readonly contractVerdict: ContractVerdict;
+  readonly contractHash: string | null;
+  readonly inputHashes: readonly string[];
+  readonly outputHash: string | null;
+  readonly redactionPolicyId?: string;
+  readonly noRouteReasons?: readonly RouteRejectReason[];
+  readonly tripwireEvidence?: TripwireEvidence;
+  readonly stepName?: string;
+  readonly stepIndex?: number;
+  readonly parentStepName?: string;
+  readonly previousStepName?: string;
+  readonly sessionId?: string;
+  readonly timestamp?: string;
 }
-declare function createOpenRouterProvider(options: OpenRouterProviderOptions): ProviderAdapter;
-//#endregion
-//#region src/providers/xai.d.ts
 /**
- * Options for {@link createXaiProvider}.
+ * Build, redact, canonicalize, sign, and envelope a CapabilityReceipt.
  *
- * Thin wrapper around {@link createOpenAICompatibleProvider} pinned to
- * xAI's base URL `https://api.x.ai/v1`. The wire shape is identical to
- * OpenAI Chat Completions, with one provider-specific quirk preserved:
- * `response.usage.completion_tokens_details.reasoning_tokens` (xAI's
- * separate reasoning-token accounting; see FSB
- * `extension/ai/universal-provider.js:585-594` for the production reference).
+ * Ordering INVARIANT (09-CONTEXT.md, PITFALLS.md Pitfall #1):
+ *   redact -> canonicalize -> PAE -> sign -> encode
  *
- * SECURITY: `apiKey` is a runtime parameter -- do NOT hardcode or log it.
+ * The signed digest commits to canonicalize(redact(body)). The function
+ * structure makes any other ordering impossible to write by accident —
+ * canonicalizeReceiptBody is ONLY called on the output of redactReceiptBody.
  *
- * DEFERRED (Phase 4 carryforward notes):
- *   - tool-streaming -- deferred
- *   - streaming      -- deferred (single-shot Promise per CONTEXT.md D-06)
- *   - resume-from-eviction -- see Phase 5 (MV3-survivability adapter contract)
+ * Defense in depth:
+ *   - body.kid is assigned from signer.kid, never from input (input has no
+ *     kid field). The signed body and the envelope keyid CANNOT disagree by
+ *     construction.
+ *   - signer.kid is also written to envelope.signatures[0].keyid, so the
+ *     verifier can cross-check (Step 7 of verifyReceipt).
  *
- * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-03 + D-07: thin wrapper; reasoning_tokens quirk preserved).
+ * I-JSON guarantees: usage.costUsd is converted to string (or null) via
+ * usageToCanonical. Receipts NEVER carry raw floats in the canonical form.
  */
-interface XaiProviderOptions extends Omit<OpenAICompatibleProviderOptions, "id" | "baseUrl"> {
-  readonly id?: string;
-  /** Defaults to `https://api.x.ai/v1`. Override for proxies. */
-  readonly baseUrl?: string;
-}
-declare function createXaiProvider(options: XaiProviderOptions): ProviderAdapter;
-//#endregion
-//#region src/outputs/infer.d.ts
-type InferOutput<C> = C extends "text" ? string : C extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<C> : C extends CitationsOutputContract ? readonly CitationRef[] : C extends ArtifactRefsOutputContract ? readonly ArtifactRef[] : never;
-type InferOutputMap<T extends OutputContractMap> = { readonly [K in keyof T]: InferOutput<T[K]> };
-//#endregion
-//#region src/results/result.d.ts
-interface RunSuccess<TOutputs extends OutputContractMap> {
-  readonly ok: true;
-  readonly outputs: InferOutputMap<TOutputs>;
-  readonly artifacts: readonly ArtifactRef[];
-  readonly usage: Usage;
-  readonly plan: ResultPlan;
-  readonly events?: readonly RunEvent[];
-  /**
-   * Phase 9 — signed capability receipt issued when `LatticeConfig.signer`
-   * is configured. Undefined when no signer is set.
-   */
-  readonly receipt?: ReceiptEnvelope;
-}
-interface RunFailure {
-  readonly ok: false;
-  readonly error: LatticeRunError;
-  readonly usage: Usage;
-  readonly raw?: unknown;
-  readonly partialOutputs?: Record<string, unknown>;
-  readonly plan: ResultPlan;
-  readonly events?: readonly RunEvent[];
-  /**
-   * Phase 9 — signed capability receipt issued when `LatticeConfig.signer`
-   * is configured. Undefined when no signer is set.
-   */
-  readonly receipt?: ReceiptEnvelope;
-}
-type RunResult<TOutputs extends OutputContractMap> = RunSuccess<TOutputs> | RunFailure;
+declare function createReceipt(input: CreateReceiptInput, signer: ReceiptSigner): Promise<ReceiptEnvelope>;
 //#endregion
-//#region src/runtime/survivability.d.ts
+//#region src/contract/checkpoint.d.ts
 /**
- * MV3-survivability adapter contract -- Phase 5 (FSB v0.10.0-attempt-2).
- *
- * This module is a SIBLING of create-ai.ts (the Lattice runtime facade) and
- * a SIBLING of contract/bands.ts (the hook pipeline factory) and
- * contract/checkpoint.ts (the per-step receipt hook). It does NOT modify
- * any of them; the SurvivabilityAdapter contract is composed from those
- * surfaces by the consumer (FSB's lattice-runtime-adapter.js in Plan 05-05).
- *
- * What is the survivability problem?
- *   Some host runtimes can evict the execution context mid-flow with no
- *   synchronous shutdown signal:
- *     - Chrome MV3 service workers: evicted after 30s silence OR 5min idle.
- *     - Cloudflare Workers: evicted at end of each request unless waitUntil.
- *     - AWS Lambda: process freeze + thaw across invocations.
- *   Lattice's existing runtime (create-ai.ts) assumes the process stays
- *   live for the duration of a run. The SurvivabilityAdapter contract is
- *   the seam where a host runtime tells Lattice "here is how to serialize
- *   my state, here is how to deserialize it back, here is how to resume
- *   work after I get evicted and recreated."
- *
- * What this module SHIPS:
- *   - SurvivabilityAdapter<TState> interface (4 methods)
- *   - SerializedSnapshot type (string-encodable opaque envelope)
- *   - EvictionHook<TState> type (pre-eviction callback signature)
- *   - ResumePolicy literal-union (post-restore reconstruction verdict)
- *   - UnsubscribeFn type
- *   - createNoopSurvivabilityAdapter() reference implementation
- *
- * What this module DOES NOT ship:
- *   - chrome.storage.session integration (FSB-side; Plan 05-05).
- *   - offscreen-document message bus (FSB-side; Plan 05-04).
- *   - Auto-wiring into create-ai.ts runtime (deferred indefinitely; the
- *     contract is consumer-controlled).
- *   - Mid-API-request / mid-tool-dispatch recovery dispatcher (CONSERVATIVE
- *     recovery wiring is deferred to a follow-on FSB milestone per
- *     CONTEXT.md D-22; only the ResumePolicy taxonomy lands here).
+ * The tracer event name Lattice's checkpoint hook emits per step transition.
+ * Identical to the literal added to RunEventKind in tracing.ts.
+ */
+declare const STEP_TRANSITION_EVENT_NAME: "step.transition";
+/**
+ * Default band convention for the checkpoint hook (D-06). The caller is
+ * free to register in a different band but the documented convention is
+ * OBSERVABILITY -- between SAFETY (runs first) and EXTENSION (runs last).
+ */
+declare const DEFAULT_CHECKPOINT_BAND: Band;
+/**
+ * Per-step context the caller passes through the hook pipeline.
  *
- * Composition conventions (NOT enforced; documented for callers):
- *   D-09: onEviction hooks SHOULD register in BAND.SAFETY band on the
- *         caller's HookPipeline so they run FIRST per Phase 2 priority
- *         ordering. This module does NOT auto-register; it ships the
- *         contract only.
- *   D-10: serialize(state) MAY include the latest checkpoint receipt
- *         envelope (Phase 3 createCheckpointHook output) inside the
- *         SerializedSnapshot.payload; deserialize() reconstructs session
- *         identifiers from the v1.1 receipt body's step-marker fields
- *         (stepName, stepIndex, parentStepName, previousStepName,
- *         sessionId, timestamp). The payload is opaque to Lattice -- the
- *         host runtime defines the shape.
+ * Fields are stable identifiers (D-04 carryforward); do NOT populate with
+ * user content -- they appear cleartext in the signed receipt body.
  *
- * ResumePolicy taxonomy (CD-E resolution per attempt-1 02-04-PLAN.md):
- *   - SAFE: the snapshot was captured at a safe boundary (BEFORE_ITERATION
- *     or BEFORE_NEXT_ITERATION_SCHEDULE step markers) and can be replayed
- *     deterministically. The host runtime may re-arm the loop.
- *   - RECOVERY_AMBIGUOUS: the snapshot was captured during a tool dispatch
- *     where re-execution risk is non-zero (file write, network POST without
- *     Idempotency-Key, side-effecting browser action). Host should escalate
- *     to the user before deciding.
- *   - ON_ERROR_SW_EVICTION_MID_REQUEST: the eviction happened mid-API-call
- *     (the provider request was in flight). 6 of 7 FSB providers do NOT
- *     document Idempotency-Key headers; replay risks duplicate charges +
- *     duplicate responses. Host should treat the run as failed and surface
- *     the error to the user.
- *   - ON_ERROR_SW_EVICTION_MID_TOOL_DISPATCH: the eviction happened mid-
- *     tool-dispatch (a browser action was in progress). Re-execution risk
- *     is similar to mid-API-call but lands in a different recovery branch
- *     (the host may inspect the page state before deciding).
+ * - stepName: required. Stable identifier for this step.
+ * - stepIndex: required. Monotonically increasing ordinal; caller-owned.
+ * - parentStepName: optional. Names the enclosing step when nested.
+ * - previousStepName: optional. Names the immediately-prior step in the
+ *   linked-list timeline (D-09 linked-list threading).
+ * - timestamp: required. ISO-8601 RFC 3339.
+ */
+interface CheckpointHookContext {
+  readonly stepName: string;
+  readonly stepIndex: number;
+  readonly parentStepName?: string;
+  readonly previousStepName?: string;
+  readonly timestamp: string;
+}
+/**
+ * The factory's options.
  *
- * SerializedSnapshot is intentionally opaque + string-encodable. The
- * host runtime defines the payload shape; Lattice's only requirement
- * is that serialize() followed by deserialize() round-trips the state.
+ * - runId: required. Threaded into every receipt body + every tracer event.
+ * - tracer: optional. When omitted, the handler still mints (when signer
+ *   present) but does NOT emit a tracer event. When provided, the handler
+ *   ALWAYS emits exactly one event per invocation (independent of mint
+ *   success/failure per D-10).
+ * - signer: optional. When omitted, the handler emits a tracer event only
+ *   (no mint attempted). When provided, the handler attempts to mint via
+ *   createReceipt(...) inside a try/catch (D-07 best-effort).
+ * - sessionId: optional. Threaded into receipt body and event metadata.
+ * - model: optional. ReceiptModel descriptor for the receipt body; the
+ *   factory provides a sensible "step" default when omitted.
+ * - route: optional. ReceiptRoute descriptor for the receipt body; the
+ *   factory provides a sensible "step" default when omitted.
+ * - contractVerdict: optional. Defaults to "success" -- step transitions
+ *   are observability events, not contract evaluations.
+ */
+interface CheckpointHookOptions {
+  readonly runId: string;
+  readonly tracer?: TracerLike;
+  readonly signer?: ReceiptSigner;
+  readonly sessionId?: string;
+  readonly model?: ReceiptModel;
+  readonly route?: ReceiptRoute;
+  readonly contractVerdict?: CreateReceiptInput["contractVerdict"];
+}
+/**
+ * Build a checkpoint hook handler.
  *
- * Ed25519 receipt envelope contract (carries forward from Phase 1-3):
- *   Callers MAY embed a v1.1 ReceiptEnvelope inside SerializedSnapshot.payload
- *   for signed checkpoint round-trip. verifyReceipt against the embedded
- *   envelope MUST return result.ok === true after a serialize -> deserialize
- *   cycle (Test 12). This validates that JSON.stringify + JSON.parse over
- *   the envelope preserves the JCS-canonical body bytes used by DSSE PAE.
+ * The returned handler is suitable for registration on a HookPipeline
+ * created via createHookPipeline (see ./bands.ts). The handler does not
+ * auto-register; the caller passes it to pipeline.register(...) with the
+ * desired lifecycle event (typically AFTER_TOOL or BEFORE_TOOL) and band
+ * (typically BAND.OBSERVABILITY, exported as DEFAULT_CHECKPOINT_BAND).
  *
- * Threat model (Phase 5 CONTEXT.md security block):
- *   - PII via serialized state: callers MUST ensure SerializedSnapshot.payload
- *     contains only stable identifiers + user-controlled state the user has
- *     already consented to persist. Mirrors Phase 2 D-04 receipt-body contract
- *     (step-marker fields are stable identifiers, not free-form user input).
- *   - Snapshot tampering: the noop adapter does NOT sign the snapshot.
- *     Callers that need cryptographic integrity SHOULD embed a signed
- *     ReceiptEnvelope inside the payload + verify it on deserialize.
- *     Phase 5 ships the contract; signature wrapping is a follow-on.
+ * Per-invocation behavior:
+ *   1. Build event metadata from options + per-call context.
+ *   2. If signer is configured, attempt createReceipt(...) inside a
+ *      try/catch. On success, set metadata.receiptId + metadata.envelope.
+ *      On failure, set metadata.mintError (string from caught error).
+ *   3. If tracer is configured, emit exactly one tracer.event?.(
+ *      STEP_TRANSITION_EVENT_NAME, metadata) call.
+ *   4. Return void.
  *
- * Vocabulary separation (carries forward Phase 2 D-12 + Phase 3 D-02):
- *   ResumePolicy is the survivability vocabulary -- separate from
- *   RunEventKind (tracing) AND separate from HookLifecycleEvent (bands).
- *   The three vocabularies meet only when a host runtime composes them.
+ * NO upstream throw (D-07). NO global mutation (D-05).
  */
+declare function createCheckpointHook(options: CheckpointHookOptions): HookHandler<CheckpointHookContext>;
+//#endregion
+//#region src/contract/preflight.d.ts
 /**
- * String-encodable opaque snapshot. The host runtime defines the payload
- * shape; Lattice's only requirement is that serialize() followed by
- * deserialize() round-trips the original state object.
+ * Result of a single pre-flight contract evaluation against a candidate
+ * capability. `reasons` is empty when `ok` is true and contains one or more
+ * `RouteRejectReason` entries when `ok` is false.
  *
- * Why string-encodable? MV3's chrome.storage.session and most cross-process
- * storage layers accept structured-clone-safe values. JSON-string payloads
- * are the lowest-common-denominator that survives MV3 SW eviction +
- * Cloudflare Worker freeze + Lambda thaw. Callers MAY use a richer payload
- * shape (Uint8Array, Blob) IF the host runtime supports it; the contract
- * does not constrain payload format beyond "deserialize round-trips it".
+ * The evaluator surfaces ALL failing reasons in a single pass — not the
+ * first-failing only — so the deterministic router can aggregate per-candidate
+ * rejection detail (CONTEXT.md "Pre-flight surfaces ALL failed candidates
+ * with per-candidate rejection reasons").
  */
-interface SerializedSnapshot {
-  readonly kind: "survivability-snapshot";
-  readonly version: "lattice-survivability/v1";
-  readonly payload: string;
-  readonly capturedAt: string;
+interface ContractPreflightResult {
+  readonly ok: boolean;
+  readonly reasons: readonly RouteRejectReason[];
 }
 /**
- * Pre-eviction callback. The host runtime CAN attempt to call this hook
- * before the execution context is evicted, but MAY NOT be able to in
- * every case (MV3 eviction has no synchronous signal -- the SW just
- * stops). Callers should treat onEviction as best-effort: useful for
- * gathering final state when the eviction is announced (e.g., user-
- * initiated stop) but not load-bearing for involuntary eviction.
- *
- * The hook receives the current TState by reference. Mutations on the
- * hook side leak to the caller's state -- this is deliberate (the hook
- * is the LAST chance to update state before eviction). Callers who want
- * structuredClone semantics SHOULD wrap state in their own freeze layer.
+ * Input for the pure cost estimator. Token counts come from the router's
+ * existing `estimateRoute()` helper so preflight and router agree on the
+ * projected output size (one source of truth — see `evaluateContractAgainstRoute`).
  */
-type EvictionHook<TState> = (state: TState) => void | Promise<void>;
+interface EstimateRouteCostInput {
+  readonly capability: ModelCapability;
+  readonly estimatedInputTokens: number;
+  readonly estimatedOutputTokens: number;
+}
 /**
- * Return value of onEviction(); calling unsubscribes the hook.
- *
- * Idempotent -- calling twice has the same effect as calling once.
+ * Pure cost estimator. Returns `null` when pricing is unknown (so downstream
+ * gates can distinguish "free / zero" from "unmeasured" per the Phase 7
+ * cost-normalization decision). Uses static catalog metadata only — no probes,
+ * no external pricing APIs.
  */
-type UnsubscribeFn = () => void;
+declare function estimateRouteCost(input: EstimateRouteCostInput): number | null;
+/** Input for the pre-flight evaluator. */
+interface EvaluateContractInput {
+  readonly capability: ModelCapability;
+  readonly estimatedInputTokens: number;
+  readonly estimatedOutputTokens: number;
+}
 /**
- * Resume policy taxonomy. The host runtime calls adapter.resume(snapshot)
- * after eviction + restore; the returned policy tells the host runtime
- * how to react.
+ * Pure pre-flight evaluator. Phase 9 receipts will reuse this for deterministic
+ * verdict reconstruction.
  *
- * The 4 literal members carry forward from FSB v0.10.0-attempt-1's
- * 02-04-PLAN.md CONSERVATIVE recovery dispatch (preserved at
- * .planning/milestones/v0.10.0-attempt-1-pre-pivot/02-state-inspectability-
- * carve-out/02-04-PLAN.md). Per CONTEXT.md CD-E this is the locked union.
+ * Token estimation: Phase 7 does NOT define a separate token estimator. Output-
+ * token projection is the canonical responsibility of the router's existing
+ * `estimateRoute()` helper (in `routing/router.ts`), which already produces an
+ * `estimatedOutputTokens` value. The router passes that same value into this
+ * evaluator via `EvaluateContractInput.estimatedOutputTokens`, so preflight
+ * and the router always agree on the projected output size. Phase 9 receipts
+ * will pin the router's estimate as the deterministic input — intentionally
+ * one source of truth.
+ *
+ * Reject taxonomy (Phase 7 emits three of four codes):
+ *  - `contract-budget-exceeded` (CONTRACT-04 + COST-03)
+ *  - `contract-modality-missing` (CONTRACT-06)
+ *  - `contract-privacy-mismatch` (CONTRACT-06)
+ *  - `contract-quality-floor` (reserved for Phase 12 `lattice eval`; NEVER emitted here)
  */
-type ResumePolicy = "SAFE" | "RECOVERY_AMBIGUOUS" | "ON_ERROR_SW_EVICTION_MID_REQUEST" | "ON_ERROR_SW_EVICTION_MID_TOOL_DISPATCH";
+declare function evaluateContractAgainstRoute(contract: CapabilityContract | undefined, input: EvaluateContractInput): ContractPreflightResult;
+//#endregion
+//#region src/observability/otel.d.ts
+type OtelAttributeValue = string | number | boolean | readonly string[] | readonly number[] | readonly boolean[];
+type OtelAttributes = Record<string, OtelAttributeValue>;
+interface OtelSpanStatus {
+  readonly code: number;
+  readonly message?: string;
+}
+interface OtelSpanLike {
+  setAttribute?(key: string, value: OtelAttributeValue): unknown;
+  setAttributes?(attributes: OtelAttributes): unknown;
+  addEvent?(name: string, attributes?: OtelAttributes): unknown;
+  setStatus?(status: OtelSpanStatus): unknown;
+  recordException?(error: Error | string | Record<string, unknown>): unknown;
+  end?(endTime?: Date | number): unknown;
+}
+interface OtelTracerLike {
+  startSpan(name: string, options?: {
+    readonly attributes?: OtelAttributes;
+    readonly startTime?: Date | number;
+  }): OtelSpanLike;
+}
+type OtelContentCaptureMode = "none" | "metadata";
+interface OtelSanitizerOptions {
+  readonly contentCapture?: OtelContentCaptureMode;
+}
+interface OtelRunEventSinkOptions extends OtelSanitizerOptions {
+  readonly tracer: OtelTracerLike;
+  readonly spanName?: string;
+}
+interface OtelHttpTraceConfig {
+  readonly endpoint: string;
+  readonly headers: Record<string, string>;
+}
+interface LangfuseOtlpConfigOptions {
+  readonly baseUrl?: string;
+  readonly publicKey?: string;
+  readonly secretKey?: string;
+  readonly authString?: string;
+  readonly ingestionVersion?: string;
+  readonly headers?: Record<string, string>;
+}
+interface PhoenixOtlpConfigOptions {
+  readonly baseUrl?: string;
+  readonly endpoint?: string;
+  readonly apiKey?: string;
+  readonly projectName?: string;
+  readonly headers?: Record<string, string>;
+}
+declare function createOtelRunEventSink(options: OtelRunEventSinkOptions): RunEventSink;
+declare function sanitizeRunEventAttributes(event: RunEvent, options?: OtelSanitizerOptions): OtelAttributes;
+declare function createOtelReceiptAttributes(envelope: ReceiptEnvelope): Promise<OtelAttributes>;
+declare function createLangfuseOtlpConfig(options?: LangfuseOtlpConfigOptions): OtelHttpTraceConfig;
+declare function createPhoenixOtlpConfig(options?: PhoenixOtlpConfigOptions): OtelHttpTraceConfig;
+//#endregion
+//#region src/receipts/keyset.d.ts
 /**
- * The SurvivabilityAdapter contract. Host runtimes implement this; Lattice
- * runs against the interface.
+ * In-memory KeySet factory.
  *
- * 4 methods (D-08 locked):
- *   - serialize(state): convert in-memory state to SerializedSnapshot
- *   - deserialize(snapshot): inverse of serialize
- *   - onEviction(hook): register a best-effort pre-eviction callback
- *   - resume(snapshot): return ResumePolicy verdict for the post-restore
- *     reconstruction. The host runtime acts on the policy.
+ * Verification flow (plan 09-03):
+ *   - keySet.lookup(kid) returns undefined  → VerifyError {kind: "key-not-found"}
+ *   - entry.state === "revoked"             → VerifyError {kind: "key-revoked"}
+ *   - entry.state === "retired"             → VerifyOk + keyState: "retired" (caller may warn)
+ *   - entry.state === "active"              → VerifyOk + keyState: "active"
  *
- * Adapters are POLYMORPHIC over TState -- the host runtime parameterizes
- * the type. Lattice's vitest covers the contract surface with a noop
- * adapter where TState = Record<string, unknown> for ergonomics.
+ * Duplicate kids: last write wins (deterministic — callers control entry order).
+ * Empty entries array is legal — every lookup returns undefined.
+ * Returned KeySet exposes only `lookup` — no enumeration.
+ *
+ * See 09-CONTEXT.md "Key Management (UNRETROFITTABLE)".
  */
-interface SurvivabilityAdapter<TState> {
-  readonly kind: "survivability-adapter";
-  readonly id: string;
-  serialize(state: TState): SerializedSnapshot;
-  deserialize(snapshot: SerializedSnapshot): TState;
-  onEviction(hook: EvictionHook<TState>): UnsubscribeFn;
-  resume(snapshot: SerializedSnapshot): Promise<ResumePolicy>;
+declare function createMemoryKeySet(entries: readonly KeyEntry[]): KeySet;
+//#endregion
+//#region src/receipts/remote-signer.d.ts
+type RemoteReceiptSignerProvider = "aws-kms" | "gcp-kms" | "external-kms" | (string & {});
+type RemoteReceiptPayloadFormat = "dsse-pae";
+interface RemoteReceiptSignRequest {
+  readonly kid: string;
+  readonly publicKeyJwk: JsonWebKey;
+  readonly bytes: Uint8Array;
+  readonly payloadFormat: RemoteReceiptPayloadFormat;
+  readonly algorithm: "Ed25519";
+  readonly provider?: RemoteReceiptSignerProvider;
+  readonly keyRef?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+interface RemoteReceiptSignResult {
+  readonly signature: Uint8Array;
+}
+interface RemoteReceiptSignerOptions {
+  readonly kid: string;
+  readonly publicKeyJwk: JsonWebKey;
+  readonly provider?: RemoteReceiptSignerProvider;
+  readonly keyRef?: string;
+  readonly metadata?: Record<string, unknown>;
+  sign(request: RemoteReceiptSignRequest): Promise<Uint8Array | RemoteReceiptSignResult>;
 }
 /**
- * Factory options for the reference noop adapter.
+ * Adapt a remote signing service to Lattice's existing ReceiptSigner contract.
  *
- * - id: optional. Defaults to "noop-survivability". Useful when callers
- *   want to distinguish multiple adapter instances in test fixtures.
- * - policy: optional. Sets the default ResumePolicy returned by resume().
- *   Defaults to "SAFE" (matches noop adapter semantics: no recovery
- *   ambiguity if nothing was ever persisted).
+ * The callback receives the exact DSSE PAE bytes that createReceipt signs.
+ * Cloud-specific request construction, hashing choices, credentials, retries,
+ * and audit logging stay outside core.
  */
-interface NoopSurvivabilityAdapterOptions {
-  readonly id?: string;
-  readonly policy?: ResumePolicy;
+declare function createRemoteReceiptSigner(options: RemoteReceiptSignerOptions): ReceiptSigner;
+//#endregion
+//#region src/receipts/sign.d.ts
+interface GeneratedEd25519KeyPair {
+  readonly privateKeyJwk: JsonWebKey;
+  readonly publicKeyJwk: JsonWebKey;
 }
+declare function generateEd25519KeyPairJwk(): Promise<GeneratedEd25519KeyPair>;
+declare function createInMemorySigner(privateKeyJwk: JsonWebKey, options: {
+  readonly kid: string;
+  readonly publicKeyJwk: JsonWebKey;
+}): ReceiptSigner;
+//#endregion
+//#region src/receipts/verify.d.ts
 /**
- * Reference implementation of SurvivabilityAdapter<TState>. Records
- * eviction events but does NOT persist; serialize / deserialize round-
- * trip via JSON.stringify / JSON.parse. Analog to createFakeProvider
- * in the providers/ module -- gives Lattice's vitest a complete shape-
- * conformance target before the real (FSB-side) adapter ships in
- * Plan 05-05.
+ * Pure receipt verifier.
  *
- * Per CONTEXT.md D-11 the noop adapter ships in Lattice (not FSB)
- * because it covers the contract surface in Lattice's own test suite;
- * FSB's real chrome.storage.session-backed adapter is glue layer.
+ * Returns a typed VerifyResult — never throws across the verification
+ * boundary (PITFALLS.md security: "Verifier panics on malformed receipts
+ * -> DoS via crafted input"). All parsing failures become typed errors.
+ *
+ * Decision tree (first match wins):
+ *   1. decodeEnvelope throws OR signatures[] empty       -> envelope-malformed
+ *   2. payload bytes are not valid JSON                  -> envelope-malformed
+ *   3. body shape check fails OR version unknown literal -> version-mismatch
+ *   4. body.version === undefined OR "lattice-receipt/v1"-> schema-version-too-low (CRYPTO-01)
+ *   5. keySet.lookup(keyid) === undefined                -> key-not-found
+ *   6. entry.state === "revoked"                         -> key-revoked
+ *   7. re-canonicalized body != signed payloadBytes      -> canonicalization-mismatch
+ *   8. Ed25519 verification of PAE fails                 -> signature-invalid
+ *   9. body.kid !== entry.kid (defense in depth)         -> signature-invalid
+ *  10. otherwise                                         -> ok + keyState
  */
-declare function createNoopSurvivabilityAdapter<TState = Record<string, unknown>>(options?: NoopSurvivabilityAdapterOptions): SurvivabilityAdapter<TState>;
-//#endregion
-//#region src/tools/tools.d.ts
-interface ToolExecutionContext {
-  readonly signal?: AbortSignal;
-  readonly emit?: RunEventSink;
-}
-interface ToolDefinition<TSchema extends StandardSchemaV1 = StandardSchemaV1> {
-  readonly kind: "tool";
-  readonly name: string;
-  readonly description?: string;
-  readonly inputSchema: TSchema;
-  readonly execute: (input: StandardSchemaV1.InferOutput<TSchema>, context: ToolExecutionContext) => Promise<unknown> | unknown;
-}
-interface ToolCallResult {
-  readonly callId: string;
-  readonly toolName: string;
-  readonly artifact: ArtifactInput;
-}
-declare function defineTool<TSchema extends StandardSchemaV1>(definition: Omit<ToolDefinition<TSchema>, "kind">): ToolDefinition<TSchema>;
-declare function runTool<TSchema extends StandardSchemaV1>(tool: ToolDefinition<TSchema>, input: unknown, context?: ToolExecutionContext): Promise<ToolCallResult>;
-interface McpLikeClient {
-  readonly listTools?: () => Promise<readonly McpToolDescriptor[]> | readonly McpToolDescriptor[];
-  readonly callTool: (input: {
-    readonly name: string;
-    readonly arguments: unknown;
-  }) => Promise<unknown> | unknown;
-}
-interface McpToolDescriptor {
-  readonly name: string;
-  readonly description?: string;
-  readonly inputSchema: StandardSchemaV1;
-}
-declare function importMcpTools(client: McpLikeClient, toolNames?: readonly string[]): Promise<readonly ToolDefinition[]>;
-declare function toolArtifactRef(result: ToolCallResult): ArtifactRef;
+declare function verifyReceipt(envelope: ReceiptEnvelope, keySet: KeySet): Promise<VerifyResult>;
 //#endregion
-//#region src/agent/format-tools.d.ts
+//#region src/providers/no-public-url.d.ts
 /**
- * One turn in the running conversation.
+ * Thrown when a run with `policy.noPublicUrl: true` is about to dispatch a
+ * request whose serialized body still contains a public http(s) URL derived
+ * from `request.artifacts` (value or string metadata entry).
  *
- * `role: "tool"` is used for tool-result turns; `toolCallId` and `toolName`
- * are populated so the model can correlate the result with its prior
- * `tool_call` envelope.
+ * This is the single shared egress error class for all three adapter families
+ * (OpenAI-compatible, Anthropic, Gemini).  Callers may `instanceof`-check it.
  */
-interface ConversationTurn {
-  readonly role: "user" | "assistant" | "tool";
-  readonly content: string;
-  readonly toolCallId?: string;
-  readonly toolName?: string;
+declare class NoPublicUrlEgressError extends Error {
+  readonly providerId: string;
+  readonly artifactId: string;
+  readonly offendingUrl: string;
+  constructor(providerId: string, artifactId: string, offendingUrl: string);
 }
-type FormatToolsMode = "native" | "prompt-reencoded" | "auto";
-interface FormatToolsOptions {
+//#endregion
+//#region src/sanitizers/sanitizers.d.ts
+interface SanitizerContext {
+  readonly providerId: string;
+  readonly modelId?: string;
+  readonly outputName: string;
+}
+type SanitizerFn = (text: string, context: SanitizerContext) => string | Promise<string>;
+type SanitizeOutputOption = SanitizerFn | readonly SanitizerFn[];
+interface InternalEnvelopeOptions {
+  readonly field?: string;
+  readonly path?: string;
+  readonly schema?: StandardSchemaV1;
+}
+declare function stripReasoningTags(): SanitizerFn;
+declare function stripChatTemplateArtifacts(): SanitizerFn;
+declare function unwrapInternalEnvelope(schemaOrPath: string | InternalEnvelopeOptions | StandardSchemaV1): SanitizerFn;
+//#endregion
+//#region src/providers/adapters.d.ts
+interface OpenAICompatibleProviderOptions {
+  readonly id?: string;
+  readonly model: string;
+  readonly baseUrl: string;
+  readonly apiKey?: string;
+  readonly gateway?: GatewayPolicy;
+  readonly fetch?: typeof fetch;
   /**
-   * Tool-use protocol mode. Defaults to `"auto"`, which currently resolves
-   * to `"prompt-reencoded"` for ALL 7 providers (Phase 19 simplification —
-   * native tool_use deferred to a follow-on milestone). Reserved for
-   * forward compatibility.
+   * Phase 7 addition: caller-supplied per-1k pricing. When provided, the
+   * adapter computes `normalizedUsage.costUsd` from the API-reported token
+   * counts. When omitted, `normalizedUsage.costUsd` is `null` so downstream
+   * consumers can distinguish "unmeasured" from "free" (per 07-CONTEXT.md).
    */
-  readonly mode?: FormatToolsMode;
+  readonly pricing?: {
+    readonly inputPer1kTokens?: number;
+    readonly outputPer1kTokens?: number;
+  };
   /**
-   * Optional system prompt to prepend. Useful for setting persona /
-   * domain-specific instructions on top of the tool-use envelope.
+   * Phase 34 — D-05/D-06/D-08 — TTL for the per-instance models cache.
+   * Default 300_000ms (5 minutes). Set to 0 to disable caching.
+   * Set to Infinity for process-lifetime caching.
+   *
+   * NOTE: for createOpenAICompatibleProvider, this option is accepted for
+   * option-bag uniformity but is NOT USED — openai-compat has no /models
+   * endpoint (D-04). Document in JSDoc for consumers pointing at known servers.
    */
-  readonly system?: string;
-}
-interface FormattedToolsHandle {
+  readonly modelsCacheTtlMs?: number;
   /**
-   * Builds the single `task` string passed to `ProviderAdapter.execute()`.
-   * Encodes the conversation, available tools, and response-envelope
-   * instructions.
+   * Phase 34 — D-11 — Number of retry attempts on transient /models errors
+   * (5xx, network, timeout). Default 2. Set to 0 to disable retries.
+   *
+   * NOTE: for createOpenAICompatibleProvider, this option is accepted for
+   * option-bag uniformity but is NOT USED — openai-compat has no /models
+   * endpoint (D-04).
    */
-  readonly buildTask: (conversation: readonly ConversationTurn[]) => string;
+  readonly modelsRetryCount?: number;
   /**
-   * Parses the assistant's response text. Returns:
-   *   - `ToolUseRequest[]` when the response contains one or more tool-call
-   *     envelopes (parsed in declaration order).
-   *   - `null` when the response is a final answer (no tool-call envelopes
-   *     detected).
+   * Phase 34 — D-12 — Optional RunEventSink for capability negotiation events.
+   * When provided, emits the "capabilities.negotiation.fallback" event on
+   * transient /models errors (5xx, network, timeout).
    *
-   * The parser is forgiving: it tolerates extra prose around the JSON
-   * envelope (markdown fences, leading explanations) and the model
-   * occasionally drifting on whitespace.
+   * NOTE: for createOpenAICompatibleProvider, this option is accepted for
+   * option-bag uniformity but the event is NOT FIRED for source: "registry"
+   * (the documented happy path for openai-compat). Emitting events for the
+   * intentional no-endpoint path would produce noisy false-positives.
    */
-  readonly parseToolUse: (responseText: string) => ReadonlyArray<ToolUseRequest> | null;
+  readonly runEventSink?: RunEventSink;
   /**
-   * Returns the static system block describing available tools. Useful for
-   * tracing / logging the exact tool-description text fed to the model.
+   * Phase 36 — Optional output sanitizer pipeline. When provided, string
+   * rawOutputs are transformed in order after provider text extraction and
+   * before the adapter returns.
    */
-  readonly describeForSystem: () => string;
+  readonly sanitizeOutput?: SanitizeOutputOption;
   /**
-   * Effective mode this handle resolved to (`"prompt-reencoded"` for all
-   * v1.2 providers). Exposed for inspectability.
+   * Phase 37 — Optional returned tool-call validator. When provided, the
+   * adapter parses prompt-reencoded tool_calls envelopes and returns
+   * normalized validated calls without mutating rawOutputs or rawResponse.
    */
-  readonly mode: "prompt-reencoded";
+  readonly validateToolCalls?: ValidateToolCallsOption;
+}
+interface SdkLikeProviderOptions {
+  readonly id?: string;
+  readonly model: string;
+  readonly generate: (input: {
+    readonly task: string;
+    readonly outputNames: readonly string[];
+  }) => Promise<ProviderRunResponse> | ProviderRunResponse;
 }
 /**
- * Convert a Standard Schema to a JSON Schema-shaped descriptor suitable for
- * inclusion in an LLM tool description. Standard Schema vendors can
- * optionally expose `toJSONSchema` on their schema objects; when absent,
- * we fall back to a minimal structural description that lists the schema
- * vendor + version + a placeholder. Models tolerate placeholder schemas in
- * practice because the tool description is supplementary — what matters
- * is the envelope contract (`{tool_call: {name, args}}`).
- */
-declare function toolSchemaToJsonSchema(schema: StandardSchemaV1): unknown;
-/**
- * Builds the prompt-reencoded tool-use protocol handle for any provider.
+ * Phase 34 — D-04 / QUIRK-02 — OpenAI-compatible provider factory.
  *
- * Phase 19 ships a uniform implementation across all 7 logical providers
- * (openai, openai-compat, anthropic, gemini, xai, openrouter, lm-studio).
- * The `providerName` argument is accepted for forward compatibility but
- * does not branch the implementation in v1.2.
+ * This factory is the prototypical "intentional no remote /models endpoint"
+ * adapter per D-04. The consumer points this adapter at any OpenAI-shaped
+ * endpoint (vLLM, TGI, Ollama, custom), and the factory returns conservative
+ * defaults for the quirks block because the server could be anything.
+ *
+ * The `negotiateCapabilities` method performs NO fetch; it returns
+ * synthesizeNegotiatedCapabilitiesFromRegistry with source: "registry"
+ * (the intentional-no-endpoint signal, as distinct from "registry-fallback"
+ * which signals a transient failure). Plan 34-05 (LM Studio) reuses this
+ * same pattern.
+ *
+ * D-04 citation: "consumer adapters without a /models endpoint skip the
+ * fetch layer entirely and delegate to synthesizeNegotiatedCapabilitiesFromRegistry."
  */
-declare function formatToolsForProvider(providerName: string, tools: ReadonlyArray<ToolDefinition<StandardSchemaV1>>, options?: FormatToolsOptions): FormattedToolsHandle;
+declare function createOpenAICompatibleProvider(options: OpenAICompatibleProviderOptions): ProviderAdapter & {
+  readonly quirks: OpenAICompatQuirks;
+  readonly negotiateCapabilities: (modelId: string) => Promise<NegotiatedCapabilities>;
+};
+/**
+ * Phase 34 — QUIRK-02 / NEG-01 / NEG-02 — OpenAI provider factory.
+ *
+ * Extends the base OpenAI-compat factory with:
+ *   1. `quirks: OpenAIQuirks` — verified per RESEARCH §Q6 OpenAI vocabulary.
+ *   2. `negotiateCapabilities(modelId)` — queries OpenAI /v1/models GET with
+ *      Authorization: Bearer header; SPARSE response; intersects with Phase 33
+ *      registry for supports.* (per RESEARCH §Anti-patterns — don't assume
+ *      OpenAI /v1/models returns capability flags, it doesn't).
+ *
+ * The negotiate() pattern mirrors Plan 34-02 (Anthropic thick reference):
+ *   - Per-instance TTL cache (modelsCacheTtlMs, default 300_000ms)
+ *   - Single-flight inflight coalescing with .finally cleanup (Pitfall 4)
+ *   - Retry with [0, 200, 1000]ms backoff (modelsRetryCount, default 2)
+ *   - 401/403 throws NegotiationAuthError (D-10: no retry, no fallback, no event)
+ *   - 5xx/network/timeout falls back to registry with source: "registry-fallback"
+ *   - emitFallbackEvent fires the "capabilities.negotiation.fallback" RunEvent
+ *
+ * SECURITY (T-34-03-07): inflight Map MUST use .finally cleanup to prevent
+ * leak on rejection. Verifiable: grep `.finally` in this file.
+ */
+declare function createOpenAIProvider(options: OpenAICompatibleProviderOptions): ProviderAdapter & {
+  readonly quirks: OpenAIQuirks;
+  readonly negotiateCapabilities: (modelId: string) => Promise<NegotiatedCapabilities>;
+};
+declare function createAISdkProvider(options: SdkLikeProviderOptions): ProviderAdapter;
 //#endregion
-//#region src/agent/host.d.ts
+//#region src/providers/anthropic.d.ts
 /**
- * Snapshot shape the agent loop serializes between iterations. The full
- * shape is opaque to callers (they only see it through SerializedSnapshot
- * via the configured SurvivabilityAdapter) but it's exported so reference
- * implementations and tests can inspect the round-trip.
+ * Options for {@link createAnthropicProvider}.
+ *
+ * Mirrors `OpenAICompatibleProviderOptions` ergonomics (Phase 7 pattern) but
+ * for the Anthropic Messages API at `/v1/messages` -- which uses a top-level
+ * `system` field and a `content[0].text` response shape that diverges from
+ * the OpenAI Chat Completions schema (see FSB v0.9.x `extension/ai/universal-provider.js`
+ * lines 280-297 + 566-573 for the production reference).
+ *
+ * SECURITY: `apiKey` is a runtime parameter -- do NOT hardcode or log it.
+ *
+ * STREAMING (Phase 44): supported through native Anthropic Messages SSE events.
+ *
+ * DEFERRED (Phase 4 carryforward notes):
+ *   - prompt caching   (Phase 39: opt-in via `ProviderRunRequest.cacheSystemPrefix` —
+ *                       emitted as a cache_control-marked system block when present)
+ *   - resume-from-eviction -- see Phase 5 (MV3-survivability adapter contract)
+ *
+ * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-02 + D-07: full custom adapter; preserve top-level `system`).
  */
-interface AgentSnapshot {
-  readonly version: "agent-snapshot/v1";
-  readonly iterationIndex: number;
-  readonly conversation: readonly ConversationTurn[];
-  readonly cumulativeUsage: Usage;
-  readonly providerName: string;
-  readonly capturedAt: string;
+interface AnthropicProviderOptions {
+  readonly id?: string;
+  readonly model: string;
+  readonly apiKey: string;
+  /** Defaults to `https://api.anthropic.com`. Override for proxies. */
+  readonly baseUrl?: string;
+  /** Defaults to `2023-06-01`. Override only if the consumer has tested a newer pinned version. */
+  readonly anthropicVersion?: string;
+  readonly fetch?: typeof fetch;
+  readonly pricing?: {
+    readonly inputPer1kTokens?: number;
+    readonly outputPer1kTokens?: number;
+  };
+  /**
+   * D-08: Per-instance TTL for the /v1/models response cache (milliseconds).
+   * Default 300_000 (5 minutes). `0` disables caching (always re-fetch -- for testing).
+   * `Infinity` disables expiry (process-lifetime for the instance).
+   */
+  readonly modelsCacheTtlMs?: number;
+  /**
+   * D-11: Number of retries for transient /v1/models fetch failures (5xx, network,
+   * timeout). Default 2 (3 total attempts). `0` disables retries.
+   * Backoff schedule: [0ms, 200ms, 1000ms].
+   */
+  readonly modelsRetryCount?: number;
+  /**
+   * D-12: Optional RunEventSink for emitting `capabilities.negotiation.fallback`
+   * events when the /v1/models fetch falls back to the Phase 33 static registry.
+   * If absent, fallback emits no event (no-op). Auth errors (401/403) never emit
+   * the fallback event -- they throw `NegotiationAuthError` instead.
+   */
+  readonly runEventSink?: RunEventSink;
+  readonly sanitizeOutput?: SanitizeOutputOption;
+  readonly validateToolCalls?: ValidateToolCallsOption;
+}
+declare function createAnthropicProvider(options: AnthropicProviderOptions): ProviderAdapter & {
+  readonly quirks: AnthropicQuirks;
+  readonly negotiateCapabilities: (modelId: string) => Promise<NegotiatedCapabilities>;
+};
+//#endregion
+//#region src/providers/fake.d.ts
+interface FakeProviderOptions {
+  readonly id?: string;
+  readonly modelId?: string;
+  readonly response?: ProviderRunResponse | ((request: ProviderRunRequest) => ProviderRunResponse | Promise<ProviderRunResponse>);
+  readonly artifacts?: readonly ArtifactInput[];
+  /**
+   * Phase 7 addition: when provided, REPLACES the default single-capability
+   * array so callers (notably Plan 07-04's modality/privacy reject tests)
+   * can construct a fake adapter with arbitrary
+   * `inputModalities` / `outputModalities` / `dataPolicy` / `pricing`
+   * without mutating the returned adapter's readonly `capabilities` array.
+   * When omitted, the existing default capability is used.
+   */
+  readonly capabilities?: readonly ModelCapability[];
 }
+declare function createFakeProvider(options?: FakeProviderOptions): ProviderAdapter;
+//#endregion
+//#region src/providers/gemini.d.ts
 /**
- * Scheduler seam — controls how the agent loop yields between iterations.
+ * Options for {@link createGeminiProvider}.
  *
- * `scheduleNext(iterationIndex)` is called AFTER an AFTER_AGENT_ITERATION
- * emission and BEFORE the next iteration's BEFORE_AGENT_ITERATION. The
- * scheduler decides when to resume — synchronously (sync loop), on next
- * tick (setTimeout/queueMicrotask), via a queue (Durable Object), or any
- * other strategy.
+ * Mirrors `OpenAICompatibleProviderOptions` ergonomics (Phase 7 pattern) but
+ * for Google's Generative Language API at
+ * `/v1beta/models/{model}:generateContent` -- which uses `contents[].parts[].text`
+ * (NOT OpenAI's `messages[]`), `role: "model"` for assistant turns (NOT
+ * `"assistant"`), authenticates via `?key=` query string for execute(), and applies a
+ * 4-category `safetySettings` block at `BLOCK_NONE` thresholds (FSB convention
+ * mirrored from `extension/ai/universal-provider.js:255-272`).
  *
- * Default (noop): resolves immediately.
+ * SECURITY: `apiKey` is a runtime parameter -- do NOT hardcode or log it.
+ *
+ * STREAMING (Phase 44): supported through native `streamGenerateContent` SSE events.
+ *
+ * DEFERRED (Phase 4 carryforward notes):
+ *   - multimodal (vision) -- deferred
+ *   - resume-from-eviction -- see Phase 5 (MV3-survivability adapter contract)
+ *
+ * NOTE (Phase 34): negotiate() uses x-goog-api-key HEADER (preferred per RESEARCH §Q3).
+ * The existing execute() path uses ?key= query string -- execute() migration is out-of-scope
+ * for Phase 34 (additive only; T-34-04-01).
+ *
+ * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-02 + D-07: full custom adapter; preserve role:"model").
  */
-interface AgentScheduler {
-  scheduleNext(iterationIndex: number): Promise<void>;
+interface GeminiProviderOptions {
+  readonly id?: string;
+  readonly model: string;
+  readonly apiKey: string;
+  /** Defaults to `https://generativelanguage.googleapis.com`. */
+  readonly baseUrl?: string;
+  readonly fetch?: typeof fetch;
+  readonly pricing?: {
+    readonly inputPer1kTokens?: number;
+    readonly outputPer1kTokens?: number;
+  };
+  /**
+   * D-08: TTL for per-instance /models response cache, in milliseconds.
+   * Default: 300_000ms (5 minutes). 0 = always refetch (tests). Infinity = process-lifetime.
+   */
+  readonly modelsCacheTtlMs?: number;
+  /**
+   * D-11: Number of retries on transient /models fetch errors. Default: 2.
+   * Retry schedule: immediate + 200ms + 1000ms (3 total attempts at retryCount=2).
+   * 0 = no retries (1 attempt total).
+   */
+  readonly modelsRetryCount?: number;
+  /**
+   * D-12: Optional event sink for observability. When provided, the adapter
+   * emits a "capabilities.negotiation.fallback" RunEvent on transient /models failure.
+   * If absent, no event is emitted (silent fallback).
+   */
+  readonly runEventSink?: RunEventSink;
+  readonly sanitizeOutput?: SanitizeOutputOption;
+  readonly validateToolCalls?: ValidateToolCallsOption;
 }
 /**
- * Transport seam — controls how a provider call is dispatched.
+ * Phase 34 — D-03 / D-05..D-12 — Extended Gemini provider factory.
  *
- * `call(provider, request)` wraps the provider's `execute()` invocation.
- * Default (noop): pass-through (`provider.execute!(request)`). Cross-process
- * bridges (FSB's offscreen-document host) override to dispatch via
- * `chrome.runtime.sendMessage`.
+ * Returns a `ProviderAdapter` narrowed to expose:
+ *   - `quirks: GeminiQuirks` — static adapter capability flags
+ *   - `negotiateCapabilities(modelId)` — live /v1beta/models fetch with medium-thick
+ *     derivation (inputTokenLimit + thinking + supportedGenerationMethods from upstream)
+ *     intersected with Phase 33 registry; TTL cache + inflight coalescing + retry +
+ *     auth-throw + transient-fallback + event.
  *
- * Per the Phase 19 INV-03 parity invariant, the transport seam does NOT
- * modify the `ProviderAdapter` interface — it operates on top of the
- * existing `execute()` method.
+ * NOTE on auth strategy (T-34-04-01): negotiate() uses x-goog-api-key HEADER
+ * (preferred per RESEARCH §Q3 -- avoids leaking the key in server-side logs that
+ * capture URL query strings). The existing execute() path uses ?key= query string
+ * and is NOT changed by Phase 34 (out-of-scope migration).
  */
-interface AgentTransport {
-  call(provider: ProviderAdapter, request: ProviderRunRequest): Promise<ProviderRunResponse>;
-}
+declare function createGeminiProvider(options: GeminiProviderOptions): ProviderAdapter & {
+  readonly quirks: GeminiQuirks;
+  readonly negotiateCapabilities: (modelId: string) => Promise<NegotiatedCapabilities>;
+};
+//#endregion
+//#region src/providers/litellm.d.ts
 /**
- * Storage seam — controls how agent state persists between iterations for
- * resume after host eviction.
- *
- * Phase 20 composes this with the Phase 18 `SurvivabilityAdapter`:
- *   - The adapter serializes `AgentSnapshot` to `SerializedSnapshot` on
- *     each AFTER_AGENT_ITERATION; storage.save() persists the snapshot.
- *   - On run start, the agent loop calls storage.load(). If a non-null
- *     snapshot is returned, the adapter deserializes it; the loop resumes
- *     at the recorded iteration index.
- *   - On success, the loop calls storage.clear() so the next run starts
- *     fresh.
+ * Options for {@link createLiteLLMProvider}.
  *
- * Default (noop): save() is a no-op, load() returns null, clear() is a
- * no-op. Suitable for Node tests where eviction never occurs.
+ * Thin wrapper around {@link createOpenAICompatibleProvider} pinned to the
+ * documented local LiteLLM proxy URL. LiteLLM is treated as an
+ * OpenAI-compatible gateway over HTTP; this helper does not start, embed, or
+ * depend on a LiteLLM gateway process.
  */
-interface AgentStorage {
-  save(snapshot: SerializedSnapshot): Promise<void>;
-  load(): Promise<SerializedSnapshot | null>;
-  clear(): Promise<void>;
+interface LiteLLMProviderOptions extends Omit<OpenAICompatibleProviderOptions, "id" | "baseUrl" | "gateway"> {
+  readonly id?: string;
+  /** Defaults to `http://localhost:4000`. Override for hosted proxies or `/v1` deployments. */
+  readonly baseUrl?: string;
+  readonly gateway?: GatewayPolicy;
 }
+declare function createLiteLLMProvider(options: LiteLLMProviderOptions): ProviderAdapter & {
+  readonly quirks: LiteLLMQuirks;
+  readonly negotiateCapabilities: (modelId: string) => Promise<NegotiatedCapabilities>;
+};
+//#endregion
+//#region src/providers/lm-studio.d.ts
 /**
- * The host adapter — three optional seams, all swappable independently.
+ * Options for {@link createLmStudioProvider}.
  *
- * Callers pass `host` on `AgentIntent`. The agent runtime falls back to
- * `createNoopAgentHost()` when `intent.host` is absent (so Phase 19
- * single-shot Node usage continues to work without explicit configuration).
+ * Thin wrapper around {@link createOpenAICompatibleProvider} pinned to
+ * LM Studio's default local server URL `http://localhost:1234/v1`. Wire
+ * shape is OpenAI Chat Completions. LM Studio is no-auth by convention
+ * (CD-03): `apiKey` is OPTIONAL; when omitted, the underlying factory
+ * sends no `Authorization` header (see
+ * `lattice/packages/lattice/src/providers/adapters.ts:53` for the
+ * conditional auth-header wiring).
+ *
+ * Phase 34 additions:
+ *   - `modelsCacheTtlMs` -- Reserved for future /models discovery; LM Studio
+ *     currently has no remote /models endpoint. Accepted for option-bag
+ *     uniformity but NOT USED (D-04 intentional no-endpoint pattern).
+ *   - `runEventSink` -- Accepted for option-bag uniformity but NEVER fired
+ *     because source: "registry" is the documented happy path for LM Studio
+ *     (no event for intentional no-endpoint per RESEARCH Open Question 5).
+ *
+ * STREAMING (Phase 44): supported through the OpenAI-compatible stream path.
+ *
+ * DEFERRED (D-16 carryforward):
+ *   - latency-tail diagnostics  -- observability concern; LM Studio is
+ *                                  the canary for latency tails (INV-03);
+ *                                  diagnostics module deferred to a
+ *                                  follow-on observability phase.
+ *   - resume-from-eviction      -- see Phase 5 (MV3-survivability adapter).
+ *
+ * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-03: thin wrapper; D-16: latency-tail deferred; CD-03 no-opt-out).
  */
-interface AgentHost {
-  readonly kind: "agent-host";
-  readonly scheduler?: AgentScheduler;
-  readonly transport?: AgentTransport;
-  readonly storage?: AgentStorage;
+interface LmStudioProviderOptions extends Omit<OpenAICompatibleProviderOptions, "id" | "baseUrl" | "apiKey"> {
+  readonly id?: string;
+  /** Defaults to `http://localhost:1234/v1`. Override for non-localhost deployments. */
+  readonly baseUrl?: string;
+  /**
+   * Optional. LM Studio is no-auth by convention (CD-03 default).
+   * When provided, sent as `Authorization: Bearer <apiKey>` (matches the
+   * underlying OpenAI-compat factory). Use only for proxied LM Studio
+   * deployments that have a token gate in front.
+   */
+  readonly apiKey?: string;
 }
 /**
- * Reference implementation suitable for Node tests + the Phase 19 default
- * behavior.
+ * Phase 34 — D-04 / QUIRK-02 — LM Studio provider factory.
  *
- * - scheduler: resolves immediately (no yield between iterations).
- * - transport: pass-through to provider.execute().
- * - storage: save() / clear() are no-ops; load() always returns null.
+ * LM Studio is the prototypical "intentional no remote /models endpoint"
+ * adapter per D-04 (alongside OpenAI-compat). The factory returns conservative
+ * defaults for the quirks block because LM Studio runs LOCAL quantized models
+ * whose capabilities vary wildly by chat template + model file.
  *
- * Equivalent to passing no host at all.
+ * The `negotiateCapabilities` method performs NO fetch; it returns
+ * `synthesizeNegotiatedCapabilitiesFromRegistry` with source: "registry"
+ * (the intentional-no-endpoint signal, distinct from "registry-fallback"
+ * which signals a transient failure). Mirrors Plan 34-03 Task 2 (OpenAI-compat
+ * registry-only pattern) verbatim.
+ *
+ * D-04 citation: "consumer adapters without a /models endpoint skip the
+ * fetch layer entirely and delegate to synthesizeNegotiatedCapabilitiesFromRegistry."
+ *
+ * Open Question 5 (RESEARCH §): no event emitted for source: "registry" because
+ * this is the intentional happy path for LM Studio -- emitting a "fallback" event
+ * would produce false-positive noise for consumers monitoring the event stream.
  */
-declare function createNoopAgentHost(): AgentHost;
+declare function createLmStudioProvider(options: LmStudioProviderOptions): ProviderAdapter & {
+  readonly quirks: LmStudioQuirks;
+  readonly negotiateCapabilities: (modelId: string) => Promise<NegotiatedCapabilities>;
+};
 //#endregion
-//#region src/agent/types.d.ts
+//#region src/providers/openrouter.d.ts
 /**
- * Per-iteration record stored on `AgentSuccess.iterations` for inspectability.
+ * Options for {@link createOpenRouterProvider}.
  *
- * `toolCalls` carries content-addressed args/result hashes (sha256) so
- * downstream receipts can reference them without inlining the bodies.
+ * Thin wrapper around {@link createOpenAICompatibleProvider} pinned to
+ * OpenRouter's base URL `https://openrouter.ai/api/v1`. Wire shape is
+ * OpenAI Chat Completions; no provider-specific quirks at the
+ * single-shot Promise contract level.
  *
- * `deniedReason` is populated on iterations whose `BEFORE_AGENT_ITERATION`
- * SAFETY-band handler set `controls.deny(...)`.
- */
-interface IterationRecord {
-  readonly index: number;
-  readonly provider: string;
-  readonly promptTokens: number;
-  readonly completionTokens: number;
-  readonly costUsd: number | null;
-  readonly durationMs: number;
-  readonly toolCalls: ReadonlyArray<{
-    readonly id: string;
-    readonly name: string;
-    readonly argsHash: string;
-    readonly resultHash: string;
-  }>;
-  readonly deniedReason?: string;
-  readonly receipt?: ReceiptEnvelope;
-}
-/**
- * Input shape accepted by `ai.runAgent(intent)`.
+ * SECURITY: `apiKey` is a runtime parameter -- do NOT hardcode or log it.
  *
- * All fields except `task` and `tools` are optional. The runtime supplies
- * sensible defaults (in-process host, fresh pipeline, no signer, no tracer).
+ * STREAMING (Phase 44): supported through the OpenAI-compatible stream path.
  *
- * `TOutputs` parameterizes the final-answer schema map; defaults to a free-form
- * `{ answer: "text" }` shape when the field is omitted. Validation runs once
- * against the final assistant message (no intermediate iteration validation).
+ * DEFERRED (D-17 carryforward; Phase 4 ships the named adapter as a
+ * first-class OpenAI-compat wrapper):
+ *   - per-message routing  -- deferred.
+ *   - resume-from-eviction -- see Phase 5 (MV3-survivability adapter).
+ *
+ * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-03: thin wrapper; D-17: model-routing deferred).
  */
-interface AgentIntent<TOutputs extends OutputContractMap = OutputContractMap> {
-  readonly task: string;
-  readonly tools: ReadonlyArray<ToolDefinition<StandardSchemaV1>>;
-  readonly host?: AgentHost;
+interface OpenRouterProviderOptions extends Omit<OpenAICompatibleProviderOptions, "id" | "baseUrl"> {
+  readonly id?: string;
+  /** Defaults to `https://openrouter.ai/api/v1`. Override for proxies. */
+  readonly baseUrl?: string;
   /**
-   * Phase 20 (v1.2): when the agent loop resumes from a host.storage snapshot,
-   * the configured SurvivabilityAdapter handles the serialize/deserialize
-   * round-trip. When absent, runtime defaults to
-   * `createNoopSurvivabilityAdapter<AgentSnapshot>()`.
+   * D-08: TTL for per-instance /models response cache, in milliseconds.
+   * Default: 300_000ms (5 minutes). 0 = always refetch (tests). Infinity = process-lifetime.
    */
-  readonly survivabilityAdapter?: SurvivabilityAdapter<AgentSnapshot>;
-  readonly contract?: CapabilityContract;
-  readonly policy?: PolicySpec;
-  readonly outputs?: TOutputs;
-  readonly pipeline?: HookPipeline;
-  readonly signer?: ReceiptSigner;
-  readonly tracer?: TracerLike;
+  readonly modelsCacheTtlMs?: number;
   /**
-   * When `false`, the runtime will NOT auto-register `createCheckpointHook`
-   * even if `signer` is provided. Callers who want full manual control over
-   * receipt minting set this to `false` and register their own hook.
-   * Defaults to `true` (auto-register when signer present).
+   * D-11: Number of retries on transient /models fetch errors. Default: 2.
+   * Retry schedule: immediate + 200ms + 1000ms (3 total attempts at retryCount=2).
+   * 0 = no retries (1 attempt total).
    */
-  readonly autoRegisterCheckpoint?: boolean;
-}
+  readonly modelsRetryCount?: number;
+  /**
+   * D-12: Optional event sink for observability. When provided, the adapter
+   * emits a "capabilities.negotiation.fallback" RunEvent on transient /models failure.
+   * If absent, no event is emitted (silent fallback).
+   */
+  readonly runEventSink?: RunEventSink;
+  /**
+   * Ordered OpenRouter model fallback candidates. The primary `model` remains
+   * the Lattice-selected route; these candidates serialize as OpenRouter's
+   * top-level `models` request field when non-empty.
+   */
+  readonly fallbackModels?: readonly string[];
+}
+/**
+ * Phase 34 — D-03 / D-05..D-12 — Extended OpenRouter provider factory.
+ *
+ * Returns a `ProviderAdapter` narrowed to expose:
+ *   - `quirks: OpenRouterQuirks` — static adapter capability flags (8 booleans)
+ *   - `negotiateCapabilities(modelId)` — live /api/v1/models fetch with rich /models
+ *     intersection (supported_parameters -> nativeToolCalling + structuredOutputs,
+ *     top_provider.context_length -> contextWindow) intersected with Phase 33 registry
+ *     for knownFailureModes + recommendedSanitizers.
+ *
+ * CRITICAL for ANCHOR CASE STUDY (session_1780792387779):
+ *   negotiate("openai/gpt-oss-120b:free") MUST resolve to:
+ *     - result.knownFailureModes.includes("internal_envelope_leak") -> TRUE
+ *     - result.recommendedSanitizers.includes("unwrapInternalEnvelope") -> TRUE
+ *     - result.source === "live" -> TRUE
+ *   This proves: live-fetch -> id suffix-strip via stripOpenRouterVariant
+ *   -> registry intersection -> getRecommendedSanitizers derivation.
+ *
+ * Anti-pattern (RESEARCH §Anti-pattern, lines 534-535):
+ *   The /api/v1/models endpoint is UNAUTHENTICATED (public discovery surface verified
+ *   Phase 33). Do NOT send Authorization Bearer to this endpoint -- it is NOT required
+ *   and would add unnecessary API key exposure surface in transit logs.
+ */
+declare function createOpenRouterProvider(options: OpenRouterProviderOptions): ProviderAdapter & {
+  readonly quirks: OpenRouterQuirks;
+  readonly negotiateCapabilities: (modelId: string) => Promise<NegotiatedCapabilities>;
+};
+//#endregion
+//#region src/providers/xai.d.ts
 /**
- * Success result returned by `ai.runAgent` when the loop reaches a final
- * answer and (when `outputs` is declared) the final answer validates.
+ * Options for {@link createXaiProvider}.
  *
- * `iterations[]` records every iteration that ran — including the one that
- * produced the final answer. `receipt` is the outermost receipt minted at
- * loop close when `signer` is configured (separate from per-iteration
- * receipts on `iterations[i].receipt`).
+ * Thin wrapper around {@link createOpenAICompatibleProvider} pinned to
+ * xAI's base URL `https://api.x.ai/v1`. The wire shape is identical to
+ * OpenAI Chat Completions, with one provider-specific quirk preserved:
+ * `response.usage.completion_tokens_details.reasoning_tokens` (xAI's
+ * separate reasoning-token accounting; see FSB
+ * `extension/ai/universal-provider.js:585-594` for the production reference).
+ *
+ * SECURITY: `apiKey` is a runtime parameter -- do NOT hardcode or log it.
+ *
+ * STREAMING (Phase 44): supported through the OpenAI-compatible stream path.
+ *
+ * DEFERRED (Phase 4 carryforward notes):
+ *   - tool-streaming -- deferred
+ *   - resume-from-eviction -- see Phase 5 (MV3-survivability adapter contract)
+ *
+ * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-03 + D-07: thin wrapper; reasoning_tokens quirk preserved).
+ *
+ * Phase 34 additions:
+ *   - `modelsCacheTtlMs?` — D-05/D-06/D-08; default 300_000ms; 0 disables; Infinity = process-lifetime
+ *   - `modelsRetryCount?` — D-11; default 2; 0 disables retry
+ *   - `runEventSink?`     — D-12; fires "capabilities.negotiation.fallback" on transient errors
  */
-interface AgentSuccess<TOutputs extends OutputContractMap = OutputContractMap> {
-  readonly kind: "success";
-  readonly output: InferOutputMap<TOutputs>;
-  readonly usage: Usage;
-  readonly iterations: ReadonlyArray<IterationRecord>;
-  readonly receipt?: ReceiptEnvelope;
+interface XaiProviderOptions extends Omit<OpenAICompatibleProviderOptions, "id" | "baseUrl"> {
+  readonly id?: string;
+  /** Defaults to `https://api.x.ai/v1`. Override for proxies. */
+  readonly baseUrl?: string;
 }
 /**
- * Failure kinds specific to the agent loop. v1.1 `LatticeRunError.kind`
- * values remain valid (provider errors, no-contract-match, validation-failed,
- * tripwire-violated) and are reused verbatim. Phase 19 adds three
- * agent-specific kinds.
- */
-type AgentFailureKind = LatticeRunError["kind"] | "agent-iteration-denied" | "agent-max-iterations" | "agent-wall-time-exceeded";
-/**
- * Failure result returned by `ai.runAgent`. Discriminates via `kind`.
+ * Phase 34 — QUIRK-02 / NEG-01 / NEG-02 — xAI provider factory.
  *
- * `iterations[]` carries any iterations that completed before the failure
- * (empty if the failure occurred pre-iteration). For `agent-iteration-denied`,
- * the failing iteration is the LAST entry and carries `deniedReason`.
+ * Extends the base OpenAI-compat execution wrapper with:
+ *   1. `quirks: XaiQuirks` — verified per RESEARCH §Q6 xAI vocabulary.
+ *   2. `negotiateCapabilities(modelId)` — queries xAI /v1/models GET with
+ *      Authorization: Bearer header; LENIENT-PARSE sparse OpenAI-shaped
+ *      response; intersects with Phase 33 registry for supports.*.
+ *
+ * CITED: RESEARCH §Q4 (INFERRED) — xAI /v1/models shape is undocumented;
+ * assumed OpenAI-compatible based on the chat completions wire format.
+ *
+ * CITED: RESEARCH §A1 — Pitfall 1 lenient parse: if xAI publishes a
+ * different /models shape, only the parsing logic updates; the contract
+ * (source values, NegotiatedCapabilities shape) holds.
+ *
+ * The negotiate() pattern mirrors Plan 34-02 (Anthropic thick reference):
+ *   - Per-instance TTL cache (modelsCacheTtlMs, default 300_000ms)
+ *   - Single-flight inflight coalescing with .finally cleanup (Pitfall 4)
+ *   - Retry with [0, 200, 1000]ms backoff (modelsRetryCount, default 2)
+ *   - 401/403 throws NegotiationAuthError with adapter: "xai" (D-10)
+ *   - 5xx/network/timeout falls back to registry + emits fallback event
+ *
+ * SECURITY (T-34-03-07): inflight Map MUST use .finally cleanup to prevent
+ * leak on rejection. Verifiable: grep `.finally` in this file.
  */
-interface AgentFailure {
-  readonly kind: AgentFailureKind;
+declare function createXaiProvider(options: XaiProviderOptions): ProviderAdapter & {
+  readonly quirks: XaiQuirks;
+  readonly negotiateCapabilities: (modelId: string) => Promise<NegotiatedCapabilities>;
+};
+//#endregion
+//#region src/providers/streaming.d.ts
+interface CollectStreamOptions {
+  readonly defaultOutput?: string;
+}
+declare function collectStream(stream: ProviderStream, options?: CollectStreamOptions): Promise<ProviderRunResponse>;
+//#endregion
+//#region src/results/result.d.ts
+interface RunSuccess<TOutputs extends OutputContractMap> {
+  readonly ok: true;
+  readonly outputs: InferOutputMap<TOutputs>;
+  readonly artifacts: readonly ArtifactRef[];
   readonly usage: Usage;
-  readonly iterations: ReadonlyArray<IterationRecord>;
-  readonly reason?: string;
-  readonly cause?: unknown;
+  readonly plan: ResultPlan;
+  readonly events?: readonly RunEvent[];
+  readonly gateway?: ProviderGatewayMetadata;
+  /**
+   * Phase 9 — signed capability receipt issued when `LatticeConfig.signer`
+   * is configured. Undefined when no signer is set.
+   */
   readonly receipt?: ReceiptEnvelope;
 }
-/**
- * Discriminated union returned by `ai.runAgent`.
- */
-type AgentResult<TOutputs extends OutputContractMap = OutputContractMap> = AgentSuccess<TOutputs> | AgentFailure;
-/**
- * Typed error raised when a SAFETY-band handler sets `controls.deny(reason)`
- * during `BEFORE_AGENT_ITERATION`. Carries `terminal: true` semantics to
- * align with v1.1 `TripwireViolationError`: the failure is NOT retried by
- * the fallback chain.
- *
- * Surfaced via `AgentFailure { kind: "agent-iteration-denied", reason, ... }`
- * — callers can also catch the typed error if they prefer.
- */
-declare class AgentDeniedError extends Error {
-  readonly kind: "agent-iteration-denied";
-  readonly terminal: true;
-  readonly reason: string;
-  readonly iterationIndex: number;
-  constructor(reason: string, iterationIndex: number);
-}
-/**
- * Returned by `formatToolsForProvider` (Phase 19 Plan 19-03). Re-exported
- * here for convenience; the canonical declaration lives in format-tools.ts.
- */
-interface ToolUseRequest {
-  readonly id: string;
-  readonly name: string;
-  readonly args: unknown;
+interface RunFailure {
+  readonly ok: false;
+  readonly error: LatticeRunError;
+  readonly usage: Usage;
+  readonly raw?: unknown;
+  readonly partialOutputs?: Record<string, unknown>;
+  readonly plan: ResultPlan;
+  readonly events?: readonly RunEvent[];
+  readonly gateway?: ProviderGatewayMetadata;
+  /**
+   * Phase 9 — signed capability receipt issued when `LatticeConfig.signer`
+   * is configured. Undefined when no signer is set.
+   */
+  readonly receipt?: ReceiptEnvelope;
 }
+type RunResult<TOutputs extends OutputContractMap> = RunSuccess<TOutputs> | RunFailure;
 //#endregion
 //#region src/storage/storage.d.ts
 interface ArtifactStore {
@@ -1994,6 +2980,88 @@ interface NormalizedLatticeConfig {
   readonly signer?: ReceiptSigner;
 }
 //#endregion
+//#region src/agent/crew/agent-spec.d.ts
+/**
+ * Crew member specification. A literal sibling of `ToolDefinition`
+ * discriminated by `kind: "agent"` (D-03).
+ */
+interface AgentSpec {
+  readonly kind: "agent";
+  readonly id: string;
+  readonly intent: string;
+  readonly tools: ReadonlyArray<ToolDefinition<StandardSchemaV1>>;
+  readonly childAgents?: ReadonlyArray<AgentSpec>;
+  readonly summaryReturnSchema: StandardSchemaV1;
+  /** Optional per-agent sub-budget (D-07). */
+  readonly contract?: CapabilityContract;
+}
+/**
+ * Factory for `AgentSpec` values. Mirrors `defineTool` exactly: spread
+ * preserves input identity (no cloning, no mutation) and absent optional
+ * members stay absent (`exactOptionalPropertyTypes`-safe).
+ */
+declare function defineAgent(definition: Omit<AgentSpec, "kind">): AgentSpec;
+//#endregion
+//#region src/agent/crew/crew-policy.d.ts
+/** Per-adapter rate-limit override (keyed by `adapter.id` in `limits`). */
+interface CrewRateLimitOverride {
+  readonly requestsPerMinute?: number;
+  readonly tokensPerMinute?: number;
+}
+/** Crew-level policy contract (D-06, D-11, D-16). */
+interface CrewPolicy {
+  /** Crew-level shared budget pool — `BudgetInvariant` reused verbatim. */
+  readonly budget?: BudgetInvariant;
+  readonly maxTotalIterations?: number;
+  readonly maxIterationsPerAgent?: number;
+  /** Forward-compat field; the v1.3 runtime rejects values > 1 (D-11). */
+  readonly maxConcurrentChildren?: number;
+  /** Delegation depth cap; defaults to 1 (parent→child only, D-05). */
+  readonly maxDepth?: number;
+  /** Per-adapter-id rate-limit overrides (D-16). */
+  readonly limits?: Readonly<Record<string, CrewRateLimitOverride>>;
+  /** "managed" (default) wraps transports in the rate-limit group; "unmanaged" skips it. */
+  readonly coordination?: "managed" | "unmanaged";
+}
+//#endregion
+//#region src/agent/crew/run-crew.d.ts
+interface RunAgentCrewOptions {
+  readonly root: AgentSpec;
+  readonly hosts: {
+    readonly childHost: AgentHost;
+  };
+  readonly policy?: CrewPolicy;
+  /** Crew-level signer threaded into member loops and completion receipts. */
+  readonly signer?: ReceiptSigner;
+  /** Crew-level tracer threaded into member loops. */
+  readonly tracer?: TracerLike;
+  /** Crew-level hook pipeline threaded into member loops. */
+  readonly pipeline?: HookPipeline;
+}
+interface CrewAgentResult {
+  readonly id: string;
+  readonly usage: Usage;
+  readonly iterations: number;
+  readonly receiptCids: readonly string[];
+}
+interface CrewResult {
+  /** Parent result, with parent output untouched on success. */
+  readonly result: AgentResult;
+  /** Per-agent accounting records, including root parent and completed children. */
+  readonly perAgent: ReadonlyArray<CrewAgentResult>;
+  /** Crew aggregate usage: parent total + sum(child totals), no double-counting. */
+  readonly usage: Usage;
+  /** Total iterations across every recorded agent. */
+  readonly totalIterations: number;
+  /** All crew completion receipts, including the crew-root envelope. */
+  readonly receipts: ReadonlyArray<ReceiptEnvelope>;
+  readonly crewRootCid?: string;
+}
+/**
+ * Execute a crew rooted at `options.root`.
+ */
+declare function runAgentCrew(options: RunAgentCrewOptions, config?: LatticeConfig): Promise<CrewResult>;
+//#endregion
 //#region src/runtime/create-ai.d.ts
 interface RuntimeOverrides {
   readonly provider?: string;
@@ -2041,12 +3109,21 @@ interface AI {
    * Phase 19 (v1.2): single-agent execution loop. Drives multiple provider
    * iterations under one call, dispatching tool requests between iterations.
    * Composes with the v1.2 hook pipeline (SAFETY-band veto, OBSERVABILITY-band
-   * checkpoint receipts) and the v1.1 capability receipts (when
+   * checkpoint receipts) and the v1.2 capability receipts (when
    * `intent.signer` is provided + `intent.autoRegisterCheckpoint !== false`).
    *
    * See `packages/lattice/src/agent/runtime.ts` for orchestration details.
    */
   runAgent<const TOutputs extends OutputContractMap>(intent: AgentIntent<TOutputs>): Promise<AgentResult<TOutputs>>;
+  /**
+   * Phase 39 (v1.3): opt-in multi-agent crew execution. Runs a literal
+   * `AgentSpec` tree through the existing single-agent loop plus the crew
+   * dispatcher, with shared budget/rate-limit coordination and chained
+   * completion receipts.
+   *
+   * See `packages/lattice/src/agent/crew/run-crew.ts` for orchestration details.
+   */
+  runAgentCrew(options: RunAgentCrewOptions): Promise<CrewResult>;
 }
 declare function createAI(config?: LatticeConfig): AI;
 //#endregion
@@ -2138,6 +3215,10 @@ declare function materializeReplayEnvelope<TOutputs extends OutputContractMap =
  * calling Promise), direct transport (provider.execute()), and in-memory
  * transcript (the `conversation` array). Phase 20 promotes scheduler /
  * transport / storage to the pluggable `AgentHost` adapter.
+ *
+ * Phase 39: `runAgent` is a thin public wrapper over `runAgentInternal`
+ * with no internal options — the public signature and behavior are
+ * unchanged.
  */
 declare function runAgent<TOutputs extends OutputContractMap = OutputContractMap>(intent: AgentIntent<TOutputs>, config?: LatticeConfig): Promise<AgentResult<TOutputs>>;
 //#endregion
@@ -2299,6 +3380,131 @@ declare function createPermissionGuardHook(context: PermissionContext): HookHand
  */
 declare function permissionGuardRegisterOptions(): RegisterOptions;
 //#endregion
+//#region src/agent/infra/rate-limit-group.d.ts
+interface RateLimitGroupOptions {
+  /** Requests per minute. Defaults to 50 (Anthropic Tier 1). */
+  readonly requestsPerMinute?: number;
+  /** Input tokens per minute. Defaults to 30_000 (Anthropic Tier 1). */
+  readonly tokensPerMinute?: number;
+  /** Injectable clock for tests (defaults to `Date.now`). */
+  readonly now?: () => number;
+}
+interface RateLimitLease {
+  /**
+   * Reconcile the reservation against actual usage. Refunds
+   * `estimate - actual.promptTokens` to the token bucket when positive,
+   * debits the difference when negative. Idempotent — only the first call
+   * has an effect. Requests are never refunded.
+   */
+  release(actual: {
+    promptTokens: number;
+  }): void;
+}
+interface RateLimitGroup {
+  readonly kind: "rate-limit-group";
+  /**
+   * Reserve 1 request + `estimate.inputTokens` tokens. Resolves immediately
+   * when both dimensions have capacity; otherwise the caller waits (FIFO)
+   * until continuous drain refills the deficit.
+   */
+  acquire(estimate: {
+    inputTokens: number;
+  }): Promise<RateLimitLease>;
+}
+declare function createRateLimitGroup(options?: RateLimitGroupOptions): RateLimitGroup;
+/**
+ * Wrap an `AgentTransport` so every provider call is gated through `group`.
+ *
+ * Every transport wrapped with the SAME group instance shares one bucket —
+ * `runAgentCrew` (39-06) wraps parent + child hosts with one shared group per
+ * adapter instance, structurally guaranteeing crew-wide coordination (D-13).
+ * `ProviderAdapter` is never modified (INV-03 parity invariant intact).
+ *
+ * - `inner` provided → dispatch nests through `inner.call(provider, request)`,
+ *   composing with consumer transports (e.g. cross-process bridges).
+ * - `inner` undefined → falls through to `provider.execute(request)`, guarded
+ *   the same way as `createNoopAgentHost` (error names the provider id only).
+ *
+ * Release policy:
+ * - Success → release with `normalizedUsage.promptTokens`; when usage is
+ *   missing or non-finite, fall back to the estimate (no NaN arithmetic —
+ *   the `costUsd: null` "unmeasured" discipline analog).
+ * - Throw → release with the ORIGINAL estimate (burn — no refund; the
+ *   provider may have consumed quota despite the error) and rethrow the
+ *   same error unchanged. Request objects and headers are never serialized
+ *   into error paths.
+ */
+declare function withRateLimit(group: RateLimitGroup, inner?: AgentTransport): AgentTransport;
+//#endregion
+//#region src/receipts/cid.d.ts
+/**
+ * Derive the content-addressed CID of a receipt envelope.
+ *
+ * Returns `sha256:<hex>` where `<hex>` is the 64-char lowercase SHA-256
+ * digest of the decoded DSSE payload bytes. No KeySet, signer, or other
+ * key material is required — callers chaining receipts (parentReceiptCid)
+ * compute this from the parent envelope alone.
+ */
+declare function receiptCid(envelope: ReceiptEnvelope): Promise<string>;
+//#endregion
+//#region src/realtime/realtime.d.ts
+declare const REALTIME_DIRECTION_SUPPORT_LEVEL: "direction-only";
+type RealtimeSupportLevel = typeof REALTIME_DIRECTION_SUPPORT_LEVEL;
+type RealtimeProviderKind = "openai-realtime" | "gemini-live";
+type RealtimeTransportKind = "websocket" | "webrtc" | "sip";
+type RealtimeSessionMode = "voice-agent" | "transcription" | "translation" | "live-multimodal";
+type RealtimeInputModality = "text" | "audio" | "image" | "video";
+type RealtimeOutputModality = "text" | "audio" | "tool";
+type RealtimeCheckpointKind = "session.start" | "client.frame" | "server.frame" | "session.summary" | "session.close";
+interface OpenAIRealtimeTarget {
+  readonly provider: "openai-realtime";
+  readonly model: string;
+  readonly transport: RealtimeTransportKind;
+  readonly endpoint: "/v1/realtime" | "/v1/realtime/translations" | "/v1/realtime/transcription_sessions";
+}
+interface GeminiLiveTarget {
+  readonly provider: "gemini-live";
+  readonly model: string;
+  readonly transport: "websocket";
+  readonly endpoint: "wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent";
+  readonly preview: true;
+}
+type RealtimeProviderTarget = OpenAIRealtimeTarget | GeminiLiveTarget;
+interface RealtimeSessionSpec {
+  readonly kind: "realtime-session-spec";
+  readonly supportLevel: RealtimeSupportLevel;
+  readonly sessionId: string;
+  readonly target: RealtimeProviderTarget;
+  readonly mode: RealtimeSessionMode;
+  readonly inputModalities: readonly RealtimeInputModality[];
+  readonly outputModalities: readonly RealtimeOutputModality[];
+  readonly artifactRefs?: readonly ArtifactRef[];
+  readonly policy?: PolicySpec;
+  readonly checkpointing?: RealtimeCheckpointingSpec;
+}
+interface RealtimeCheckpointingSpec {
+  readonly receiptThreading: "step-linked-list";
+  readonly summaryCheckpoints: "manual" | "session-close" | "interval";
+  readonly note: "direction-only";
+}
+interface RealtimeCheckpointInput {
+  readonly sessionId: string;
+  readonly provider: RealtimeProviderKind;
+  readonly checkpoint: RealtimeCheckpointKind;
+  readonly stepIndex: number;
+  readonly timestamp?: string;
+  readonly parentStepName?: string;
+  readonly previousStepName?: string;
+}
+interface RealtimeReceiptDescriptors {
+  readonly sessionId: string;
+  readonly model: ReceiptModel;
+  readonly route: ReceiptRoute;
+}
+declare function createRealtimeCheckpointContext(input: RealtimeCheckpointInput): CheckpointHookContext;
+declare function createRealtimeReceiptDescriptors(spec: RealtimeSessionSpec): RealtimeReceiptDescriptors;
+declare function realtimeStepName(provider: RealtimeProviderKind, checkpoint: RealtimeCheckpointKind): string;
+//#endregion
 //#region src/agent/eval.d.ts
 /**
  * Summary of an agent run sufficient for regression analysis. Callers
@@ -2353,7 +3559,62 @@ interface MemoryArtifactStoreOptions {
 declare function createMemoryArtifactStore(options?: MemoryArtifactStoreOptions): ArtifactStore;
 //#endregion
 //#region src/version.d.ts
-declare const latticeVersion = "0.0.0";
+declare const latticeVersion = "1.4.0";
+//#endregion
+//#region src/capabilities/lookup.d.ts
+/**
+ * Strip the OpenRouter variant suffix (`:free` or `:thinking`) from an
+ * OpenRouter-shaped id (`vendor/model:variant`). Other adapter id shapes
+ * pass through verbatim — does not, for example, alter
+ * `anthropic:claude-opus-4` (direct-adapter canonical key) or
+ * `openai/gpt-4o:beta` (unrecognized variant per Pitfall 4).
+ *
+ * Exported because Phase 34 (adapter quirks) and Phase 36 (output
+ * sanitizers) need the same normalization. Phase 33 D-11 scope.
+ */
+declare function stripOpenRouterVariant(id: string): string;
+/**
+ * D-09 strict lookup — return the capability profile for the exact
+ * `${adapter}:${modelId}` canonical key. Returns `undefined` if the key
+ * is not registered. No fuzzy matching — use `findCapabilityProfile`
+ * for that.
+ *
+ * Examples:
+ *   getCapabilityProfile("openrouter:openai/gpt-oss-120b") -> profile
+ *   getCapabilityProfile("anthropic:claude-opus-4")        -> profile
+ *   getCapabilityProfile("not-a-real-key")                  -> undefined
+ *
+ * The lookup is case-sensitive on the canonical key. Threat T-33-02-01
+ * mitigation: backing store is `Map<string, ModelCapabilityProfile>`,
+ * not a plain object literal, so `__proto__` and other prototype-chain
+ * keys are safe (Map uses SameValueZero, not property lookup).
+ */
+declare function getCapabilityProfile(canonicalKey: string): ModelCapabilityProfile | undefined;
+/**
+ * D-10 fuzzy lookup — strip the OpenRouter variant suffix (if any) and
+ * return ALL matching profiles across every adapter, in deterministic
+ * order: direct adapters first (anthropic, openai, gemini, xai,
+ * openai-compat, lm-studio), then OpenRouter.
+ *
+ * Useful for pre-routing capability inspection where the adapter has
+ * not yet been chosen — the consumer can iterate the returned list
+ * and pick the first compatible one. Returns `[]` when no match is
+ * found across any adapter.
+ *
+ * Suffix-strip is OpenRouter-shape-only per D-11. Direct-adapter ids
+ * pass through verbatim:
+ *   findCapabilityProfile("openai/gpt-oss-120b:free")
+ *     -> [openrouter:openai/gpt-oss-120b]
+ *   findCapabilityProfile("claude-opus-4")
+ *     -> [anthropic:claude-opus-4, ...]   (no suffix-strip)
+ */
+declare function findCapabilityProfile(id: string): ModelCapabilityProfile[];
+//#endregion
+//#region src/prompts/scaffolds.d.ts
+declare const PROMPT_SCAFFOLD_VERSION: "lattice.prompt-scaffold/v1";
+declare const PROMPT_STRATEGIES: readonly ["frontier", "mid_tier", "open_weight", "reasoning", "local"];
+declare function getStructuredOutputContract(strategy: RecommendedPromptStrategy, schema: unknown): string;
+declare function getToolUseContract(strategy: RecommendedPromptStrategy, tools: unknown): string;
 //#endregion
-export { type AI, type ActionHistory, type ActionHistoryOptions, type ActionRecord, AgentDeniedError, type AgentEvalResult, type AgentFailure, type AgentFailureKind, type AgentHost, type AgentIntent, type AgentResult, type AgentRunSnapshot, type AgentScheduler, type AgentSnapshot, type AgentStorage, type AgentSuccess, type AgentTransport, type AnthropicProviderOptions, type ArtifactFingerprint, type ArtifactInput, type ArtifactKind, type ArtifactLineage, type ArtifactOptions, type ArtifactParentRef, type ArtifactPrivacy, type ArtifactRef, type ArtifactSize, type ArtifactSource, type ArtifactStorageRef, type ArtifactStore, type ArtifactTransformDescriptor, type ArtifactTransformKind, BAND, type BudgetInvariant, type CapabilityContract, type CapabilityContractInput, type CapabilityReceiptBody, type CheckpointHookContext, type CheckpointHookOptions, type ContractRejectReasonCode, type ContractVerdict, type ConversationTurn, type CostBudgetStatus, type CostTracker, type CreateReceiptInput, DEFAULT_CHECKPOINT_BAND, type EvalOptions, type EvalRegression, type EvalRegressionKind, type EvictionHook, type ExecutionPlanStub, type FieldFromTableInvariant, type FormatToolsMode, type FormatToolsOptions, type FormattedToolsHandle, type GeminiProviderOptions, type GoalProgressOptions, type GoalProgressStep, type GoalProgressTracker, type HookControls, type HookDenyDirective, type HookLifecycleEvent, type HookPipeline, type InferOutput, type InferOutputMap, type InvariantDeclaration, type InvariantOptions, type IterationRecord, type KeyEntry, type KeySet, type KeyState, type LatticeConfig, type LatticeRunError, type LmStudioProviderOptions, type MatchesInvariant, type MaterializationError, type MaterializeReplayEnvelopeOptions, type MustCiteInvariant, type NoPiiInvariant, type NormalizedLatticeConfig, type OpenRouterProviderOptions, type OutputContract, type OutputContractMap, type PermissionContext, type PermissionDecisionInput, type PermissionHookContext, type PermissionRule, type PermissionVerdict, type PiiDetector, type PiiDetectorResult, type PolicySpec, type ProgressStatus, type ProviderAdapter, type ProviderRef, type ProviderRunRequest, type ProviderRunResponse, type QualityFloorInvariant, type ReceiptEnvelope, type ReceiptModel, type ReceiptRedaction, type ReceiptRoute, type ReceiptSignature, type ReceiptSigner, type ReceiptUsageCanonical, type ReplayEnvelope, type ResumePolicy, type RunFailure, type RunIntent, type RunResult, type RunSuccess, STEP_TRANSITION_EVENT_NAME, STUCK_REASONS, type SerializedSnapshot, type SessionRef, type StorageLike, type StoredArtifactEnvelope, type StoredArtifactPayloadDescriptor, type StuckReason, type SurvivabilityAdapter, type TokenEstimator, type ToolUseRequest, type TracerLike, type TranscriptStore, type TripwireEvidence, type TripwireResult, type TripwireViolationError, type UnsubscribeFn, type Usage, type ValidationIssue, type VerifyError, type VerifyErrorKind, type VerifyFail, type VerifyOk, type VerifyResult, type XaiProviderOptions, artifact, contract, createAI, createAISdkProvider, createActionHistory, createAnthropicProvider, createCheckpointHook, createCostTracker, createFakeProvider, createGeminiProvider, createGoalProgressTracker, createHookPipeline, createInMemorySigner, createLmStudioProvider, createLocalArtifactStore, createMemoryArtifactStore, createMemoryKeySet, createMemorySessionStore, createNoopAgentHost, createNoopSurvivabilityAdapter, createOpenAICompatibleProvider, createOpenAIProvider, createOpenRouterProvider, createPermissionContext, createPermissionGuardHook, createReceipt, createReplayEnvelope, createTranscriptStore, createXaiProvider, defaultPiiDetectors, defineTool, estimateRouteCost, evalAgentRun, evaluateContractAgainstRoute, evaluateTripwires, formatToolsForProvider, generateEd25519KeyPairJwk, importMcpTools, inv, isTerminal, latticeVersion, materializeReplayEnvelope, output, permissionGuardRegisterOptions, redactArtifactRef, redactPlan, redactReplayEnvelope, replayOffline, rerunLive, runAgent, runTool, toolArtifactRef, toolSchemaToJsonSchema, verifyReceipt };
+export { type AI, ALL_KNOWN_FAILURE_MODES, ALL_TRAINING_CLASSES, type ActionHistory, type ActionHistoryOptions, type ActionRecord, type AdapterQuirks, AgentDeniedError, type AgentEvalResult, type AgentFailure, type AgentFailureKind, type AgentHost, type AgentIntent, type AgentResult, type AgentRunSnapshot, type AgentScheduler, type AgentSnapshot, type AgentSpec, type AgentStorage, type AgentSuccess, type AgentTransport, type AnthropicProviderOptions, type AnthropicQuirks, type ArtifactFingerprint, type ArtifactInput, type ArtifactKind, type ArtifactLineage, type ArtifactOptions, type ArtifactParentRef, type ArtifactPrivacy, type ArtifactRef, type ArtifactSize, type ArtifactSource, type ArtifactStorageRef, type ArtifactStore, type ArtifactTransformDescriptor, type ArtifactTransformKind, BAND, type BudgetInvariant, type CapabilityAdapter, type CapabilityContract, type CapabilityContractInput, type CapabilityReceiptBody, type CheckpointHookContext, type CheckpointHookOptions, type CollectStreamOptions, type ContractRejectReasonCode, type ContractVerdict, type ConversationTurn, type CostBudgetStatus, type CostTracker, type CreateReceiptInput, type CrewAgentResult, type CrewPolicy, type CrewRateLimitOverride, type CrewResult, DEFAULT_CHECKPOINT_BAND, type EvalOptions, type EvalRegression, type EvalRegressionKind, type EvictionHook, type ExecutionPlanStub, type FieldFromTableInvariant, type FormatToolsMode, type FormatToolsOptions, type FormattedToolsHandle, type GatewayMetadataValue, type GatewayPolicy, type GeminiLiveTarget, type GeminiProviderOptions, type GeminiQuirks, type GoalProgressOptions, type GoalProgressStep, type GoalProgressTracker, type HookControls, type HookDenyDirective, type HookLifecycleEvent, type HookPipeline, type InferOutput, type InferOutputMap, type InternalEnvelopeOptions, type InvariantDeclaration, type InvariantOptions, type IterationRecord, type KeyEntry, type KeySet, type KeyState, type KnownFailureMode, type LangfuseOtlpConfigOptions, type LatticeConfig, type LatticeRunError, type LiteLLMProviderOptions, type LiteLLMQuirks, type LmStudioProviderOptions, type LmStudioQuirks, type MatchesInvariant, type MaterializationError, type MaterializeReplayEnvelopeOptions, type ModelCapabilityProfile, type ModelCapabilityProfileModality, type ModelCapabilityProfilePricing, type ModelCapabilityProfilePricingKey, type MustCiteInvariant, type NegotiatedCapabilities, NegotiationAuthError, type NoPiiInvariant, NoPublicUrlEgressError, type NormalizedLatticeConfig, type OpenAICompatQuirks, type OpenAIQuirks, type OpenAIRealtimeTarget, type OpenRouterProviderOptions, type OpenRouterQuirks, type OtelAttributeValue, type OtelAttributes, type OtelContentCaptureMode, type OtelHttpTraceConfig, type OtelRunEventSinkOptions, type OtelSanitizerOptions, type OtelSpanLike, type OtelSpanStatus, type OtelTracerLike, type OutputContract, type OutputContractMap, PROMPT_SCAFFOLD_VERSION, PROMPT_STRATEGIES, type PermissionContext, type PermissionDecisionInput, type PermissionHookContext, type PermissionRule, type PermissionVerdict, type PhoenixOtlpConfigOptions, type PiiDetector, type PiiDetectorResult, type PolicySpec, type ProgressStatus, type ProviderAdapter, type ProviderGatewayMetadata, type ProviderRef, type ProviderRunRequest, type ProviderRunResponse, type ProviderStream, type ProviderStreamChunk, type ProviderStreamCompleteChunk, type ProviderStreamGatewayChunk, type ProviderStreamOutputChunk, type ProviderStreamTextDeltaChunk, type ProviderStreamToolCallChunk, type ProviderStreamUsageChunk, type QualityFloorInvariant, REALTIME_DIRECTION_SUPPORT_LEVEL, type RateLimitGroup, type RateLimitGroupOptions, type RateLimitLease, type RealtimeCheckpointInput, type RealtimeCheckpointKind, type RealtimeCheckpointingSpec, type RealtimeInputModality, type RealtimeOutputModality, type RealtimeProviderKind, type RealtimeProviderTarget, type RealtimeReceiptDescriptors, type RealtimeSessionMode, type RealtimeSessionSpec, type RealtimeSupportLevel, type RealtimeTransportKind, type ReasoningSurface, type ReceiptEnvelope, type ReceiptModel, type ReceiptRedaction, type ReceiptRoute, type ReceiptSignature, type ReceiptSigner, type ReceiptUsageCanonical, type RecommendedPromptStrategy, type RemoteReceiptPayloadFormat, type RemoteReceiptSignRequest, type RemoteReceiptSignResult, type RemoteReceiptSignerOptions, type RemoteReceiptSignerProvider, type ReplayEnvelope, type ResumePolicy, type RunAgentCrewOptions, type RunEvent, type RunEventKind, type RunEventSink, type RunFailure, type RunIntent, type RunResult, type RunSuccess, SANITIZER_BY_FAILURE_MODE, STEP_TRANSITION_EVENT_NAME, STUCK_REASONS, type SanitizeOutputOption, type SanitizerContext, type SanitizerFn, type SanitizerKey, type SerializedSnapshot, type SessionRef, type StorageLike, type StoredArtifactEnvelope, type StoredArtifactPayloadDescriptor, type StuckReason, type SurvivabilityAdapter, type TokenEstimator, type ToolCallSurface, ToolCallValidationError, type ToolCallValidationFailureReason, type ToolUseRequest, type TracerLike, type TrainingClass, type TranscriptStore, type TripwireEvidence, type TripwireResult, type TripwireViolationError, type UnsubscribeFn, type Usage, type ValidateToolCallsOption, type ValidatedToolCall, type ValidationIssue, type VerifyError, type VerifyErrorKind, type VerifyFail, type VerifyOk, type VerifyResult, type XaiProviderOptions, type XaiQuirks, artifact, collectStream, contract, createAI, createAISdkProvider, createActionHistory, createAnthropicProvider, createCheckpointHook, createCostTracker, createFakeProvider, createGeminiProvider, createGoalProgressTracker, createHookPipeline, createInMemorySigner, createLangfuseOtlpConfig, createLiteLLMProvider, createLmStudioProvider, createLocalArtifactStore, createMemoryArtifactStore, createMemoryKeySet, createMemorySessionStore, createNoopAgentHost, createNoopSurvivabilityAdapter, createOpenAICompatibleProvider, createOpenAIProvider, createOpenRouterProvider, createOtelReceiptAttributes, createOtelRunEventSink, createPermissionContext, createPermissionGuardHook, createPhoenixOtlpConfig, createRateLimitGroup, createRealtimeCheckpointContext, createRealtimeReceiptDescriptors, createReceipt, createRemoteReceiptSigner, createReplayEnvelope, createTranscriptStore, createXaiProvider, defaultPiiDetectors, defineAgent, defineTool, estimateRouteCost, evalAgentRun, evaluateContractAgainstRoute, evaluateTripwires, findCapabilityProfile, formatToolsForProvider, generateEd25519KeyPairJwk, getCapabilityProfile, getRecommendedSanitizers, getStructuredOutputContract, getToolUseContract, importMcpTools, inv, isTerminal, latticeVersion, materializeReplayEnvelope, negotiateCapabilities, output, parseToolUseEnvelope, permissionGuardRegisterOptions, realtimeStepName, receiptCid, redactArtifactRef, redactPlan, redactReplayEnvelope, replayOffline, rerunLive, runAgent, runAgentCrew, runTool, sanitizeRunEventAttributes, stripChatTemplateArtifacts, stripOpenRouterVariant, stripReasoningTags, synthesizeNegotiatedCapabilitiesFromRegistry, toolArtifactRef, toolSchemaToJsonSchema, unwrapInternalEnvelope, verifyReceipt, withRateLimit };
 //# sourceMappingURL=index.d.ts.map