@full-self-browsing/lattice 0.0.0-bootstrap.0

package/dist/index.d.ts

@@ -0,0 +1,2359 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/policy/policy.d.ts
+interface PolicySpec {
+  readonly maxCostUsd?: number;
+  readonly latency?: "interactive" | "batch";
+  readonly privacy?: "standard" | "sensitive" | "restricted";
+  readonly providerAllowList?: readonly string[];
+  readonly providerDenyList?: readonly string[];
+  readonly noUpload?: boolean;
+  readonly noPublicUrl?: boolean;
+  readonly noLogging?: boolean;
+  readonly metadata?: Record<string, unknown>;
+}
+//#endregion
+//#region src/artifacts/lineage.d.ts
+type ArtifactTransformKind = "manual" | "generated" | "extraction" | "chunking" | "transcription" | "resizing" | "provider-packaging" | "tool-result" | "model-output";
+interface ArtifactTransformDescriptor {
+  readonly kind: ArtifactTransformKind;
+  readonly name?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+interface ArtifactParentRef {
+  readonly id: string;
+  readonly kind: ArtifactKind;
+  readonly mediaType?: string;
+  readonly source: ArtifactSource;
+  readonly label?: string;
+  readonly metadata?: Record<string, unknown>;
+  readonly privacy: ArtifactPrivacy;
+  readonly size?: ArtifactSize;
+  readonly fingerprint?: ArtifactFingerprint;
+  readonly storage?: ArtifactStorageRef;
+  readonly lineage?: ArtifactLineage;
+}
+interface ArtifactLineage {
+  readonly parents: readonly ArtifactParentRef[];
+  readonly transform: ArtifactTransformDescriptor;
+}
+//#endregion
+//#region src/artifacts/artifact.d.ts
+type ArtifactKind = "text" | "json" | "file" | "image" | "audio" | "video" | "document" | "url" | "tool-result";
+type ProviderUploadArtifactSource = `provider-${"up"}${"load"}`;
+type ArtifactSource = "inline" | "file" | "url" | "generated" | ProviderUploadArtifactSource | "tool";
+type ArtifactPrivacy = NonNullable<PolicySpec["privacy"]>;
+interface ArtifactSize {
+  readonly bytes?: number;
+  readonly characters?: number;
+  readonly pages?: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly durationMs?: number;
+}
+interface ArtifactFingerprint {
+  readonly algorithm: "sha256";
+  readonly value: string;
+}
+interface ArtifactStorageRef {
+  readonly storeId: string;
+  readonly key: string;
+}
+interface ArtifactOptions {
+  readonly id?: string;
+  readonly mediaType?: string;
+  readonly label?: string;
+  readonly metadata?: Record<string, unknown>;
+  readonly privacy?: ArtifactPrivacy;
+  readonly size?: ArtifactSize;
+  readonly fingerprint?: ArtifactFingerprint;
+  readonly storage?: ArtifactStorageRef;
+  readonly lineage?: ArtifactLineage;
+}
+interface ArtifactToolResultOptions extends ArtifactOptions {
+  readonly toolName: string;
+  readonly callId?: string;
+}
+interface ArtifactDerivedOptions extends ArtifactOptions {
+  readonly kind: ArtifactKind;
+  readonly source?: ArtifactSource;
+  readonly value?: unknown;
+  readonly parents: readonly ArtifactRef[];
+  readonly transform: ArtifactTransformDescriptor;
+}
+interface ArtifactRef {
+  readonly id: string;
+  readonly kind: ArtifactKind;
+  readonly mediaType?: string;
+  readonly source: ArtifactSource;
+  readonly label?: string;
+  readonly metadata?: Record<string, unknown>;
+  readonly privacy: ArtifactPrivacy;
+  readonly size?: ArtifactSize;
+  readonly fingerprint?: ArtifactFingerprint;
+  readonly storage?: ArtifactStorageRef;
+  readonly lineage?: ArtifactLineage;
+}
+type ArtifactInput = ArtifactRef & {
+  readonly value?: unknown;
+};
+declare const artifact: {
+  text(value: string, options?: ArtifactOptions): ArtifactInput;
+  json(value: unknown, options?: ArtifactOptions): ArtifactInput;
+  file(value: Blob | File | string, options?: ArtifactOptions): ArtifactInput;
+  image(value: Blob | File | string, options?: ArtifactOptions): ArtifactInput;
+  audio(value: Blob | File | string, options?: ArtifactOptions): ArtifactInput;
+  document(value: Blob | File | string, options?: ArtifactOptions): ArtifactInput;
+  url(value: string | URL, options?: ArtifactOptions): ArtifactInput;
+  toolResult(value: unknown, options: ArtifactToolResultOptions): ArtifactInput;
+  derive(input: ArtifactDerivedOptions): ArtifactInput;
+};
+//#endregion
+//#region src/tracing/tracing.d.ts
+interface TracerLike {
+  readonly kind: "tracer";
+  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";
+interface RunEvent {
+  readonly kind: RunEventKind;
+  readonly timestamp: string;
+  readonly runId: string;
+  readonly planId?: string;
+  readonly stageId?: string;
+  readonly providerId?: string;
+  readonly modelId?: string;
+  readonly artifactId?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+type RunEventSink = (event: RunEvent) => void | Promise<void>;
+//#endregion
+//#region src/contract/bands.d.ts
+/**
+ * Hook lifecycle event vocabulary -- separate from RunEventKind by design.
+ *
+ * Phase 19 (v1.2) additively extends with BEFORE_AGENT_ITERATION and
+ * AFTER_AGENT_ITERATION — emitted by `runAgent` around each iteration's
+ * provider call. Existing four events continue to fire inside each
+ * iteration (BEFORE/AFTER_PROVIDER per native call; BEFORE/AFTER_TOOL
+ * per dispatched tool).
+ */
+type HookLifecycleEvent = "BEFORE_PROVIDER" | "AFTER_PROVIDER" | "BEFORE_TOOL" | "AFTER_TOOL" | "BEFORE_AGENT_ITERATION" | "AFTER_AGENT_ITERATION";
+/**
+ * SAFETY-band veto mechanism — Phase 19.
+ *
+ * Handlers can deny an iteration by calling `controls.deny(reason)`. The
+ * pipeline records the latest reason and exposes it via `lastDenialReason()`.
+ * The reason resets at the start of each `run()` call.
+ *
+ * Composition convention: the agent runtime invokes BEFORE_AGENT_ITERATION
+ * before provider call, then checks `pipeline.lastDenialReason()`. If set,
+ * the iteration aborts with `agent-iteration-denied` failure.
+ */
+interface HookDenyDirective {
+  readonly reason: string;
+}
+/**
+ * Controls passed to each handler as an optional second argument.
+ *
+ * Backward compat: existing single-argument handlers (Phase 15 + Phase 16)
+ * ignore this and continue to work unchanged.
+ */
+interface HookControls {
+  /** Set a denial reason; the latest call wins per `run()`. */
+  readonly deny: (reason: string) => void;
+}
+/**
+ * Priority bands. Lower number = higher priority (runs first).
+ *
+ * SAFETY (0)        -- safety / breaker hooks; cannot be overridden by lower bands
+ * OBSERVABILITY (1) -- logging, metrics, audit; runs after safety, before extension
+ * EXTENSION (2)     -- user-supplied hooks; runs last
+ *
+ * Within a band, handlers run in registration order.
+ */
+declare const BAND: {
+  readonly SAFETY: 0;
+  readonly OBSERVABILITY: 1;
+  readonly EXTENSION: 2;
+};
+type Band = typeof BAND[keyof typeof BAND];
+/**
+ * Handler input -- frozen snapshot of the caller's context at run() time.
+ *
+ * structuredClone-then-Object.freeze: handlers receive a deep-cloned,
+ * surface-frozen view. Mutations on the handler side do NOT leak back to
+ * the calling site.
+ *
+ * The handler's return value is currently ignored; future revisions may
+ * add a typed return that downstream bands consume.
+ */
+interface HookHandler<TContext = unknown> {
+  (context: Readonly<TContext>, controls?: HookControls): void | Promise<void>;
+}
+interface RegisterOptions {
+  readonly band: Band;
+  readonly matcher?: RegExp;
+  readonly budgetMs?: number;
+}
+/**
+ * The HookPipeline interface returned by createHookPipeline().
+ *
+ * IMMUTABILITY: once freeze() is called, register() throws an Error whose
+ * .name === "PIPELINE_FROZEN". freeze() is irreversible by design --
+ * protects against late-binding hook injection mid-session.
+ */
+interface HookPipeline {
+  readonly kind: "hook-pipeline";
+  register<TContext = unknown>(event: HookLifecycleEvent, handler: HookHandler<TContext>, options: RegisterOptions): void;
+  freeze(): void;
+  isFrozen(): boolean;
+  run<TContext = unknown>(event: HookLifecycleEvent, context: TContext): Promise<void>;
+  /**
+   * Phase 19: returns the latest denial reason set by any handler during
+   * the most recent `run()` call. Resets to `null` at the start of each run.
+   * Read by the agent runtime to detect SAFETY-band veto.
+   */
+  lastDenialReason(): string | null;
+}
+interface CreateHookPipelineOptions {
+  readonly tracer?: TracerLike;
+  readonly sessionId?: string;
+  readonly defaultBudgetMs?: number;
+}
+/**
+ * Factory: build a fresh hook pipeline.
+ */
+declare function createHookPipeline(options?: CreateHookPipelineOptions): HookPipeline;
+//#endregion
+//#region src/contract/invariants.d.ts
+/**
+ * Tripwire invariant declaration variants produced by the `inv` fluent
+ * builder. Each variant is a frozen value carrying a discriminant `kind`
+ * and an `id` (auto-generated or caller-supplied).
+ *
+ * Phase 8 reshapes the Phase 7 placeholder `{ kind: "policy"|"semantic"|"schema" }`
+ * into this discriminated union. Phase 7 never populated `invariants`
+ * (see 07-04-SUMMARY decisions), so the change is additive in practice
+ * but technically a breaking type change for any external caller that
+ * authored a literal of the old shape.
+ */
+interface MustCiteInvariant {
+  readonly id: string;
+  readonly kind: "must-cite";
+  readonly artifactName: string;
+}
+interface FieldFromTableInvariant {
+  readonly id: string;
+  readonly kind: "field-from-table";
+  readonly path: string;
+  readonly allowedValues: readonly string[];
+}
+interface NoPiiInvariant {
+  readonly id: string;
+  readonly kind: "no-pii";
+  readonly path: string;
+}
+interface MatchesInvariant<T = unknown> {
+  readonly id: string;
+  readonly kind: "matches";
+  readonly path: string;
+  readonly schema: StandardSchemaV1<unknown, T>;
+}
+type InvariantDeclaration = MustCiteInvariant | FieldFromTableInvariant | NoPiiInvariant | MatchesInvariant;
+interface InvariantOptions {
+  readonly id?: string;
+}
+/**
+ * Fluent builder for tripwire invariants.
+ *
+ * Each helper returns a frozen `InvariantDeclaration` with an auto-generated
+ * id of the form `${kind}-${counter}`. Callers may override the id via the
+ * second-positional `options.id` arg.
+ *
+ * The counter is monotonic across kinds — calling `inv.mustCite("a")` then
+ * `inv.fieldFromTable("x", ["y"])` yields ids `must-cite-1` then
+ * `field-from-table-2`. This keeps ids globally unique within a process.
+ *
+ * Note on `inv.matches`: the caller supplies the StandardSchema validator,
+ * and the tripwire evaluator trusts whatever `~standard.validate` returns.
+ * This is by design — `matches` is the caller-driven escape hatch (see
+ * T-08-05 in the 08-01-PLAN threat register).
+ */
+declare const inv: {
+  readonly mustCite: (artifactName: string, options?: InvariantOptions) => MustCiteInvariant;
+  readonly fieldFromTable: (path: string, allowedValues: readonly string[], options?: InvariantOptions) => FieldFromTableInvariant;
+  readonly noPII: (path: string, options?: InvariantOptions) => NoPiiInvariant;
+  readonly matches: <T>(path: string, schema: StandardSchemaV1<unknown, T>, options?: InvariantOptions) => MatchesInvariant<T>;
+  /**
+   * Test-only: reset the auto-id counter. NOT exported from the package
+   * root barrel — callers must import `inv` directly from this module if
+   * they ever need it, which is intentional friction.
+   */
+  readonly __resetCounterForTests: () => void;
+};
+//#endregion
+//#region src/contract/pii-detectors.d.ts
+/**
+ * Regex-based PII detectors used by the `no-pii` tripwire invariant.
+ *
+ * Phase 8 ships four detectors (email, US SSN, Luhn-valid credit card,
+ * US phone). They are intentionally regex-only — zero new dependencies —
+ * per the v1.1 scope locked in 08-CONTEXT.md.
+ *
+ * Each detector returns either `{ matched: true, substring }` carrying
+ * ONLY the matched fragment, or `{ matched: false }`. The substring shape
+ * is required so the tripwire evaluator can emit redacted evidence
+ * (Phase 9 receipts must not leak the full input).
+ *
+ * Detector order in `defaultPiiDetectors` is deterministic so the
+ * evaluator's first-violation semantics produce stable receipts.
+ */
+type PiiDetectorResult = {
+  readonly matched: true;
+  readonly substring: string;
+} | {
+  readonly matched: false;
+};
+interface PiiDetector {
+  readonly name: string;
+  detect(input: string): PiiDetectorResult;
+}
+/**
+ * Default PII detectors used by `evaluateTripwires` for `no-pii` invariants.
+ *
+ * Order is deterministic: email, us-ssn, credit-card, us-phone. Callers who
+ * need a different set can pass their own list to `evaluateTripwires`.
+ */
+declare const defaultPiiDetectors: readonly PiiDetector[];
+//#endregion
+//#region src/contract/tripwire.d.ts
+/**
+ * Evidence emitted when a tripwire invariant fires.
+ *
+ * `observed` is the SHAPE-MATCHED redacted payload, not the raw output:
+ *   - for `must-cite`: the citations array as found at the located path
+ *   - for `field-from-table`: the actual value at `path`
+ *   - for `no-pii`: ONLY `{ detector, substring }` — never the full input
+ *     (T-08-01 in the 08-01-PLAN threat register)
+ *   - for `matches`: the value at `path`
+ *
+ * Phase 9 receipts will sign this evidence, so leaking the full PII into
+ * `observed` would defeat redact-before-sign.
+ */
+interface TripwireEvidence {
+  readonly invariantId: string;
+  readonly kind: "must-cite" | "field-from-table" | "no-pii" | "matches";
+  readonly path: string;
+  readonly observed: unknown;
+  readonly message: string;
+}
+type TripwireResult = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly evidence: TripwireEvidence;
+};
+/**
+ * Pure tripwire evaluator.
+ *
+ * No I/O, no Date.now, no random — same `(output, invariants)` always
+ * returns the same `TripwireResult`. Phase 9 receipts can reconstruct the
+ * verdict deterministically (T-08-04).
+ *
+ * Evaluates invariants in declaration order; the FIRST failing invariant
+ * aborts and returns its evidence. Subsequent invariants are not evaluated.
+ *
+ * @param output      The provider output to inspect.
+ * @param invariants  Invariants to evaluate, in declaration order.
+ * @param detectors   PII detectors used for `no-pii` invariants. Defaults
+ *                    to `defaultPiiDetectors`. Callers can pass a custom
+ *                    list to override.
+ */
+declare function evaluateTripwires(output: unknown, invariants: readonly InvariantDeclaration[], detectors?: readonly PiiDetector[]): Promise<TripwireResult>;
+//#endregion
+//#region src/outputs/contracts.d.ts
+type TextOutputContract = "text";
+interface CitationRef {
+  readonly artifactId: string;
+  readonly label?: string;
+  readonly span?: {
+    readonly start?: number;
+    readonly end?: number;
+  };
+  readonly metadata?: Record<string, unknown>;
+}
+interface CitationsOutputContract {
+  readonly kind: "citations";
+}
+interface ArtifactRefsOutputContract {
+  readonly kind: "artifacts";
+  readonly artifactKind?: ArtifactKind | string;
+}
+type SchemaOutputContract = StandardSchemaV1;
+type OutputContract = TextOutputContract | SchemaOutputContract | CitationsOutputContract | ArtifactRefsOutputContract;
+type OutputContractMap = Record<string, OutputContract>;
+declare const output: {
+  citations(): CitationsOutputContract;
+  artifacts(options?: {
+    readonly artifactKind?: ArtifactKind | string;
+  }): ArtifactRefsOutputContract;
+};
+//#endregion
+//#region src/sessions/session.d.ts
+interface SessionRef {
+  readonly id: string;
+  readonly kind?: "session-ref";
+}
+interface SessionTurn {
+  readonly id: string;
+  readonly task: string;
+  readonly artifactRefs: readonly ArtifactRef[];
+  readonly planId?: string;
+  readonly outputArtifactRefs: readonly ArtifactRef[];
+  readonly createdAt: string;
+}
+interface SessionSummary {
+  readonly id: string;
+  readonly artifactRef: ArtifactRef;
+  readonly sourceTurnIds: readonly string[];
+  readonly trust: "model-summary";
+  readonly createdAt: string;
+}
+interface SessionRecord extends SessionRef {
+  readonly kind: "session-ref";
+  readonly parentId?: string;
+  readonly branchPointRunId?: string;
+  readonly turns: readonly SessionTurn[];
+  readonly summaries: readonly SessionSummary[];
+  readonly artifactRefs: readonly ArtifactRef[];
+  readonly planIds: readonly string[];
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+interface CreateSessionOptions {
+  readonly id?: string;
+  readonly parentId?: string;
+  readonly branchPointRunId?: string;
+}
+interface AppendSessionTurnInput {
+  readonly sessionId: string;
+  readonly task: string;
+  readonly artifactRefs: readonly ArtifactRef[];
+  readonly outputArtifactRefs?: readonly ArtifactRef[];
+  readonly planId?: string;
+}
+interface SessionStore {
+  readonly kind: "session-store";
+  readonly id: string;
+  create(options?: CreateSessionOptions): Promise<SessionRecord>;
+  load(id: string): Promise<SessionRecord | undefined>;
+  save(session: SessionRecord): Promise<SessionRecord>;
+  branch(parentId: string, options?: Omit<CreateSessionOptions, "parentId">): Promise<SessionRecord>;
+  appendTurn(input: AppendSessionTurnInput): Promise<SessionRecord>;
+}
+interface MemorySessionStoreOptions {
+  readonly id?: string;
+}
+declare function createMemorySessionStore(options?: MemorySessionStoreOptions): SessionStore;
+//#endregion
+//#region src/context/context-pack.d.ts
+interface ContextPack extends ContextPackPlan {
+  readonly kind: "context-pack";
+}
+interface ContextSummarizer {
+  summarize(input: {
+    readonly artifacts: readonly ArtifactRef[];
+    readonly budgetTokens: number;
+  }): 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;
+}
+/**
+ * Normalized per-run usage at the result layer.
+ *
+ * `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".
+ *
+ * Distinct from `UsageRecord` on `ProviderAttemptRecord`: `UsageRecord`
+ * is the per-attempt record, `Usage` is the per-run normalized shape
+ * surfaced on `RunSuccess` / `RunFailure`.
+ */
+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;
+}
+interface ProviderRef {
+  readonly id: string;
+  readonly kind?: "provider-ref";
+}
+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[];
+}
+interface ProviderRunResponse {
+  readonly rawOutputs: Record<string, unknown>;
+  readonly artifactRefs?: readonly (ArtifactInput | ArtifactRef)[];
+  /**
+   * @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 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 rawResponse?: unknown;
+}
+interface ProviderAdapter {
+  readonly id: string;
+  readonly kind: "provider-adapter";
+  readonly capabilities?: readonly ModelCapability[];
+  readonly execute?: (request: ProviderRunRequest) => Promise<ProviderRunResponse>;
+}
+type ProviderRegistryInput = readonly (ProviderRef | ProviderAdapter | string)[];
+//#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>;
+}
+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 warnings: readonly 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;
+}
+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[];
+}
+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 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";
+  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;
+}
+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;
+}
+type VerifyResult = VerifyOk | VerifyFail;
+//#endregion
+//#region src/receipts/receipt.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)
+ *
+ * receiptId and issuedAt default to runtime-generated values when omitted.
+ * redactionPolicyId defaults to DEFAULT_REDACTION_POLICY_ID.
+ */
+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;
+}
+/**
+ * Build, redact, canonicalize, sign, and envelope a CapabilityReceipt.
+ *
+ * Ordering INVARIANT (09-CONTEXT.md, PITFALLS.md Pitfall #1):
+ *   redact -> canonicalize -> PAE -> sign -> encode
+ *
+ * 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.
+ *
+ * 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).
+ *
+ * I-JSON guarantees: usage.costUsd is converted to string (or null) via
+ * usageToCanonical. Receipts NEVER carry raw floats in the canonical form.
+ */
+declare function createReceipt(input: CreateReceiptInput, signer: ReceiptSigner): Promise<ReceiptEnvelope>;
+//#endregion
+//#region src/contract/checkpoint.d.ts
+/**
+ * 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.
+ *
+ * Fields are stable identifiers (D-04 carryforward); do NOT populate with
+ * user content -- they appear cleartext in the signed receipt body.
+ *
+ * - 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.
+ *
+ * - 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.
+ *
+ * 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.
+ *
+ * NO upstream throw (D-07). NO global mutation (D-05).
+ */
+declare function createCheckpointHook(options: CheckpointHookOptions): HookHandler<CheckpointHookContext>;
+//#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;
+}
+/**
+ * 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;
+}
+/**
+ * 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";
+}
+/**
+ * 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";
+}
+/**
+ * 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/contract/preflight.d.ts
+/**
+ * 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.
+ *
+ * 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`).
+ */
+interface EstimateRouteCostInput {
+  readonly capability: ModelCapability;
+  readonly estimatedInputTokens: number;
+  readonly estimatedOutputTokens: number;
+}
+/**
+ * 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.
+ */
+declare function estimateRouteCost(input: EstimateRouteCostInput): number | null;
+/** Input for the pre-flight evaluator. */
+interface EvaluateContractInput {
+  readonly capability: ModelCapability;
+  readonly estimatedInputTokens: number;
+  readonly estimatedOutputTokens: number;
+}
+/**
+ * Pure pre-flight evaluator. Phase 9 receipts will reuse this for deterministic
+ * verdict reconstruction.
+ *
+ * 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)
+ */
+declare function evaluateContractAgainstRoute(contract: CapabilityContract | undefined, input: EvaluateContractInput): ContractPreflightResult;
+//#endregion
+//#region src/receipts/keyset.d.ts
+/**
+ * In-memory KeySet factory.
+ *
+ * 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"
+ *
+ * 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)".
+ */
+declare function createMemoryKeySet(entries: readonly KeyEntry[]): KeySet;
+//#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
+/**
+ * Pure receipt verifier.
+ *
+ * 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 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 ExecutionUnavailableError {
+  readonly kind: "execution_unavailable";
+  readonly message: string;
+}
+interface NoRouteError {
+  readonly kind: "no_route";
+  readonly message: string;
+  readonly reasons: readonly string[];
+}
+interface ProviderExecutionError {
+  readonly kind: "provider_execution";
+  readonly message: string;
+  readonly providerId?: string;
+  readonly modelId?: string;
+}
+interface TimeoutError {
+  readonly kind: "timeout";
+  readonly message: string;
+}
+/**
+ * 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[];
+}
+/**
+ * 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;
+}
+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;
+  /**
+   * 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 pricing?: {
+    readonly inputPer1kTokens?: number;
+    readonly outputPer1kTokens?: number;
+  };
+}
+interface SdkLikeProviderOptions {
+  readonly id?: string;
+  readonly model: string;
+  readonly generate: (input: {
+    readonly task: string;
+    readonly outputNames: readonly string[];
+  }) => Promise<ProviderRunResponse> | ProviderRunResponse;
+}
+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;
+  };
+}
+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[];
+  /**
+   * 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
+/**
+ * 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;
+  };
+}
+declare function createGeminiProvider(options: GeminiProviderOptions): ProviderAdapter;
+//#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;
+}
+declare function createLmStudioProvider(options: LmStudioProviderOptions): ProviderAdapter;
+//#endregion
+//#region src/providers/openrouter.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).
+ *
+ * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-03: thin wrapper; D-17: model-routing deferred).
+ */
+interface OpenRouterProviderOptions extends Omit<OpenAICompatibleProviderOptions, "id" | "baseUrl"> {
+  readonly id?: string;
+  /** Defaults to `https://openrouter.ai/api/v1`. Override for proxies. */
+  readonly baseUrl?: string;
+}
+declare function createOpenRouterProvider(options: OpenRouterProviderOptions): ProviderAdapter;
+//#endregion
+//#region src/providers/xai.d.ts
+/**
+ * Options for {@link createXaiProvider}.
+ *
+ * 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.
+ *
+ * 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)
+ *
+ * Ref: FSB v0.10.0-attempt-2 Phase 4 (D-03 + D-07: thin wrapper; reasoning_tokens quirk preserved).
+ */
+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;
+//#endregion
+//#region src/runtime/survivability.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).
+ *
+ * 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.
+ */
+/**
+ * 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;
+}
+/**
+ * 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;
+  serialize(state: TState): SerializedSnapshot;
+  deserialize(snapshot: SerializedSnapshot): TState;
+  onEviction(hook: EvictionHook<TState>): UnsubscribeFn;
+  resume(snapshot: SerializedSnapshot): Promise<ResumePolicy>;
+}
+/**
+ * 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 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;
+//#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 {
+  /**
+   * 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 mode?: FormatToolsMode;
+  /**
+   * Optional system prompt to prepend. Useful for setting persona /
+   * domain-specific instructions on top of the tool-use envelope.
+   */
+  readonly system?: string;
+}
+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;
+  /**
+   * 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";
+}
+/**
+ * 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;
+//#endregion
+//#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;
+}
+/**
+ * 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>;
+}
+/**
+ * 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>;
+}
+/**
+ * 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>;
+}
+/**
+ * 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;
+}
+/**
+ * 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/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;
+}
+/**
+ * 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;
+}
+/**
+ * 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 usage: Usage;
+  readonly iterations: ReadonlyArray<IterationRecord>;
+  readonly receipt?: ReceiptEnvelope;
+}
+/**
+ * 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`.
+ *
+ * `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;
+}
+/**
+ * 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;
+}
+//#endregion
+//#region src/storage/storage.d.ts
+interface ArtifactStore {
+  readonly kind: "artifact-store";
+  readonly id: string;
+  put(artifact: ArtifactInput): Promise<ArtifactRef>;
+  get(id: string): Promise<ArtifactRef | undefined>;
+  load(id: string): Promise<ArtifactInput | undefined>;
+  has(id: string): Promise<boolean>;
+  delete(id: string): Promise<boolean>;
+  list(): Promise<readonly ArtifactRef[]>;
+}
+type StorageLike = ArtifactStore;
+interface StoredArtifactPayloadDescriptor {
+  readonly kind: "json" | "binary";
+  readonly path: string;
+}
+interface StoredArtifactEnvelope {
+  readonly version: 1;
+  readonly ref: ArtifactRef;
+  readonly payload?: StoredArtifactPayloadDescriptor;
+}
+//#endregion
+//#region src/runtime/config.d.ts
+interface LatticeConfig {
+  readonly providers?: ProviderRegistryInput;
+  readonly storage?: StorageLike | false;
+  readonly sessions?: SessionStore | false;
+  readonly defaults?: {
+    readonly policy?: PolicySpec;
+  };
+  readonly tracing?: TracerLike | false;
+  readonly events?: RunEventSink | readonly RunEventSink[];
+  /**
+   * Phase 9 — when configured, every terminal branch of `ai.run` emits a
+   * signed `CapabilityReceipt` attached to `RunResult.receipt`. When absent,
+   * no receipts are issued and `RunResult.receipt` is undefined.
+   */
+  readonly signer?: ReceiptSigner;
+}
+type NormalizedProviderEntry = ProviderRef | ProviderAdapter;
+interface NormalizedLatticeConfig {
+  readonly providers: readonly NormalizedProviderEntry[];
+  readonly storage?: StorageLike;
+  readonly sessions?: SessionStore;
+  readonly defaults: {
+    readonly policy?: PolicySpec;
+  };
+  readonly tracing?: TracerLike;
+  readonly events: readonly RunEventSink[];
+  readonly signer?: ReceiptSigner;
+}
+//#endregion
+//#region src/runtime/create-ai.d.ts
+interface RuntimeOverrides {
+  readonly provider?: string;
+  readonly model?: string;
+  readonly routingPolicy?: PolicySpec;
+  readonly tokenBudget?: number;
+  readonly summarizer?: ContextSummarizer;
+  readonly transforms?: readonly RuntimeArtifactTransform[];
+  readonly hooks?: RuntimeHooks;
+}
+interface RuntimeArtifactTransform {
+  readonly name: string;
+  transform(input: {
+    readonly task: string;
+    readonly artifacts: readonly ArtifactInput[];
+  }): Promise<ArtifactInput | readonly ArtifactInput[]> | ArtifactInput | readonly ArtifactInput[];
+}
+interface RuntimeHooks {
+  readonly beforeProviderCall?: (input: {
+    readonly plan: ExecutionPlan;
+    readonly request: ProviderRunRequest;
+  }) => void | Promise<void>;
+  readonly afterProviderCall?: (input: {
+    readonly plan: ExecutionPlan;
+    readonly response: unknown;
+  }) => void | Promise<void>;
+}
+interface RunIntent<TOutputs extends OutputContractMap> {
+  readonly task: string;
+  readonly artifacts?: readonly ArtifactInput[];
+  readonly outputs: TOutputs;
+  readonly policy?: PolicySpec;
+  readonly session?: SessionRef;
+  readonly signal?: AbortSignal;
+  readonly overrides?: RuntimeOverrides;
+  readonly tools?: readonly ToolDefinition<any>[];
+  readonly toolInputs?: Record<string, unknown>;
+  readonly contract?: CapabilityContract;
+}
+interface AI {
+  session(id: string): SessionRef;
+  plan<const TOutputs extends OutputContractMap>(intent: RunIntent<TOutputs>): Promise<ExecutionPlan>;
+  run<const TOutputs extends OutputContractMap>(intent: RunIntent<TOutputs>): Promise<RunResult<TOutputs>>;
+  /**
+   * 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
+   * `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>>;
+}
+declare function createAI(config?: LatticeConfig): AI;
+//#endregion
+//#region src/replay/replay.d.ts
+interface ReplayEnvelope<TOutputs extends OutputContractMap = OutputContractMap> {
+  readonly kind: "replay-envelope";
+  readonly version: 1;
+  readonly runtimeVersion: string;
+  readonly catalogVersion: string;
+  readonly createdAt: string;
+  readonly plan: ExecutionPlan;
+  readonly artifacts: readonly ArtifactRef[];
+  readonly outputs?: InferOutputMap<TOutputs>;
+  readonly warnings: readonly string[];
+  readonly errors: readonly string[];
+  readonly usage?: UsageRecord;
+  readonly events: readonly RunEvent[];
+  /**
+   * Phase 10 — optional signed receipt recorded alongside the envelope so a
+   * single artifact is sufficient to materialize an offline replay session
+   * deterministically. Type-only import — replay.ts stays runtime-import-free
+   * of the receipts builder.
+   */
+  readonly receipt?: ReceiptEnvelope;
+  /**
+   * Phase 10 — optional contract recorded so replays can re-run pre-flight
+   * checks deterministically.
+   */
+  readonly contract?: CapabilityContract;
+}
+declare function createReplayEnvelope<TOutputs extends OutputContractMap>(result: RunResult<TOutputs>): ReplayEnvelope<TOutputs>;
+declare function replayOffline<TOutputs extends OutputContractMap>(envelope: ReplayEnvelope<TOutputs>): Promise<RunResult<TOutputs>>;
+declare function rerunLive<TOutputs extends OutputContractMap>(ai: AI, envelope: ReplayEnvelope<TOutputs>, intent: RunIntent<TOutputs>): Promise<RunResult<TOutputs>>;
+declare function redactReplayEnvelope<TOutputs extends OutputContractMap>(envelope: ReplayEnvelope<TOutputs>): ReplayEnvelope<TOutputs>;
+declare function redactPlan(plan: ExecutionPlan): ExecutionPlan;
+declare function redactArtifactRef(ref: ArtifactRef): ArtifactRef;
+//#endregion
+//#region src/replay/materialize.d.ts
+/**
+ * Discriminated union of materialization failure modes.
+ *
+ *   - "verify-failed"        — receipt failed verifyReceipt (signature, key
+ *                              missing/revoked, canonicalization mismatch).
+ *   - "artifact-load-failed" — the artifactLoader callback rejected for at
+ *                              least one input hash.
+ *   - "envelope-malformed"   — receipt verified but the verified body is
+ *                              structurally unusable (should never happen
+ *                              under verifyReceipt invariants, but kept as a
+ *                              defensive third branch).
+ */
+interface MaterializationError {
+  readonly kind: "verify-failed" | "artifact-load-failed" | "envelope-malformed";
+  readonly message: string;
+}
+/**
+ * Async callback that resolves an artifact body from its sha256 hex digest.
+ * Phase 10 ships only the in-memory variant for tests. Phase 11's CLI plugs
+ * in a filesystem-backed loader reading from `.lattice/fixtures/<sha256>.bin`.
+ */
+type ArtifactLoader = (hash: string) => Promise<ArtifactInput>;
+interface MaterializeReplayEnvelopeOptions<TOutputs extends OutputContractMap = OutputContractMap> {
+  readonly artifactLoader: ArtifactLoader;
+  readonly keySet: KeySet;
+  /** Optional original task string. Defaults to "" when omitted. */
+  readonly task?: string;
+  /**
+   * Optional caller-supplied outputs map. When provided, the resulting
+   * `ReplayEnvelope.outputs` is populated and `replayOffline` will return
+   * an `ok: true` result. When omitted, `replayOffline` reports an
+   * `execution_unavailable` failure (current Phase 5 semantics).
+   */
+  readonly outputs?: InferOutputMap<TOutputs>;
+  readonly policy?: PolicySpec;
+  readonly contract?: CapabilityContract;
+}
+/**
+ * Pure async function that reconstructs a `ReplayEnvelope` from a receipt.
+ *
+ * Verify-FIRST ordering: `verifyReceipt` runs before `artifactLoader` is
+ * touched. Tampered receipts MUST NOT cause loader side effects.
+ */
+declare function materializeReplayEnvelope<TOutputs extends OutputContractMap = OutputContractMap>(receipt: ReceiptEnvelope, options: MaterializeReplayEnvelopeOptions<TOutputs>): Promise<ReplayEnvelope<TOutputs>>;
+//#endregion
+//#region src/agent/runtime.d.ts
+/**
+ * Resolves the runtime's behaviour for a single `ai.runAgent(intent)` call.
+ *
+ * Phase 19 ships an in-process default scheduler (the loop runs in the
+ * calling Promise), direct transport (provider.execute()), and in-memory
+ * transcript (the `conversation` array). Phase 20 promotes scheduler /
+ * transport / storage to the pluggable `AgentHost` adapter.
+ */
+declare function runAgent<TOutputs extends OutputContractMap = OutputContractMap>(intent: AgentIntent<TOutputs>, config?: LatticeConfig): Promise<AgentResult<TOutputs>>;
+//#endregion
+//#region src/agent/infra/cost-tracker.d.ts
+type CostBudgetStatus = "ok" | "warning" | "exceeded";
+interface CostTracker {
+  readonly kind: "cost-tracker";
+  /** Append a per-iteration Usage record. Mutates internal state. */
+  recordIteration(usage: Usage): void;
+  /** Returns the running sum across all recorded iterations. */
+  total(): Usage;
+  /**
+   * Reports budget status against `contract.budget`:
+   *   - "ok" — under 80% of maxCostUsd.
+   *   - "warning" — at or over 80% but under 100%.
+   *   - "exceeded" — at or over 100% of maxCostUsd.
+   * Returns "ok" when no budget is declared or when cumulative cost is null.
+   */
+  budgetStatus(budget?: BudgetInvariant): CostBudgetStatus;
+}
+declare function createCostTracker(): CostTracker;
+//#endregion
+//#region src/agent/infra/transcript-store.d.ts
+/**
+ * Token estimator used by `tailByTokens`. The default ~4 chars / token is
+ * the OpenAI rule of thumb for English text. Callers with provider-specific
+ * tokenizers can supply their own.
+ */
+type TokenEstimator = (text: string) => number;
+interface TranscriptStore {
+  readonly kind: "transcript-store";
+  append(turn: ConversationTurn): void;
+  all(): readonly ConversationTurn[];
+  /** Returns the first user turn (if any) + the most-recent `limit` turns. */
+  tail(limit: number): readonly ConversationTurn[];
+  /**
+   * Returns the first user turn (if any) + the most-recent turns whose
+   * combined token estimate fits within `maxTokens`. The default estimator
+   * is the ~4 chars / token rule; callers can override for provider-
+   * specific tokenizers.
+   */
+  tailByTokens(maxTokens: number, estimator?: TokenEstimator): readonly ConversationTurn[];
+}
+declare function createTranscriptStore(): TranscriptStore;
+//#endregion
+//#region src/agent/infra/goal-progress.d.ts
+/**
+ * GoalProgressTracker — Phase 21 (v1.2).
+ *
+ * Stuck-detection primitive. The caller declares a goal-satisfaction
+ * score per iteration (0..1); the tracker reports a coarse status the
+ * agent loop can use to back off or surface to the human.
+ */
+type ProgressStatus = "progressing" | "stalled" | "regressed";
+interface GoalProgressOptions {
+  /**
+   * Window of recent steps used for stall + regression detection.
+   * Default 3. The tracker waits until it has at least this many steps
+   * before reporting anything other than "progressing".
+   */
+  readonly windowSize?: number;
+  /** Max satisfaction delta across the window to count as "stalled". Default 0.02. */
+  readonly stallThreshold?: number;
+  /** Min drop from prior max to count as "regressed". Default 0.1. */
+  readonly regressionThreshold?: number;
+}
+interface GoalProgressStep {
+  readonly iterationIndex: number;
+  readonly goalSatisfaction: number;
+}
+interface GoalProgressTracker {
+  readonly kind: "goal-progress-tracker";
+  recordStep(step: GoalProgressStep): void;
+  status(): ProgressStatus;
+}
+declare function createGoalProgressTracker(options?: GoalProgressOptions): GoalProgressTracker;
+//#endregion
+//#region src/agent/infra/action-history.d.ts
+/**
+ * ActionHistory — Phase 21 (v1.2).
+ *
+ * Detects stuck patterns in the agent loop's tool-call sequence:
+ *   - "consecutive-identical-tool-call" — same (toolName, argsHash) N+ times in a row
+ *   - "ping-pong" — last 4 records alternate between 2 distinct (toolName, argsHash) pairs
+ *   - "no-progress" — reserved for callers wiring goal-progress feedback here
+ *
+ * Standalone (no dependency on the agent runtime); callers register the
+ * primitive externally and pump `recordAction` from their loop or hook.
+ */
+declare const STUCK_REASONS: readonly ["consecutive-identical-tool-call", "no-progress", "ping-pong"];
+type StuckReason = typeof STUCK_REASONS[number];
+interface ActionRecord {
+  readonly iterationIndex: number;
+  readonly toolName: string;
+  readonly argsHash: string;
+}
+interface ActionHistoryOptions {
+  /** Number of consecutive identical records that triggers the consecutive detector. Default 3. */
+  readonly consecutiveLimit?: number;
+}
+interface ActionHistory {
+  readonly kind: "action-history";
+  /**
+   * Append a record. Returns the latest StuckReason triggered by this
+   * record, or null when no detector fires. The most recent reason wins
+   * when multiple apply.
+   */
+  recordAction(action: ActionRecord): StuckReason | null;
+  history(): readonly ActionRecord[];
+}
+declare function createActionHistory(options?: ActionHistoryOptions): ActionHistory;
+//#endregion
+//#region src/agent/infra/permission-context.d.ts
+interface PermissionRule {
+  /** Match on tool name. String = exact match; RegExp = test. Both undefined = match-any. */
+  readonly toolName?: string | RegExp;
+  /**
+   * Optional resource matcher. The caller passes `resource` on each
+   * decide() invocation; this rule fires only when the rule's resource
+   * matches.
+   */
+  readonly resource?: string | RegExp;
+  readonly verdict: "allow" | "deny";
+  readonly reason?: string;
+}
+interface PermissionDecisionInput {
+  readonly toolName: string;
+  readonly iterationIndex: number;
+  readonly resource?: string;
+  readonly args?: unknown;
+}
+type PermissionVerdict = {
+  readonly allow: true;
+} | {
+  readonly allow: false;
+  readonly reason: string;
+};
+interface PermissionContext {
+  readonly kind: "permission-context";
+  decide(input: PermissionDecisionInput): PermissionVerdict;
+}
+declare function createPermissionContext(rules: readonly PermissionRule[]): PermissionContext;
+/**
+ * Hook handler shape suitable for registering on `BEFORE_TOOL` at
+ * BAND.SAFETY. Reads `toolName` and `iterationIndex` from the agent
+ * runtime's BEFORE_TOOL context shape (`{ iterationIndex, toolName,
+ * args }`) and translates a deny verdict into `controls.deny(reason)`.
+ */
+interface PermissionHookContext {
+  readonly iterationIndex: number;
+  readonly toolName: string;
+  readonly resource?: string;
+  readonly args?: unknown;
+}
+declare function createPermissionGuardHook(context: PermissionContext): HookHandler<PermissionHookContext>;
+/**
+ * Convenience: returns RegisterOptions for the SAFETY-band registration.
+ * Callers do `pipeline.register("BEFORE_TOOL", hook, permissionGuardRegisterOptions())`.
+ */
+declare function permissionGuardRegisterOptions(): RegisterOptions;
+//#endregion
+//#region src/agent/eval.d.ts
+/**
+ * Summary of an agent run sufficient for regression analysis. Callers
+ * typically derive this from an `AgentSuccess` via `iterations.length` and
+ * cumulative `usage`. The schema is intentionally minimal so callers can
+ * persist + load it across runs without dragging the full ReplayEnvelope.
+ */
+interface AgentRunSnapshot {
+  readonly iterationsToGoal: number;
+  readonly usage: Usage;
+}
+interface EvalOptions {
+  /**
+   * Maximum tolerated INCREASE in iterations-to-goal versus the baseline.
+   * Default 1 (one extra iteration tolerated). Set to 0 to require parity.
+   */
+  readonly iterationsToGoalRegressionLimit?: number;
+  /**
+   * Maximum tolerated FRACTIONAL cost increase versus the baseline.
+   * Default 0.10 (10% increase tolerated). Compared as
+   * `(current - baseline) / baseline`. Cost regressions are only
+   * considered when BOTH snapshots have a non-null `costUsd`; mixed-cost
+   * snapshots emit a `mixed-cost-unknown` regression so callers can decide
+   * how to handle them.
+   */
+  readonly costUsdRegressionLimit?: number;
+}
+type EvalRegressionKind = "iterations-to-goal" | "cost-regression" | "mixed-cost-unknown";
+interface EvalRegression {
+  readonly kind: EvalRegressionKind;
+  readonly baseline: number | null;
+  readonly current: number | null;
+  readonly limit: number;
+  readonly message: string;
+}
+interface AgentEvalResult {
+  readonly ok: boolean;
+  readonly regressions: ReadonlyArray<EvalRegression>;
+}
+declare function evalAgentRun(baseline: AgentRunSnapshot, current: AgentRunSnapshot, options?: EvalOptions): AgentEvalResult;
+//#endregion
+//#region src/storage/local.d.ts
+interface LocalArtifactStoreOptions {
+  readonly id?: string;
+}
+declare function createLocalArtifactStore(rootDir: string | URL, options?: LocalArtifactStoreOptions): ArtifactStore;
+//#endregion
+//#region src/storage/memory.d.ts
+interface MemoryArtifactStoreOptions {
+  readonly id?: string;
+}
+declare function createMemoryArtifactStore(options?: MemoryArtifactStoreOptions): ArtifactStore;
+//#endregion
+//#region src/version.d.ts
+declare const latticeVersion = "0.0.0";
+//#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 };
+//# sourceMappingURL=index.d.ts.map