@full-self-browsing/lattice 1.3.0 → 1.5.0

package/dist/provider-C2IfKsvz.d.ts

@@ -0,0 +1,1178 @@
+import { i as ArtifactKind, r as ArtifactInput, s as ArtifactRef } from "./artifact-Bg6mJGnm.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#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" | "stream.start" | "stream.complete" | "stream.failed" | "fallback.activated" | "validation.complete" | "validation.failed" | "artifact.created" | "run.complete" | "run.failed" | "tool.call" | "replay.offline" | "replay.live" | "step.transition" | "recovery.start" | "recovery.complete" | "recovery.failed" | "capabilities.negotiation.fallback";
+interface RunEvent {
+  readonly kind: RunEventKind;
+  readonly timestamp: string;
+  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/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/plan/plan.d.ts
+type ExecutionPlanStatus = "stub" | "planned" | "no-route" | "running" | "completed" | "failed";
+type ExecutionStageKind = "analysis" | "transforms" | "context-packing" | "provider-packaging" | "tool-execution" | "execution" | "validation" | "tripwire" | "persistence" | "replay";
+type ExecutionStageStatus = "pending" | "running" | "completed" | "skipped" | "failed";
+interface ExecutionPlanStage {
+  readonly id: string;
+  readonly kind: ExecutionStageKind;
+  readonly status: ExecutionStageStatus;
+  readonly inputArtifacts?: readonly string[];
+  readonly outputArtifacts?: readonly string[];
+  readonly warnings: readonly string[];
+  readonly metadata?: Record<string, unknown>;
+}
+interface RouteRejectReason {
+  readonly code: string;
+  readonly message: string;
+}
+interface RouteCandidate {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly capability: ModelCapability;
+  readonly score: number;
+  readonly accepted: boolean;
+  readonly reasons: readonly RouteRejectReason[];
+  readonly estimates: RouteEstimates;
+}
+interface RouteEstimates {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly costUsd?: number;
+  readonly latencyMs?: number;
+}
+interface SelectedRoute {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly score: number;
+  readonly estimates: RouteEstimates;
+  readonly inputModalities: readonly CapabilityModality[];
+  readonly outputModalities: readonly CapabilityModality[];
+  readonly fileTransport: readonly ProviderTransportMode[];
+}
+interface FallbackRoute {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly score: number;
+  readonly reason: "policy-preserving-fallback";
+}
+interface RouteDecision {
+  readonly catalogVersion: string;
+  readonly selected?: SelectedRoute;
+  readonly candidates: readonly RouteCandidate[];
+  readonly rejected: readonly RouteCandidate[];
+  readonly fallbackChain: readonly FallbackRoute[];
+  readonly noRouteReasons: readonly RouteRejectReason[];
+}
+interface ContextPackPlan {
+  readonly id: string;
+  readonly tokenBudget: number;
+  readonly estimatedTokens: number;
+  readonly included: readonly ContextPackItemPlan[];
+  readonly summarized: readonly ContextPackItemPlan[];
+  readonly archived: readonly ContextPackItemPlan[];
+  readonly omitted: readonly ContextPackItemPlan[];
+  readonly warnings: readonly string[];
+}
+interface ContextPackItemPlan {
+  readonly artifactId?: string;
+  readonly sessionTurnId?: string;
+  readonly reason: string;
+  readonly estimatedTokens: number;
+  readonly trust: "developer" | "user" | "tool" | "model-summary";
+}
+interface ProviderPackagingPlan {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly artifacts: readonly ProviderPackagedArtifactPlan[];
+  readonly warnings: readonly string[];
+}
+interface ProviderPackagedArtifactPlan {
+  readonly artifactId: string;
+  readonly transport: ProviderTransportMode;
+  readonly mediaType?: string;
+  readonly lineageTransform: "provider-packaging";
+  readonly providerRequest?: ProviderPackagedArtifactRequestPlan;
+  readonly warnings: readonly string[];
+}
+type ProviderPackagedArtifactSourceType = ProviderTransportMode | "file-reference";
+interface ProviderPackagedArtifactRequestPlan {
+  readonly shape: string;
+  readonly sourceType: ProviderPackagedArtifactSourceType;
+  readonly reason: string;
+  readonly mediaType?: string;
+  readonly sizeBytes?: number;
+  readonly reference?: ProviderPackagedArtifactReferencePlan;
+}
+interface ProviderPackagedArtifactReferencePlan {
+  readonly kind: "url" | "file-id" | "file-uri" | "storage";
+  readonly metadataKey?: string;
+}
+interface ProviderAttemptRecord {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly status: "pending" | "running" | "succeeded" | "failed" | "cancelled";
+  readonly startedAt?: string;
+  readonly completedAt?: string;
+  readonly error?: string;
+  readonly usage?: UsageRecord;
+  readonly metadata?: Record<string, unknown>;
+}
+interface UsageRecord {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly totalTokens?: number;
+  readonly costUsd?: number;
+  readonly latencyMs?: number;
+}
+interface ExecutionPlan {
+  readonly id: string;
+  readonly kind: "execution-plan";
+  readonly version: 1;
+  readonly createdAt: string;
+  readonly status: ExecutionPlanStatus;
+  readonly task: string;
+  readonly outputNames: readonly string[];
+  readonly artifactRefs: readonly ArtifactRef[];
+  readonly route: RouteDecision;
+  readonly stages: readonly ExecutionPlanStage[];
+  readonly context?: ContextPackPlan;
+  readonly providerPackaging?: ProviderPackagingPlan;
+  readonly attempts: readonly ProviderAttemptRecord[];
+  readonly warnings: readonly string[];
+  readonly metadata?: Record<string, unknown>;
+}
+interface ExecutionPlanStub {
+  readonly id: string;
+  readonly kind: "plan-stub";
+  readonly createdAt: string;
+  readonly status: "stub";
+  readonly stages: readonly [];
+  readonly warnings: readonly string[];
+}
+type ResultPlan = ExecutionPlan | ExecutionPlanStub;
+//#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
+type TrustLabel = "developer" | "user" | "tool" | "model-summary";
+interface ContextPack extends ContextPackPlan {
+  readonly kind: "context-pack";
+}
+interface BuildContextPackInput {
+  readonly task: string;
+  readonly artifacts: readonly ArtifactInput[];
+  readonly route?: SelectedRoute;
+  readonly session?: SessionRecord;
+  readonly tokenBudget?: number;
+}
+interface ContextSummarizer {
+  summarize(input: {
+    readonly artifacts: readonly ArtifactRef[];
+    readonly budgetTokens: number;
+  }): Promise<readonly ArtifactRef[]> | readonly ArtifactRef[];
+}
+declare function buildContextPack(input: BuildContextPackInput): ContextPack;
+declare function estimateArtifactTokens(artifact: ArtifactInput | ArtifactRef): number;
+declare function estimateTokens(value: string): number;
+declare function toContextArtifactRefs(artifacts: readonly ArtifactInput[]): readonly ArtifactRef[];
+//#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/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/tools/tool-use.d.ts
+interface ToolUseRequest {
+  readonly id: string;
+  readonly name: string;
+  readonly args: unknown;
+}
+declare function parseToolUseEnvelope(responseText: string): ReadonlyArray<ToolUseRequest> | null;
+//#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/tools/tool-call-validation.d.ts
+type ToolCallValidationFailureReason = "unknown_tool" | "invalid_args" | "extra_fields";
+interface ValidatedToolCall {
+  readonly id: string;
+  readonly name: string;
+  readonly args: unknown;
+}
+type ToolCallValidationTool = Pick<ToolDefinition, "name" | "inputSchema">;
+interface ValidateToolCallsOption {
+  readonly tools: readonly ToolCallValidationTool[];
+  readonly onFailure?: "throw" | "drop" | "callback";
+  readonly onValidationFailure?: (error: ToolCallValidationError) => void | Promise<void>;
+  readonly allowExtraFields?: boolean;
+}
+declare class ToolCallValidationError extends Error {
+  readonly kind: "tool-call-validation";
+  readonly reason: ToolCallValidationFailureReason;
+  readonly toolName: string;
+  readonly attemptedArgs: unknown;
+  readonly validationIssues: readonly ValidationIssue[];
+  readonly requestId: string;
+  constructor(input: {
+    readonly reason: ToolCallValidationFailureReason;
+    readonly toolName: string;
+    readonly attemptedArgs: unknown;
+    readonly validationIssues?: readonly ValidationIssue[];
+    readonly requestId: string;
+  });
+}
+declare function validateToolCallRequests(requests: readonly ToolUseRequest[], option: ValidateToolCallsOption | undefined): Promise<readonly ValidatedToolCall[] | undefined>;
+//#endregion
+//#region src/providers/quirks.d.ts
+/**
+ * Universal 5-boolean shape every first-party adapter populates (SC-1 / D-03).
+ *
+ * - `supportsToolChoice`     — adapter supports tool_choice / forced-tool-call mode
+ * - `parallelToolCalls`      — adapter supports parallel (multi-tool) calls in one turn
+ * - `structuredOutputs`      — adapter honors response_format JSON schema binding
+ * - `responseFormatHonored`  — adapter treats response_format as authoritative (false
+ *                              for vanilla openai-compat servers; true for OpenAI/Anthropic/Gemini)
+ * - `streamingDiverges`      — streamed output differs from buffered output (true for
+ *                              some self-hosted servers; false for OpenAI/Anthropic/Gemini)
+ */
+interface AdapterQuirks {
+  readonly supportsToolChoice: boolean;
+  readonly parallelToolCalls: boolean;
+  readonly structuredOutputs: boolean;
+  readonly responseFormatHonored: boolean;
+  readonly streamingDiverges: boolean;
+}
+/**
+ * Anthropic adapter quirks (extends AdapterQuirks with 3 Anthropic-specific flags).
+ *
+ * CITED: Anthropic prompt caching docs — https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+ *   - `promptCachingSupported`: cache_control on system and user turns is supported on
+ *     all active Claude models (claude-3-* and claude-*-4 families).
+ *
+ * CITED: Anthropic extended thinking docs — https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking
+ *   - `extendedThinkingSupported`: thinking blocks (claude-3-7-sonnet+ and claude-*-4) available
+ *     via the "thinking" request parameter.
+ *
+ * CITED: Anthropic tool use docs — https://docs.anthropic.com/en/docs/build-with-claude/tool-use
+ *   - `toolUseInputSchemaStrict`: Anthropic tool_use blocks require strict JSON Schema in
+ *     the input_schema field; the adapter enforces this at call time.
+ */
+interface AnthropicQuirks extends AdapterQuirks {
+  readonly promptCachingSupported: boolean;
+  readonly extendedThinkingSupported: boolean;
+  readonly toolUseInputSchemaStrict: boolean;
+}
+/**
+ * OpenAI adapter quirks (extends AdapterQuirks with 2 OpenAI-specific flags).
+ *
+ * CITED: OpenAI structured outputs docs — https://platform.openai.com/docs/guides/structured-outputs
+ *   - `strictModeSupported`: function-calling strict:true mode available on
+ *     gpt-4o-2024-08-06+ and o1+ series.
+ *   - `structuredOutputsTier2`: json_schema response_format mode (tier-2 structured outputs)
+ *     available on gpt-4o and gpt-4o-mini series.
+ */
+interface OpenAIQuirks extends AdapterQuirks {
+  readonly strictModeSupported: boolean;
+  readonly structuredOutputsTier2: boolean;
+}
+/**
+ * OpenAI-compatible adapter quirks (same 5 base booleans, no new fields).
+ *
+ * Conservative defaults: openai-compat servers (vLLM, TGI, Ollama, custom)
+ * vary widely in which response_format and tool_choice features they implement.
+ * The factory populates the base fields conservatively (responseFormatHonored:
+ * false, structuredOutputs: false) because the endpoint could be anything.
+ * Consumers pointing at a known-good server should verify quirk values manually.
+ */
+interface OpenAICompatQuirks extends AdapterQuirks {}
+/**
+ * Gemini adapter quirks (extends AdapterQuirks with 3 Gemini-specific flags).
+ *
+ * CITED: Gemini API docs — https://ai.google.dev/api/generate-content#v1beta.GenerationConfig
+ *   - `responseSchemaSupported`: responseSchema / responseJsonSchema on generateContent
+ *     is available on gemini-1.5-pro+ and gemini-2.x models.
+ *   - `safetySettingsConfigurable`: all 4 harm categories (HARASSMENT, HATE_SPEECH,
+ *     SEXUALLY_EXPLICIT, DANGEROUS_CONTENT) can be set to BLOCK_NONE — verified in
+ *     gemini.ts:50-55.
+ *
+ * CITED: Gemini API system instruction docs — https://ai.google.dev/api/generate-content#v1beta.GenerateContentRequest
+ *   - `systemInstructionSupported`: systemInstruction field on GenerateContentRequest
+ *     available on gemini-1.5+ series and later.
+ */
+interface GeminiQuirks extends AdapterQuirks {
+  readonly responseSchemaSupported: boolean;
+  readonly safetySettingsConfigurable: boolean;
+  readonly systemInstructionSupported: boolean;
+}
+/**
+ * xAI adapter quirks (extends AdapterQuirks with 2 xAI-specific flags).
+ *
+ * CITED: xAI API docs — https://docs.x.ai/api/endpoints
+ *   - `reasoningTokensReported`: completion_tokens_details.reasoning_tokens reported
+ *     in xAI API responses — verified in xai.ts:46-72.
+ *   - `logprobsSupported`: grok-4.20 silently ignores logprobs param per observed
+ *     behavior; flag indicates whether logprobs fields will be populated.
+ */
+interface XaiQuirks extends AdapterQuirks {
+  readonly reasoningTokensReported: boolean;
+  readonly logprobsSupported: boolean;
+}
+/**
+ * OpenRouter adapter quirks (extends AdapterQuirks with 3 OpenRouter-specific flags).
+ *
+ * CITED: OpenRouter provider routing docs — https://openrouter.ai/docs/provider-routing
+ *   - `providerRoutingArraySupported`: the `provider.order` / `provider.only` /
+ *     `provider.ignore` arrays are supported for explicit routing control.
+ *   - `floorPricingHints`: `max_price`, `sort: "throughput" | "price"` hints on
+ *     GenerationConfig for cost-aware routing.
+ *   - `allowFallbacks`: `provider.allow_fallbacks: boolean` controls whether OpenRouter
+ *     retries with a different upstream provider on failure.
+ */
+interface OpenRouterQuirks extends AdapterQuirks {
+  readonly providerRoutingArraySupported: boolean;
+  readonly floorPricingHints: boolean;
+  readonly allowFallbacks: boolean;
+}
+/**
+ * LM Studio adapter quirks (extends AdapterQuirks with 2 LM Studio-specific flags).
+ *
+ * CITED: lmstudio-bug-tracker — Jinja template mismatches between model training and
+ * LM Studio server defaults cause output format corruption.
+ *   - `customChatTemplateRiskFlag`: LM Studio servers can ship with broken chat templates
+ *     that don't match the model's training template; flag signals this risk.
+ *
+ * VERIFIED: lm-studio.ts:35-37 — apiKey is optional for LM Studio local servers.
+ *   - `noAuthRequired`: apiKey is NOT required for local LM Studio instances (no
+ *     authentication by default on localhost:1234).
+ */
+interface LmStudioQuirks extends AdapterQuirks {
+  readonly customChatTemplateRiskFlag: boolean;
+  readonly noAuthRequired: boolean;
+}
+/**
+ * LiteLLM adapter quirks (extends AdapterQuirks with gateway-specific flags).
+ *
+ * LiteLLM is consumed as an OpenAI-compatible gateway. Lattice does not start,
+ * embed, or depend on a LiteLLM gateway process; these flags describe the
+ * helper's supported gateway metadata contract over HTTP.
+ */
+interface LiteLLMQuirks extends AdapterQuirks {
+  readonly gatewayMetadataSupported: boolean;
+  readonly gatewayFallbacksSupported: boolean;
+  readonly openAIErrorMapping: boolean;
+}
+//#endregion
+//#region src/capabilities/profile.d.ts
+/**
+ * Closed enum of the 8 Lattice transport adapters (D-06). Adding a new
+ * adapter is a typed breaking change. Phase 34 quirk dispatch reads this
+ * field.
+ */
+type CapabilityAdapter = "openrouter" | "anthropic" | "openai" | "openai-compat" | "xai" | "gemini" | "lm-studio" | "litellm";
+/**
+ * Closed enum of the 5 training-lineage buckets (D-14). Receipt v1.2
+ * (Phase 38) carries this value verbatim via the `modelClass` field.
+ * Stable across model patches — gpt-4o-2024-05-13 and gpt-4o-2024-08-06
+ * share a trainingClass so receipts remain comparable across rebuilds.
+ */
+type TrainingClass = "frontier_rlhf" | "mid_tier_rlhf" | "open_weight_instruct" | "open_weight_base" | "local_quantized";
+/**
+ * Closed enum of the 5 recommended prompt-tuning buckets (research open
+ * question 2). DISTINCT from `TrainingClass`: `reasoning` is orthogonal
+ * to lineage (a frontier RLHF model with hidden_cot routes to the
+ * `reasoning` strategy bucket); `local` is the granularity boundary
+ * for the deployed-locally strategy bucket (vs the `local_quantized`
+ * lineage signal). Phase 35 prompt-scaffold dispatch reads this field.
+ */
+type RecommendedPromptStrategy = "frontier" | "mid_tier" | "open_weight" | "reasoning" | "local";
+/**
+ * Closed enum of the 7 known model-class output-shape failure modes at
+ * v1.3.0 (D-12). Adding a member in v1.4+ is an intentional typed
+ * breaking change — Phase 36 sanitizer dispatch enforces exhaustiveness
+ * via a `_exhaustive: never` switch (see test-d/capabilities.test-d.ts).
+ */
+type KnownFailureMode = "internal_envelope_leak" | "reasoning_tag_leak" | "system_prompt_echo" | "template_artifact_leak" | "hallucinated_tool_name" | "malformed_tool_arguments" | "premature_termination";
+/**
+ * Closed enum of the 5 reasoning-surface shapes a model exposes. Drives
+ * the Phase 36 sanitizer's choice of leak-cleanup pass (e.g., `<think>`
+ * tag stripping for `inlined_tags`).
+ */
+type ReasoningSurface = "none" | "hidden_cot" | "inlined_tags" | "interleaved_thinking" | "streamed_reasoning";
+/**
+ * Closed enum of the 5 tool-call surface shapes a model exposes. Drives
+ * the Phase 37 tool-call validator's choice of arguments parser.
+ */
+type ToolCallSurface = "none" | "native_strict" | "native_lenient" | "json_only" | "text_only";
+type ModelCapabilityProfilePricingKey = "prompt" | "completion" | "image" | "audio" | "web_search" | "internal_reasoning" | "input_cache_read" | "input_cache_write";
+type ModelCapabilityProfilePricing = Partial<Record<ModelCapabilityProfilePricingKey, string>>;
+type ModelCapabilityProfileModality = "text" | "image" | "audio" | "video" | "file" | "embeddings";
+/**
+ * Phase 33 — D-05 / D-08 — Capability profile for one (adapter, model)
+ * pair. Sibling to `ModelCapability`, not a replacement. Built-time baked
+ * via the OpenRouter snapshot generator (Phase 33-03) plus hand-edited
+ * supplemental static profiles (Phase 33-04).
+ *
+ * Canonical key: `${adapter}:${modelId}` — one profile per (adapter,
+ * model) pair. `openrouter:openai/gpt-oss-120b` and `openai:gpt-oss-120b`
+ * are two distinct entries with the same `originFamily: "openai"`.
+ */
+interface ModelCapabilityProfile {
+  /**
+   * The model identifier as the adapter sees it. For OpenRouter this is
+   * the `vendor/model` shape (e.g., `openai/gpt-oss-120b`); for direct
+   * adapters this is the provider's native id (e.g., `claude-opus-4`).
+   * Combined with `adapter` to form the canonical lookup key `${adapter}:${id}` (D-08).
+   */
+  readonly id: string;
+  /**
+   * The Lattice transport adapter that ships this profile (D-05 /
+   * D-06). Phase 34 adapter-quirk dispatch reads this field. Closed
+   * union of 8 values.
+   */
+  readonly adapter: CapabilityAdapter;
+  /**
+   * The model creator (D-07). Open extensible string — new orgs emerge
+   * frequently and should not break the type. Examples: `openai`,
+   * `anthropic`, `meta`, `mistral`, `google`, `xai`, `deepseek`, `qwen`.
+   * Phase 35 prompt-scaffold dispatch falls back to
+   * `recommendedPromptStrategy` for unknown originFamily values.
+   */
+  readonly originFamily: string;
+  /**
+   * Training-lineage classification (D-14). Receipt v1.2 `modelClass`
+   * (Phase 38) carries this value verbatim. Drives the failure-mode
+   * default set in the classifier.
+   */
+  readonly trainingClass: TrainingClass;
+  /**
+   * Shape of the model's reasoning output. Drives the Phase 36
+   * sanitizer's reasoning-leak cleanup pass.
+   */
+  readonly reasoningSurface: ReasoningSurface;
+  /**
+   * Shape of the model's tool-call output. Drives the Phase 37
+   * tool-call validator's arguments parser.
+   */
+  readonly toolCallSurface: ToolCallSurface;
+  /**
+   * The actual context window the adapter will accept on a request, in
+   * tokens. For OpenRouter this is `top_provider.context_length ?? context_length`
+   * (Phase 33 Pitfall 2) — what OpenRouter routing actually offers, not
+   * the model card's aspirational maximum.
+   */
+  readonly contextWindow: number;
+  readonly pricing?: ModelCapabilityProfilePricing;
+  readonly inputModalities?: readonly ModelCapabilityProfileModality[];
+  readonly outputModalities?: readonly ModelCapabilityProfileModality[];
+  readonly supportedParameters?: readonly string[];
+  /**
+   * Failure modes this model class is known to exhibit (D-14). Class-
+   * derived defaults plus per-family overrides. Phase 36 sanitizer
+   * dispatch exhaustively switches on each entry.
+   */
+  readonly knownFailureModes: readonly KnownFailureMode[];
+  /**
+   * Recommended prompt-tuning bucket (research open question 2). Phase
+   * 35 prompt-scaffold dispatch reads this field. Distinct from
+   * `trainingClass` — see `RecommendedPromptStrategy` JSDoc.
+   */
+  readonly recommendedPromptStrategy: RecommendedPromptStrategy;
+}
+/**
+ * Frozen list of every `KnownFailureMode` member. Useful for exhaustive
+ * iteration in downstream tests and Phase 36 sanitizer registration.
+ * Adding a new mode requires updating this array AND the
+ * `KnownFailureMode` union AND the Phase 36 exhaustive switch — the
+ * `satisfies` clause enforces array-vs-union parity at compile time.
+ */
+declare const ALL_KNOWN_FAILURE_MODES: readonly ["internal_envelope_leak", "reasoning_tag_leak", "system_prompt_echo", "template_artifact_leak", "hallucinated_tool_name", "malformed_tool_arguments", "premature_termination"];
+/**
+ * Frozen list of every `TrainingClass` member. Useful for exhaustive
+ * iteration when constructing the failure-mode defaults table (D-14)
+ * and for Phase 38 receipt-class enumeration.
+ */
+declare const ALL_TRAINING_CLASSES: readonly ["frontier_rlhf", "mid_tier_rlhf", "open_weight_instruct", "open_weight_base", "local_quantized"];
+//#endregion
+//#region src/capabilities/sanitizer-recommendations.d.ts
+/**
+ * D-13 — Phase 36 sanitizer registration keys. Closed string-literal union;
+ * adding a 4th sanitizer in v1.4 is an intentional typed breaking change
+ * that mirrors the `KnownFailureMode` discipline.
+ *
+ * Phase 36 registers implementations under EXACTLY these 3 ids:
+ *   - "stripReasoningTags"          — strips <think>/</think> (and model-specific) reasoning tags
+ *   - "stripChatTemplateArtifacts"  — removes chat-template artifact leaks from output
+ *   - "unwrapInternalEnvelope"      — extracts the user-visible payload from internal wrapper
+ */
+type SanitizerKey = "stripReasoningTags" | "stripChatTemplateArtifacts" | "unwrapInternalEnvelope";
+/**
+ * D-14 + D-16 — Exhaustive mapping from KnownFailureMode to SanitizerKey
+ * (or null when the failure mode is not a sanitizer concern). The
+ * `Record<KnownFailureMode, ...>` annotation enforces compile-time
+ * exhaustiveness — adding a new mode to KnownFailureMode in v1.4+ will
+ * cause a type-check failure here until the planner decides on a mapping.
+ *
+ * Null semantics per D-16:
+ *   - system_prompt_echo     -> null (consumer-side prompt engineering, not a sanitizer)
+ *   - hallucinated_tool_name -> null (Phase 37 tool-call validator territory)
+ *   - malformed_tool_arguments -> null (Phase 37 tool-call validator territory)
+ *   - premature_termination  -> null (consumer-side max_tokens config)
+ */
+declare const SANITIZER_BY_FAILURE_MODE: Record<KnownFailureMode, SanitizerKey | null>;
+/**
+ * D-14 / D-15 — Maps a list of known failure modes through the recommendation
+ * table and filters nulls. `recommendedSanitizers` always contains real keys.
+ *
+ * Implementation:
+ *   - Iterates modes in input order (Set insertion order)
+ *   - Skips null entries (D-16)
+ *   - Deduplicates via Set (so repeated modes yield one key)
+ *   - Returns a readonly array (frozen via spread)
+ *
+ * Consumers use this to populate `NegotiatedCapabilities.recommendedSanitizers`.
+ * Phase 36 registers implementations under the same key ids.
+ */
+declare function getRecommendedSanitizers(modes: readonly KnownFailureMode[]): readonly SanitizerKey[];
+//#endregion
+//#region src/capabilities/negotiate.d.ts
+/**
+ * Phase 34 — SC-3 — Consumer-facing capability shape returned by
+ * `adapter.negotiateCapabilities()` and the top-level `negotiateCapabilities()`
+ * helper. Simplified relative to `ModelCapabilityProfile` (the registry
+ * profile); consumers needing the full enum (e.g., native_strict vs
+ * native_lenient) should look up the profile directly via `getCapabilityProfile`.
+ *
+ * Source values (D-09):
+ *   - "live"               — /models endpoint hit, registry profile intersected
+ *   - "registry-fallback"  — /models hit failed transiently (5xx/network/timeout),
+ *                            fell back to Phase 33 static registry (D-09)
+ *   - "registry"           — adapter intentionally has no /models endpoint
+ *                            (LM Studio, openai-compat), OR consumer-adapter
+ *                            fallback path (D-04)
+ */
+interface NegotiatedCapabilities {
+  readonly modelId: string;
+  readonly contextWindow: number;
+  readonly supports: {
+    readonly nativeToolCalling: boolean;
+    readonly structuredOutputs: boolean;
+    readonly parallelToolCalls: boolean;
+    readonly extendedThinking: boolean;
+    readonly streaming: boolean;
+  };
+  readonly knownFailureModes: readonly KnownFailureMode[];
+  readonly recommendedSanitizers: readonly SanitizerKey[];
+  readonly source: "live" | "registry-fallback" | "registry";
+}
+/**
+ * D-10 — Typed error thrown by `negotiateCapabilities` when the adapter's
+ * /models endpoint returns 401 or 403. Mirrors `AgentDeniedError` shape
+ * (the only existing v1.2 `class extends Error` precedent in agent/types.ts).
+ *
+ * Why throw (vs return-as-error-union):
+ *   - Auth errors indicate a broken apiKey config — it is the caller's bug
+ *   - Silently falling back would hide the misconfiguration
+ *   - `try/catch` ergonomics work cleanly with `class extends Error`
+ *   - `instanceof NegotiationAuthError` is the consumer ergonomic
+ *
+ * IMPORTANT: `NegotiationAuthError` is throwable from `negotiateCapabilities`
+ * ONLY — never from `execute()`. Auth errors from /models do NOT contaminate
+ * the request path.
+ *
+ * T-34-01-02: message field set by adapter implementations in Plans 02-04
+ * MUST NOT include the apiKey. Only adapter, modelId, and httpStatus are carried.
+ */
+declare class NegotiationAuthError extends Error {
+  readonly kind: "negotiation-auth-failed";
+  readonly adapter: CapabilityAdapter;
+  readonly modelId: string;
+  readonly httpStatus: 401 | 403;
+  constructor(adapter: CapabilityAdapter, modelId: string, httpStatus: 401 | 403, message: string);
+}
+/**
+ * Phase 34 — D-02 / D-04 — Top-level helper for capability negotiation.
+ *
+ * Pitfall 5 (zero live-path logic): delegates verbatim to
+ * `adapter.negotiateCapabilities(modelId)` when the adapter implements it.
+ * No inflight-coalescing, no cache, no source value transformation. The
+ * adapter owns all of that.
+ *
+ * When the adapter has NO `negotiateCapabilities` (consumer-provided v1.2
+ * adapters, third-party adapters), falls back to the Phase 33 registry
+ * via `synthesizeNegotiatedCapabilitiesFromRegistry` with source "registry"
+ * (D-04). Consumer adapters get useful behavior out of the box without any
+ * migration code.
+ *
+ * Verifiable per Pitfall 5: grep for `new Map<` in this function body should
+ * return zero matches; LOC count of the function body is < 10 lines.
+ */
+declare function negotiateCapabilities(adapter: ProviderAdapter, modelId: string): Promise<NegotiatedCapabilities>;
+/**
+ * Phase 34 — D-04 / D-09 — Synthesizes a `NegotiatedCapabilities` shape from
+ * the Phase 33 static registry. Used by:
+ *   1. The top-level helper (above) for consumer-adapter fallback (D-04).
+ *   2. Per-adapter negotiate() implementations (Plans 02-05) when /models
+ *      fails transiently (D-09, source "registry-fallback").
+ *
+ * Exported as a named export so Plans 02-05 can reuse the fallback synthesis
+ * without duplicating the mapping logic.
+ *
+ * Implementation note: the boolean derivations are intentionally minimal
+ * (heuristic, not definitive). The per-adapter negotiate() implementations
+ * in Plans 02-05 own the richer derivation from live /models data.
+ * This helper is a SAFETY NET for adapters without /models endpoints and
+ * for transient-fallback cases.
+ *
+ * Anti-shape (documented in CONTEXT.md <specifics>): boolean `nativeToolCalling`
+ * loses the strict-vs-lenient distinction in `toolCallSurface`. Consumers
+ * needing the enum should look up the profile directly via `getCapabilityProfile`.
+ */
+declare function synthesizeNegotiatedCapabilitiesFromRegistry(adapter: CapabilityAdapter, modelId: string, source: "registry" | "registry-fallback"): NegotiatedCapabilities;
+//#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";
+}
+type ProviderToolDefinition = Pick<ToolDefinition<StandardSchemaV1>, "name" | "description" | "inputSchema">;
+type ProviderToolChoice = "auto" | "none" | "required" | {
+  readonly type: "tool";
+  readonly name: string;
+};
+interface ProviderStructuredOutputRequest {
+  readonly output: string;
+  readonly schema: StandardSchemaV1;
+  readonly name?: string;
+  readonly strict?: boolean;
+}
+interface ProviderRunRequest {
+  readonly task: string;
+  readonly artifacts: readonly ArtifactInput[];
+  readonly outputs: readonly string[];
+  readonly outputContracts?: OutputContractMap;
+  readonly policy?: unknown;
+  readonly signal?: AbortSignal;
+  readonly plan?: ExecutionPlan;
+  readonly contextPack?: ContextPack;
+  readonly providerPackaging?: ProviderPackagingPlan;
+  readonly packagedArtifacts?: readonly ArtifactRef[];
+  /**
+   * Phase 39 — opt-in prompt-cache prefix (DELEG-04). Adapters that support
+   * block-granular caching (Anthropic) hoist this to a `cache_control`-marked
+   * system content block; adapters that ignore it MUST receive the prefix
+   * folded into `task` by the caller instead (the crew dispatcher gates on
+   * `quirks.promptCachingSupported`). The field is advisory, additive, and
+   * absent for all existing callers — follows the Phase 37 `toolCalls`
+   * additive-field precedent (request/response additive fields accepted;
+   * `ProviderAdapter` METHODS frozen per INV-03).
+   */
+  readonly cacheSystemPrefix?: string;
+  /**
+   * Phase 51 — Provider-only native tool declarations. This is an explicit
+   * opt-in so existing `ai.run()` and agent prompt-reencoded behavior does not
+   * change merely because output contracts or tools exist elsewhere.
+   */
+  readonly nativeTools?: readonly ProviderToolDefinition[];
+  readonly nativeToolChoice?: ProviderToolChoice;
+  readonly nativeStructuredOutput?: ProviderStructuredOutputRequest;
+}
+interface ProviderGatewayMetadata {
+  readonly used: boolean;
+  readonly requestedModel?: string;
+  readonly observedModel?: string;
+  readonly fallbackModels?: readonly string[];
+  readonly policy?: Record<string, unknown>;
+}
+interface ProviderFinishMetadata {
+  readonly reason?: string;
+  readonly toolCallIds?: readonly string[];
+  readonly metadata?: Record<string, unknown>;
+}
+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 toolCalls?: readonly ValidatedToolCall[];
+  readonly gateway?: ProviderGatewayMetadata;
+  readonly finish?: ProviderFinishMetadata;
+  readonly rawResponse?: unknown;
+}
+interface ProviderStreamTextDeltaChunk {
+  readonly kind: "text-delta";
+  readonly output?: string;
+  readonly text: string;
+}
+interface ProviderStreamOutputChunk {
+  readonly kind: "output";
+  readonly output: string;
+  readonly value: unknown;
+}
+interface ProviderStreamUsageChunk {
+  readonly kind: "usage";
+  readonly usage?: UsageRecord;
+  readonly normalizedUsage?: Usage;
+}
+interface ProviderStreamGatewayChunk {
+  readonly kind: "gateway";
+  readonly gateway: ProviderGatewayMetadata;
+}
+interface ProviderStreamToolCallChunk {
+  readonly kind: "tool-call";
+  readonly toolCall: ValidatedToolCall;
+}
+interface ProviderStreamCompleteChunk {
+  readonly kind: "complete";
+  readonly rawOutputs?: Record<string, unknown>;
+  readonly artifactRefs?: readonly (ArtifactInput | ArtifactRef)[];
+  readonly usage?: UsageRecord;
+  readonly normalizedUsage?: Usage;
+  readonly gateway?: ProviderGatewayMetadata;
+  readonly toolCalls?: readonly ValidatedToolCall[];
+  readonly finish?: ProviderFinishMetadata;
+  readonly rawResponse?: unknown;
+}
+type ProviderStreamChunk = ProviderStreamTextDeltaChunk | ProviderStreamOutputChunk | ProviderStreamUsageChunk | ProviderStreamGatewayChunk | ProviderStreamToolCallChunk | ProviderStreamCompleteChunk;
+type ProviderStream = AsyncIterable<ProviderStreamChunk>;
+interface ProviderAdapter {
+  readonly id: string;
+  readonly kind: "provider-adapter";
+  readonly capabilities?: readonly ModelCapability[];
+  readonly execute?: (request: ProviderRunRequest) => Promise<ProviderRunResponse>;
+  readonly executeStream?: (request: ProviderRunRequest) => ProviderStream | Promise<ProviderStream>;
+  /**
+   * Phase 34 — D-01 — Per-adapter behavioral deviation flags. OPTIONAL on the
+   * base interface so v1.2 consumer adapters (4-field literals) continue to work
+   * without modification (non-breaking). First-party adapter factories narrow the
+   * return type to require `quirks` with the specific sub-interface for their adapter.
+   *
+   * D-03 discriminant-narrowing contract: consumers reading this field get
+   * `AdapterQuirks` autocomplete. To access adapter-specific flags, cast after
+   * an `adapter.id` discriminant check OR use the typed factory return directly.
+   * Example: `(adapter.quirks as AnthropicQuirks).promptCachingSupported`.
+   */
+  readonly quirks?: AdapterQuirks;
+  /**
+   * Phase 34 — D-02 — Capability negotiation via the provider's /models endpoint.
+   * OPTIONAL on the base interface (non-breaking for v1.2 consumer adapters).
+   * First-party adapters that have a /models endpoint implement this; adapters
+   * without one (LM Studio, openai-compat) fall back to the Phase 33 registry.
+   *
+   * The top-level `negotiateCapabilities(adapter, modelId)` helper in
+   * `capabilities/negotiate.ts` delegates to this method when present and
+   * synthesizes from the registry otherwise (D-04).
+   */
+  readonly negotiateCapabilities?: (modelId: string) => Promise<NegotiatedCapabilities>;
+}
+type ProviderRegistryInput = readonly (ProviderRef | ProviderAdapter | string)[];
+//#endregion
+export { XaiQuirks as $, ExecutionPlanStub as $t, SANITIZER_BY_FAILURE_MODE as A, defaultPiiDetectors as At, ModelCapabilityProfilePricingKey as B, ContextSummarizer as Bt, ProviderToolDefinition as C, ValidationIssue as Ct, NegotiationAuthError as D, evaluateTripwires as Dt, NegotiatedCapabilities as E, TripwireResult as Et, CapabilityAdapter as F, MustCiteInvariant as Ft, AdapterQuirks as G, toContextArtifactRefs as Gt, RecommendedPromptStrategy as H, buildContextPack as Ht, KnownFailureMode as I, NoPiiInvariant as It, LiteLLMQuirks as J, SessionStore as Jt, AnthropicQuirks as K, SessionRecord as Kt, ModelCapabilityProfile as L, inv as Lt, getRecommendedSanitizers as M, InvariantDeclaration as Mt, ALL_KNOWN_FAILURE_MODES as N, InvariantOptions as Nt, negotiateCapabilities as O, PiiDetector as Ot, ALL_TRAINING_CLASSES as P, MatchesInvariant as Pt, OpenRouterQuirks as Q, ExecutionPlan as Qt, ModelCapabilityProfileModality as R, BuildContextPackInput as Rt, ProviderToolChoice as S, ValidationError as St, Usage as T, TripwireEvidence as Tt, ToolCallSurface as U, estimateArtifactTokens as Ut, ReasoningSurface as V, TrustLabel as Vt, TrainingClass as W, estimateTokens as Wt, OpenAICompatQuirks as X, ContextPackItemPlan as Xt, LmStudioQuirks as Y, createMemorySessionStore as Yt, OpenAIQuirks as Z, ContextPackPlan as Zt, ProviderStreamOutputChunk as _, output as _n, NoContractMatchError as _t, ProviderFinishMetadata as a, RouteDecision as an, McpLikeClient as at, ProviderStreamUsageChunk as b, RunEventSink as bn, TimeoutError as bt, ProviderPricingHint as c, SelectedRoute as cn, ToolDefinition as ct, ProviderRunRequest as d, CitationRef as dn, importMcpTools as dt, FallbackRoute as en, ToolCallValidationError as et, ProviderRunResponse as f, CitationsOutputContract as fn, runTool as ft, ProviderStreamGatewayChunk as g, TextOutputContract as gn, LatticeRunError as gt, ProviderStreamCompleteChunk as h, SchemaOutputContract as hn, parseToolUseEnvelope as ht, ProviderDataPolicyHints as i, RouteCandidate as in, validateToolCallRequests as it, SanitizerKey as j, FieldFromTableInvariant as jt, synthesizeNegotiatedCapabilitiesFromRegistry as k, PiiDetectorResult as kt, ProviderRef as l, UsageRecord as ln, ToolExecutionContext as lt, ProviderStreamChunk as m, OutputContractMap as mn, ToolUseRequest as mt, ModelCapability as n, ProviderPackagingPlan as nn, ValidateToolCallsOption as nt, ProviderGatewayMetadata as o, RouteEstimates as on, McpToolDescriptor as ot, ProviderStream as p, OutputContract as pn, toolArtifactRef as pt, GeminiQuirks as q, SessionRef as qt, ProviderAdapter as r, ResultPlan as rn, ValidatedToolCall as rt, ProviderLatencyClass as s, RouteRejectReason as sn, ToolCallResult as st, CapabilityModality as t, ProviderAttemptRecord as tn, ToolCallValidationFailureReason as tt, ProviderRegistryInput as u, ArtifactRefsOutputContract as un, defineTool as ut, ProviderStreamTextDeltaChunk as v, RunEvent as vn, NoRouteError as vt, ProviderTransportMode as w, isTerminal as wt, ProviderStructuredOutputRequest as x, TracerLike as xn, TripwireViolationError as xt, ProviderStreamToolCallChunk as y, RunEventKind as yn, ProviderExecutionError as yt, ModelCapabilityProfilePricing as z, ContextPack as zt };
+//# sourceMappingURL=provider-C2IfKsvz.d.ts.map