audit-tools 0.34.41 → 0.35.0

package/dist/shared/providers/sharedProviderConfirmation.d.ts

@@ -1,802 +0,0 @@
-/**
- * DC-2 — shared, session-scoped provider confirmation (Gate-0).
- *
- * The design wants ONE provider confirmation spanning an audit→remediate run:
- * the first tool to run writes the operator's confirmed route DECISION to a
- * SHARED artifact at `<root>/.audit-tools/provider-confirmation.json` (NOT the
- * per-tool audit artifacts dir); the second tool reads and honors it. "Session" =
- * the shared `.audit-tools` dir for that repo+run, so no new identity scheme is
- * needed.
- *
- * **What this artifact carries is POLICY, not reach (G3).** The operator's
- * decision — exclusions, cost order, λ — is a set of *rules*, valid for any
- * auditor. What is *reachable* is per-auditor capability and is re-resolved from
- * live env/PATH at the moment of use, never inherited from whoever wrote this
- * file. So every read here is reach-free: it returns the persisted decision and
- * nothing else.
- *
- * INV-DC1-6 (never-block) is the only invariant left in tension, and it now
- * resolves to a plain two-valued read: a remediate run standalone with no prior
- * audit resolves its provider independently — absence or corruption of the
- * artifact is NOT an error, it is `null`.
- *
- * The former roster-staleness check (and its CE-012 three-valued `reconfirm`
- * state) is GONE. It compared the *writing* auditor's roster against the reader's
- * — meaningless cross-auditor by construction — and answered a real event (a
- * backend the operator never confirmed became reachable) by silently discarding
- * the operator's cost order and λ, while reaching no obligation at all. The
- * `autonomous_mode`-keyed reconciliation gate
- * ({@link computeNewlyReachableBackends}) replaces it: it compares the operator's
- * DECISION against *this* auditor's freshly-resolved reach, which is well-defined
- * across auditors, and it actually fires.
- *
- * CE-003 (lockless read races the writer rename): writes go through the shared
- * atomic writer (temp + atomic rename) under `withFileLock`, so a lockless
- * reader always observes either the complete old file or the complete new file —
- * never a torn intermediate.
- *
- * PB-1 (opencode opt-in): the confirmed pool is derived from `discoverProviders`,
- * which already withholds a bare-PATH opencode unless it is explicitly
- * configured, so the shared confirmation inherits that opt-in for free.
- */
-import type { DispatchableSource, ResolvedProviderName, SessionConfig } from "../types/sessionConfig.js";
-import type { RunLogger } from "../observability/runLog.js";
-import type { ConfirmedPoolEntry, PersistedPoolEntry, HostModelCostEntry, SourcePoolCostEntry, ProviderConfirmationInput } from "../types/providerConfirmation.js";
-/**
- * Schema version for the shared confirmation artifact. Bumped independently of
- * the per-tool seam contract (PROVIDER_CONFIRMATION_RESULT_VERSION) — this is
- * the cross-tool session artifact carrying the operator's route DECISION
- * (exclusions, cost order, λ), a distinct shape from the seam's pool snapshot.
- */
-export declare const SHARED_PROVIDER_CONFIRMATION_VERSION: "1.0.0";
-/**
- * Clamp an operator-supplied cost↔speed dispatch bias (λ) to [0, 1], or `undefined`
- * when it is absent/non-finite. Single-sourced so parse-time and read-time agree.
- * (spec/dispatch-quota.md).
- */
-export declare function clampDispatchBias(value: unknown): number | undefined;
-/** File name of the shared session-level confirmation under `.audit-tools/`. */
-export declare const SHARED_PROVIDER_CONFIRMATION_FILENAME = "provider-confirmation.json";
-/** `<root>/.audit-tools/provider-confirmation.json` (absolute). */
-export declare function sharedProviderConfirmationPath(root: string): string;
-/**
- * The operator's explicit route DECISION — reach-free by construction.
- *
- * This is the POLICY half of the Gate-0 confirmation: it names *rules* (which
- * provider names the operator ruled out, which self-spawn-blocked ones they ruled
- * back in), never *reachable endpoints*. It is deliberately the operator's raw
- * `exclude` / `include` input rather than the derived per-entry `excluded` flag,
- * because that flag folds in the WRITING auditor's `CLAUDECODE`/`CODEX` env via
- * `isSelfSpawnBlocked` — persisting it would make one auditor's environment
- * decide another's routing. Self-spawn-blocked is therefore recomputed in the
- * READING process (see {@link resolveDispatchExclusion}).
- *
- * Because policy is reach-independent, it stays valid when the discovered reach
- * changes. No read of this artifact gates on a reach check, for exactly that
- * reason: an exclusion must fail CLOSED (keep excluding) when reach shifts, never
- * fail open — and neither may the cost order or λ be discarded by a reach event
- * they do not depend on (G3 step 1).
- */
-export interface ConfirmedDispatchPolicy {
-    /**
-     * {@link DispatchExclusionPattern}s **the OPERATOR** ruled out of the dispatchable
-     * pool. Model-granular by default (`provider:model`) — the operator confirms
-     * *model* choices, so excluding one model of a multi-model backend must not drop
-     * the backend's other models.
-     *
-     * ⚠ Operator-authored ONLY. Tool-generated fail-closed patterns live in
-     * {@link auto_exclude} and must never be merged into this list: the two have
-     * different lifetimes, and once merged they are indistinguishable, so a
-     * carry-forward would launder a tool guess into permanent operator policy.
-     */
-    exclude?: DispatchExclusionPattern[];
-    /**
-     * Patterns **the GATE** authored on the operator's behalf — the fail-closed
-     * reconciliation excluding a newly-reachable backend that no operator decision
-     * covers (autonomous/headless path only).
-     *
-     * Kept separate from {@link exclude} because provenance decides lifetime. An
-     * operator exclusion is a durable rule and is carried forward across promotions; an
-     * auto-exclusion is a *placeholder for an answer that was never given*, so the next
-     * operator submission SUPERSEDES it. Merged into one list, the carry-forward cannot
-     * tell them apart and makes the tool's guess permanent — with no signal, because the
-     * backend is a confirmed key by then and the reconciliation delta never re-surfaces
-     * it. Honored at dispatch exactly like {@link exclude} (see
-     * {@link resolveDispatchExclusion}), so separating them weakens nothing.
-     */
-    auto_exclude?: DispatchExclusionPattern[];
-    /** Self-spawn-blocked provider names the operator explicitly opted back IN. */
-    include?: ResolvedProviderName[];
-    /**
-     * The operator's RAW capability answer — the `capability_order` key list exactly as
-     * submitted, most-capable-first.
-     *
-     * Stored verbatim rather than reconstructed from the resulting `capability_rank`s,
-     * which is the same reason `exclude` stores raw patterns. Reconstruction cannot
-     * distinguish a rank the operator authored from one that came from EXTERNAL evidence
-     * (a source's own registry rank), so it laundered external numbers into the
-     * operator's answer: a no-op promotion silently re-ranked confirmed models, and the
-     * laundered id then read as "evidenced" permanently — even after the external
-     * evidence disappeared, which is precisely the fail-open this obligation exists to
-     * close. Persisting the answer makes the distinction unrepresentable instead of
-     * merely documented.
-     */
-    capability_order?: string[];
-    /**
-     * R3-3: the model ids whose CURRENT position in {@link capability_order} was
-     * LLM-authored rather than operator-authored — always a subset of
-     * `capability_order`, never a superset. Tool-derived provenance, never itself
-     * submitted: an autonomous run has no operator to ask, so the CLI asks the host
-     * LLM instead (same submission machinery an operator would use), and the
-     * executor tags the result here rather than trusting either side to self-report
-     * authorship. An operator's later submission naming one of these ids repositions
-     * it freely (it is NOT an anchor on that submission) and removes it from this set
-     * — it is operator-authored from then on. See `advanceCapabilityOrderLlmRanked`
-     * and `capabilityOrderNonAnchors`.
-     */
-    capability_order_llm_ranked?: string[];
-}
-/**
- * The string form of an exclusion pattern. Axis-explicit: the rule names its
- * axis as a prefix, so the grammar is unambiguous against open namespaces and
- * an unknown axis is a PARSE ERROR, not an inert rule.
- *
- * | Pattern | Axis | Matches |
- * |---|---|---|
- * | `transport:codex` | transport | every model on that adapter |
- * | `transport:openai-compatible/glm-5.2` | transport | one model on that adapter (model after `/`) |
- * | `service:nim` | service | every model from that vendor, however reached |
- * | `service:nim/z-ai/glm-5.2` | service | one model from that vendor |
- * | `host:localhost:8000` | host | by endpoint address (port-specific) |
- * | `host:integrate.api.nvidia.com` | host | by endpoint address (port-agnostic) |
- *
- * There is deliberately **no `model:` axis** — a cross-service model rule
- * recombines the identities the gate exists to keep apart.
- *
- * ⚠ This is a THIRD keyspace, deliberately distinct from the quota-ledger pool
- * identity (`provider[#account]/model`, `quotaPoolKey`): an account is
- * irrelevant to a rule about a backend. Do not unify them.
- */
-export type DispatchExclusionPattern = string;
-/** A backend an exclusion rule can be evaluated against — structurally a `DispatchableSource`. */
-export interface ExcludableBackend {
-    transport: string;
-    service?: string;
-    model?: string;
-    endpoint?: string;
-}
-/**
- * The resolved exclusion rule set for THIS process: the operator's persisted
- * patterns plus every locally self-spawn-blocked provider. Applied as a
- * set-difference FILTER over freshly-gathered reach, never additively.
- */
-export interface DispatchExclusion {
-    /** True ⇒ this backend is ruled out and must not become a dispatch pool. */
-    excludes(backend: ExcludableBackend): boolean;
-    /**
-     * The first pattern that rules this backend out, or null when none does.
-     *
-     * Attribution for the capacity guard: when the rule set removes EVERY gathered
-     * source, "zero capacity" alone sends the operator hunting through their whole
-     * policy — the guard has to be able to name the rules that did it. `excludes` is
-     * derived from this (`excludedBy(b) !== null`), so the boolean verdict and the
-     * attributed pattern can never disagree.
-     */
-    excludedBy(backend: ExcludableBackend): DispatchExclusionPattern | null;
-}
-export interface SharedProviderConfirmation {
-    /** Must equal SHARED_PROVIDER_CONFIRMATION_VERSION. */
-    schema_version: typeof SHARED_PROVIDER_CONFIRMATION_VERSION;
-    /**
-     * The operator's explicit, reach-free route decision. Read at dispatch by
-     * {@link resolveDispatchExclusion} and applied as a set-difference filter over
-     * freshly-discovered reach — never additively. Absent ⇒ no operator exclusions
-     * (self-spawn-blocked providers are still excluded, recomputed locally).
-     */
-    policy?: ConfirmedDispatchPolicy;
-    /** Always true: the pool applies to the whole audit→remediate session. */
-    session_level: true;
-    /** ISO-8601 timestamp of when the pool was confirmed. */
-    confirmed_at: string;
-    /**
-     * The confirmed provider pool as PERSISTED — decision only, no reach (G3 B+D).
-     * See {@link PersistedPoolEntry}: the reach half is deliberately unrepresentable
-     * here, so one auditor's environment can never route another's.
-     */
-    provider_pool: PersistedPoolEntry[];
-    /**
-     * Host self-reported model tiers with their operator-confirmed cost positions
-     * (follow-up c). Merged into the model-keyed dispatch positions map by
-     * `readConfirmedCostPositions` so host-native tiers route by their confirmed
-     * order. Absent/empty on the headless path (no host roster is reported).
-     */
-    host_model_cost_order?: HostModelCostEntry[];
-    /**
-     * Dispatchable SOURCE pools (explicit `sources[]` + proxy expansion) with their
-     * operator-confirmed cost positions (Gate-0 source fold). Merged into the model-keyed
-     * dispatch positions map by `readConfirmedCostPositions` so a source pool routes by its
-     * confirmed order exactly like a provider pool / host tier. Absent when no source is
-     * configured (or a confirmation written before this field existed) ⇒ dispatch falls to
-     * declared/catalog price then tier, exactly as before.
-     */
-    source_pool_cost_order?: SourcePoolCostEntry[];
-    /**
-     * Operator-confirmed cost↔speed dispatch bias (λ) ∈ [0, 1], the durable operating
-     * point on the cost-vs-throughput frontier (spec/dispatch-quota.md). Read
-     * back at dispatch by `readConfirmedDispatchBias` and applied by `admitBatch`. Absent
-     * ⇒ the cost-first default (λ=0), so a confirmation written before this field existed
-     * (or a headless run) behaves exactly as before.
-     */
-    dispatch_bias?: number;
-}
-/**
- * The Gate-0 confirmation as RENDERED to the operator — identical to the persisted
- * {@link SharedProviderConfirmation} except that `provider_pool` carries the FULL
- * {@link ConfirmedPoolEntry} (this auditor's freshly-derived reach: tier, price, why
- * a backend is excluded). This shape exists ONLY in memory; it never reaches disk.
- */
-export interface RenderedProviderConfirmation extends Omit<SharedProviderConfirmation, "provider_pool"> {
-    provider_pool: ConfirmedPoolEntry[];
-}
-/**
- * Project the render DTO down to what actually gets PERSISTED: the operator's
- * decision, with this auditor's reach assessment dropped (G3 B+D).
- *
- * The PRODUCER is split — not the write site. `writeSharedProviderConfirmation`
- * receives an already-typed value, so projecting THERE would leave the reach fields
- * representable on the persisted type and a future caller could put them back.
- * Projecting here makes the persisted shape carry no reach BY CONSTRUCTION.
- */
-export declare function buildSharedProviderConfirmation(...args: Parameters<typeof buildProviderConfirmationRender>): SharedProviderConfirmation;
-/**
- * Build a fresh shared confirmation from auto-discovery. Guarantees the
- * always-available `worker-command` fallback is present in the pool (it blocks
- * auto-dispatch and so is never PATH-detected, but the pool must always be able
- * to fall back to it) and stamps the schema version, session-level flag, and
- * confirmation timestamp.
- *
- * SECURITY (self-spawn exclusion): a provider that `discoverProviders` flags as
- * `selfSpawnBlocked` (claude-code under `CLAUDECODE`, codex under `CODEX`) is set
- * `excluded: true` AND carries the machine-readable `self_spawn_blocked` flag, so
- * it is OUT of the dispatchable pool by default — launching it would self-spawn a
- * fresh agent from inside an active session of the same agent. The operator can
- * deliberately re-include it by naming it in `include`; that overrides the
- * exclusion (the host still always retains the worker-command fallback).
- *
- * @param sessionConfig - Current session config; may be an empty `{}`.
- * @param env           - Process env snapshot; defaults to `process.env`.
- * @param exclude       - {@link DispatchExclusionPattern}s to pre-exclude (from a
- *   prior gate). A `provider:model` pattern marks a pool entry excluded only when
- *   that entry's `representativeModelId` IS that model — the same key the routing
- *   filter matches on, so display and dispatch cannot disagree.
- * @param include       - Provider names the operator explicitly opts back IN,
- *   overriding the default self-spawn-blocked exclusion for those names.
- * @param detectCommand - Injectable PATH-detection hook, forwarded to
- *   `discoverProviders` so tests can drive discovery deterministically.
- * @param input         - Operator's Gate-0 submission (interactive path): its
- *   `cost_order` overrides the suggested ordering and its `host_models` become
- *   priced, orderable host-native tiers (`host_model_cost_order`). Omit for the
- *   headless / no-operator path — the tool then emits its price-ascending
- *   suggestion with no host models, exactly as before. `exclude`/`include` are
- *   passed via the dedicated params above (the executor forwards them from the
- *   same input), so this arg governs ordering + host roster only.
- */
-export declare function buildProviderConfirmationRender(sessionConfig?: SessionConfig, env?: NodeJS.ProcessEnv, exclude?: DispatchExclusionPattern[], include?: ResolvedProviderName[], detectCommand?: (command: string) => boolean, input?: ProviderConfirmationInput, sources?: DispatchableSource[], 
-/**
- * Gate-authored fail-closed patterns, kept SEPARATE from the operator's `exclude`
- * so provenance survives to disk (see {@link ConfirmedDispatchPolicy.auto_exclude}).
- * Both kinds mark a pool entry excluded in the render — the split governs lifetime,
- * not enforcement — so the two are unioned for the display/routing decision below
- * and only split again when the policy is persisted.
- */
-autoExclude?: DispatchExclusionPattern[], 
-/**
- * R3-3: the FINAL `capability_order_llm_ranked` set for this promotion (already
- * advanced across rule 1/2 by the caller — {@link advanceCapabilityOrderLlmRanked}).
- * Persisted verbatim into the policy; empty for the display-only "suggested"
- * render nextStepCommand builds (that call never persists, so provenance is moot).
- */
-capabilityOrderLlmRanked?: readonly string[]): RenderedProviderConfirmation;
-/**
- * The keys of the operator's persisted DECISION — the CONFIRMED half of the gate.
- *
- * All three pools contribute, and each is load-bearing: `annotateConfirmedPool`
- * folds a source away when its model is already claimed by a provider entry, so a
- * source can be represented ONLY by `provider_pool[].model_id`; and a host tier
- * appears only in `host_model_cost_order`. Reading fewer than all three would
- * manufacture a phantom delta for an already-confirmed backend.
- *
- * A host tier with no `provider` contributes NOTHING, and that is the deliberate
- * fail-SAFE degradation for a confirmation written before the field existed. The
- * alternative — falling back to the bare `model_id` — is precisely the bypass this
- * identity exists to close: a confirmed *host* model would silently approve an
- * identically-named model on some other provider. Contributing no key can only ever
- * cause the gate to ASK about a backend again (loud, and the operator's answer then
- * records the provider); it can never approve one unseen.
- */
-export declare function confirmedBackendKeys(confirmation: SharedProviderConfirmation): Set<string>;
-/** One backend in the gate's delta: reachable now, absent from the decision. */
-export interface NewlyReachableBackend {
-    /**
-     * The gate key — {@link backendIdentity}. Stable, operator-facing, and
-     * provider-qualified.
-     */
-    key: string;
-    /** The backend's provider name. Display only — the prompt names it beside `key`. */
-    provider: ResolvedProviderName;
-    /**
-     * The backend's serving vendor / service name (`service ?? transport`).
-     */
-    service?: string;
-    /**
-     * The transport-qualified {@link DispatchExclusionPattern} that rules out
-     * **exactly this transport route**, built HERE beside the key it was compared on.
-     */
-    exclusion_pattern: DispatchExclusionPattern;
-    /**
-     * The service-qualified {@link DispatchExclusionPattern} (`service:vendor/model` or `service:vendor`)
-     * that rules out **every transport reaching this vendor/service**. Emitted by autonomous fail-closed
-     * writes so unconfirmed backends stay excluded across transport/proxy changes.
-     */
-    service_exclusion_pattern?: DispatchExclusionPattern;
-}
-/**
- * DELTA = **REACH-NOW \ CONFIRMED**: the backends this auditor can reach *right
- * now* that the operator's persisted decision never mentions. Sorted by key, so the
- * result is stable for prompt rendering + comparison.
- *
- * This is a **set difference — a FILTER over fresh reach, never additive.** The
- * opposite direction (CONFIRMED \ REACH-NOW: a backend the operator confirmed that
- * this auditor cannot reach) is the harmless *subset* case and is deliberately
- * silent — it is also why the synthetic `worker-command` entry and
- * `host_model_cost_order` need no special-casing here.
- *
- * @param confirmation - The persisted decision (CONFIRMED).
- * @param sessionConfig - The EFFECTIVE config, so `representativeModelId` derives
- *   keys identically to the write side.
- * @param sources - REACH-NOW's source half. MUST come from the
- *   `gatherDispatchableSources` chokepoint — the single async source-gather point
- *   both `buildSourcePools` and the Gate-0 surface consume, so what the operator
- *   confirms is exactly what routes. Re-deriving it from `resolveAmbientSources`
- *   would reintroduce the display/dispatch drift that invariant forbids, and is
- *   structurally blind to descriptor-supplied sources, the demoted primary, and the
- *   legacy `openai_compatible` fold.
- * @param env - Process env, for `discoverProviders` (REACH-NOW's provider half).
- * @param detectCommand - Injectable PATH-detection hook so tests drive discovery
- *   deterministically instead of shelling out.
- */
-export declare function computeNewlyReachableBackends(confirmation: SharedProviderConfirmation, sessionConfig: SessionConfig, sources?: readonly DispatchableSource[], env?: NodeJS.ProcessEnv, detectCommand?: (command: string) => boolean): NewlyReachableBackend[];
-/**
- * The dispatchable-pool exclusion rules for THIS process: the operator's explicit
- * {@link DispatchExclusionPattern}s, plus every provider that is self-spawn-blocked
- * *in this process's env* and was not explicitly opted back in.
- *
- * Reach is recomputed here rather than read from the artifact's derived `excluded`
- * flag — that flag encodes the WRITING auditor's env, and an auditor for whom a
- * provider is perfectly spawnable must not inherit another's block. The operator's
- * decision is inherited (it is a rule); the reach assessment is not.
- *
- * ⚠ **These rules are only safe to apply to SOURCE pools.** Inside any agent session
- * the self-spawn half ALWAYS names that agent (`CLAUDECODE` ⇒ `claude-code`, `CODEX`
- * ⇒ `codex`) — i.e. the conversation host itself. Applying them to HOST pools would
- * zero out dispatch entirely: the driver would exclude itself. It is harmless at
- * `buildSourcePools` only because a host can never BE a source — `claude-code` is
- * structurally absent from `DISPATCHABLE_TRANSPORTS`, so in a Claude Code
- * session the filter is a no-op. Honoring an operator exclusion of the host/primary
- * provider therefore is NOT a matter of passing these rules to the host-pool builder;
- * it needs a separate decision about what excluding your own driver should even mean.
- */
-export declare function resolveDispatchExclusion(policy: ConfirmedDispatchPolicy | null | undefined, env?: NodeJS.ProcessEnv): DispatchExclusion;
-/**
- * The operator-authored patterns that no rule grammar can account for — see
- * {@link isGrammaticalExclusionPattern}. Empty ⇒ every pattern is writable.
- *
- * Order is the operator's own submission order (deduplicated, first occurrence
- * kept), so the refusal names their patterns back in the order they wrote them.
- */
-export declare function ungrammaticalExclusionPatterns(patterns: readonly DispatchExclusionPattern[]): DispatchExclusionPattern[];
-/**
- * The patterns that matched NOTHING in `backends` — the ADVISORY half, and
- * deliberately not an error.
- *
- * A zero-match rule is legitimate: `auto_exclude` entries go zero-match the moment
- * their backend stops being reachable, and an operator may pre-declare an exclusion
- * for a backend they have not configured yet. It is also the only signal available
- * for the grammatically-valid typo `isGrammaticalExclusionPattern` cannot catch
- * (`openai-compatible:model-typo` — real provider head, open model segment). So it
- * is REPORTED at the confirmation summary and never refused anywhere.
- *
- * Patterns are migrated before matching, so an already-saved bare form is evaluated
- * exactly as it will actually apply at dispatch — not as the string it was typed as.
- *
- * **Empty `backends` ⇒ empty result.** With nothing gathered there is no evidence
- * that any rule failed to match, only that there was nothing to match against, and
- * reporting every rule there would be noise the operator learns to read past.
- *
- * Order is the operator's own submission order (deduplicated, first occurrence kept).
- */
-export declare function unmatchedExclusionPatterns(patterns: readonly DispatchExclusionPattern[], backends: readonly ExcludableBackend[]): DispatchExclusionPattern[];
-/**
- * Read the operator's confirmed route policy from the shared Gate-0 confirmation.
- *
- * Deliberately reads the artifact DIRECTLY rather than going through
- * {@link readSharedProviderConfirmation}, so that **a corrupt sibling field cannot
- * discard the decision**: `parseSharedProviderConfirmation` returns `null` wholesale
- * on any malformed required field or a `schema_version` mismatch. Routing policy
- * through it would make an unrelated corruption (or a future version bump) silently
- * lift the operator's exclusions — failing OPEN on the one field that must fail
- * closed. Parsing `policy` on its own keeps that blast radius out.
- *
- * (Before G3 this bypass carried a second rationale — dodging the roster-freshness
- * gate. That gate is gone: no read of this artifact is reach-gated any more, so the
- * remaining reason is blast radius alone.)
- *
- * **Honest limit — this is not absolutely fail-closed.** An absent or unparseable
- * artifact yields `null` (no operator policy). That residue is irreducible here: with
- * no readable decision on disk there is nothing to fail closed ON. Self-spawn-blocked
- * providers are still excluded locally by {@link resolveDispatchExclusion}, which
- * needs no artifact.
- */
-export declare function readConfirmedDispatchPolicy(root: string | undefined): Promise<ConfirmedDispatchPolicy | null>;
-/**
- * Atomically write the shared confirmation to
- * `<root>/.audit-tools/provider-confirmation.json`. The durable write goes
- * through the shared atomic writer (temp + atomic rename) and the whole
- * operation is guarded by `withFileLock` so a concurrent writer can never
- * interleave — and a lockless reader (see `readSharedProviderConfirmation`)
- * never observes a torn file (CE-003).
- */
-export declare function writeSharedProviderConfirmation(root: string, confirmation: SharedProviderConfirmation, logger?: RunLogger): Promise<void>;
-/**
- * Read + parse the shared confirmation for `root`. TWO-valued:
- *
- *   - returns `null` when the artifact is ABSENT or MALFORMED — the caller then
- *     resolves its provider independently, exactly as today (INV-DC1-6
- *     never-block). Absence is the standalone-remediate case and is not an error.
- *   - returns the parsed confirmation otherwise — the operator's persisted route
- *     DECISION, honored as-is.
- *
- * **Reach-free by construction (G3).** This read does NOT check whether the
- * reachable backend set still matches whatever the writing auditor saw. It cannot
- * meaningfully: a *different* auditor legitimately has different reach, so that
- * comparison was noise cross-auditor — and answering it by discarding the
- * operator's decision fails OPEN on a policy question. A backend becoming newly
- * reachable is a real event, handled by the reconciliation gate
- * ({@link computeNewlyReachableBackends}), which compares the DECISION against
- * *this* auditor's reach and is keyed on `autonomous_mode`.
- *
- * Never throws: a read/parse failure is treated as absent/malformed → `null`.
- * The read is lockless (no lock needed: the writer's atomic rename guarantees a
- * complete file either way — CE-003) and so cannot deadlock against a writer.
- */
-export declare function readSharedProviderConfirmation(root: string): Promise<SharedProviderConfirmation | null>;
-/**
- * Read the operator-confirmed cost ordering (rung 1 of costRank; see
- * spec/dispatch-quota.md) from the shared Gate-0 confirmation as a model-keyed
- * `Map<model_id, cost_order>` for the dispatch build sites. Single-sourced so audit
- * and remediate honor it identically. Best-effort and never throws: an absent
- * `root` or a missing/malformed confirmation yields an empty map — dispatch then
- * falls to real price then tier.
- *
- * **Not gated on reach (G3 step 1).** The cost order is the operator's POLICY —
- * "the operator may reorder" — so a shift in what happens to be reachable must not
- * silently discard it. The former roster-freshness gate did exactly that, on the
- * false premise that these positions are reach-derived; they are not, and it was
- * the live defect this fixes.
- */
-export declare function readConfirmedCostPositions(root: string | undefined): Promise<Map<string, number>>;
-export declare function readConfirmedCapabilityRanks(root: string | undefined): Promise<Map<string, number>>;
-/**
- * The capability-evidence delta: dispatchable models with NO resolvable capability
- * rank. Computed once per invocation (it reads the confirmation + gathers sources)
- * and threaded by reference on the gate, exactly like the reach delta.
- *
- * "Evidenced" is deliberately defined as **the dispatch join resolves** — the same
- * lookup the pool constructors take ({@link readConfirmedCapabilityRanks} keyed on the
- * pool's model), never a parallel predicate. Two consequences, both load-bearing:
- *   - a pool with NO model is skipped entirely. It is unjoinable, so pinning it could
- *     never clear the delta and it would re-prompt forever.
- *   - external evidence (`source.capability_rank`) counts, so a fully-ranked roster
- *     never fires the gate at all.
- *
- * Returns [] when no confirmation exists yet — the first-time `missing` case already
- * pauses for the operator, and reporting a delta against a pool they have never seen
- * would fold a second question into a prompt that has not asked the first one yet.
- *
- * Lives HERE, beside {@link readConfirmedCapabilityRanks}, rather than in the audit CLI
- * command it is called from: its failure mode is a LIVELOCK (wrongly admitting an
- * unrankable pool re-prompts `provider_confirmation` forever), and a delta computation
- * with that failure mode must be reachable by a test.
- */
-export declare function resolveUnevidencedCapabilityPools(root: string, effectiveConfig: SessionConfig): Promise<string[]>;
-/**
- * Read the operator-confirmed cost↔speed dispatch bias (λ ∈ [0,1]) from the shared
- * Gate-0 confirmation for the dispatch build sites (spec/dispatch-quota.md).
- * Single-sourced so audit and remediate apply the identical operating point.
- * Best-effort and never throws: an absent `root`, a missing/malformed confirmation,
- * or an absent field all yield the cost-first default `0`.
- *
- * **Not gated on reach (G3 step 1)** — λ is the operator's durable operating point
- * on the cost-vs-throughput frontier, i.e. POLICY. See
- * {@link readConfirmedCostPositions}.
- */
-export declare function readConfirmedDispatchBias(root: string | undefined): Promise<number>;
-/** File name of the host-written Gate-0 input under the audit artifacts dir. */
-export declare const PROVIDER_CONFIRMATION_INPUT_FILENAME = "provider-confirmation.input.json";
-/**
- * Validate a parsed value as a ProviderConfirmationInput. Degrade-safe: returns
- * `null` for absent/malformed so a missing or corrupt input is never an error
- * (the executor then falls back to the tool's suggested ordering). Only the
- * version is required; every other field is optional and validated to its
- * expected shape (a malformed field is dropped, not fatal).
- *
- * ⚠ **One deliberate exception: an ungrammatical `exclude` rule THROWS.** Every
- * other field degrades because dropping it costs the operator only that field's
- * effect; dropping an exclusion costs them a backend they ruled out, dispatchable
- * and silent. See the `exclude` branch below for the full argument.
- */
-export declare function parseProviderConfirmationInput(value: unknown): ProviderConfirmationInput | null;
-/**
- * Seed an incoming Gate-0 submission from the PRIOR confirmation, field by field.
- *
- * **The defect class this closes.** `buildProviderConfirmationRender` rebuilds the
- * whole confirmation from the submission ALONE — every operator decision it persists
- * (`cost_order`, `capability_rank`, the host roster, λ, and the `policy` exclusions) is
- * reconstructed from `input` and from nothing else. So *any* field a submission omits
- * is not "left alone", it is DESTROYED. That is one defect with six faces, and fixing
- * it per-field is what let three of them survive a review round: the prompt's capability
- * example is `{ "capability_order": [...] }`, so an operator answering exactly what was
- * asked omits all five other fields and silently wipes them.
- *
- * Two rules, both load-bearing:
- *
- * 1. **`undefined` means "said nothing"; an explicit empty array means "delete".** A
- *    submission that never mentions host models is not a decision to remove them; an
- *    explicit `"host_models": []` is. `parseProviderConfirmationInput` therefore
- *    PRESERVES an empty array rather than dropping it to absent — without that the two
- *    cases are indistinguishable here and the carry-forward resurrects a roster the
- *    operator deleted.
- * 2. **It applies with `input === null` too.** The autonomous/headless path promotes
- *    with no submission at all, and the capability delta is a brand-new trigger for
- *    that path — so short-circuiting on `input &&` would let an unattended re-promotion
- *    wipe the operator's entire persisted decision and then report convergence.
- *
- * Returns `null` only when there is nothing on either side. A prior confirmation with
- * no incoming submission still yields a synthesized input carrying it forward.
- */
-/**
- * The gate-authored exclusions that SURVIVE this promotion.
- *
- * Round-3 defect (high, fail-OPEN): `auto_exclude` was rebuilt on every promotion from
- * `gate.newlyReachable` alone. But `confirmedBackendKeys` counts an excluded entry as
- * CONFIRMED, so once the gate fail-closed-excludes backend X and folds it into the pool,
- * the reach delta is empty forever — and the very next promotion rebuilt `auto_exclude`
- * from that empty delta and dropped X, making a backend the operator never confirmed
- * dispatchable. The docstring's "a submission supersedes it" was true; the code
- * superseded it on EVERY promotion, including the no-submission one.
- *
- * The rule is therefore narrower than "any submission clears it". A submission
- * supersedes an auto-exclusion only when it actually ADDRESSES that backend:
- *   - the operator re-stated the pattern in `exclude` — it is now operator-authored and
- *     lives there, so retaining an `auto_exclude` copy would double-record it; or
- *   - the operator named that provider in `include` — an explicit opt-back-IN.
- * Anything else is SILENCE, and silence is not confirmation ("the operator confirms
- * model choices"). A capability-only answer must not lift an exclusion the operator was
- * never even shown — the reach section does not render once the backend is a confirmed
- * key, so they cannot see what they would be lifting.
- *
- * Fail-CLOSED by construction: the uncertain case retains the exclusion.
- */
-export declare function retainAutoExclusions(priorAuto: readonly DispatchExclusionPattern[], input: ProviderConfirmationInput | null): DispatchExclusionPattern[];
-export declare function carryForwardConfirmationInput(input: ProviderConfirmationInput | null, prior: SharedProviderConfirmation | null | undefined, 
-/**
- * R3-3: true when THIS submission is LLM-authored (tool-derived — see
- * `runProviderConfirmationAutoComplete`'s `authoredByLlm`). Governs which
- * previously-ranked ids the capability merge below treats as fixed anchors:
- * an LLM submission anchors every previously-ranked id (operator's and prior
- * LLM's alike — rule 1); an operator submission does NOT anchor ids already in
- * `capability_order_llm_ranked` (rule 2 — they interpolate like new models).
- * Also gates the total-replacement escape in `mergeCapabilityOrder` (operator
- * only — see its docstring). Defaults `false` (today's operator behavior) so
- * every pre-existing call site is unaffected.
- */
-authoredByLlm?: boolean): ProviderConfirmationInput | null;
-/** How many already-ranked models the capability prompt shows as fixed reference points. */
-export declare const DEFAULT_CAPABILITY_ANCHOR_COUNT = 5;
-/**
- * Pick a BOUNDED, spread sample of an already-confirmed capability ordering to show
- * beside the unevidenced models as fixed reference points.
- *
- * The roster may be HUNDREDS of models, so the prompt must be O(new + constant) — it
- * can never render the whole ordering. First, last, and evenly-spaced interior picks
- * give the operator a usable coordinate space (top / middle / bottom of the confirmed
- * ranking) at constant cost, which is exactly what {@link mergeCapabilityOrder}
- * interpolates against.
- *
- * @param priorOrder - The confirmed ordering, most-capable-first.
- * @param exclude    - Models already being asked about (the unevidenced delta); an
- *   anchor must be a model whose rank is settled, never one under question.
- * @param max        - Ceiling on the sample size.
- */
-export declare function selectCapabilityAnchors(priorOrder: readonly string[], exclude?: readonly string[], max?: number): string[];
-/**
- * R3-3 — the submission's ANCHOR EXCLUSION set, single-sourced so
- * {@link mergeCapabilityOrder} and {@link detectDiscardedCapabilityReorder} can never
- * disagree about what counts as a fixed reference point for a given submission:
- *
- * - LLM-authored (`authoredByLlm`): every previously-ranked id — the operator's and
- *   any prior LLM's alike — stays a fixed anchor (rule 1). Nothing is excluded.
- * - Operator-authored: ids already in `capability_order_llm_ranked` are NOT anchors
- *   (rule 2) — the operator may reposition them exactly like new models, and doing
- *   so removes them from that set (see {@link advanceCapabilityOrderLlmRanked}).
- */
-export declare function capabilityOrderNonAnchors(priorLlmRanked: readonly string[], authoredByLlm: boolean): Set<string>;
-/**
- * Advance the R3-3 `capability_order_llm_ranked` authorship SET across one
- * promotion. Always a subset of the resulting `capability_order` — see
- * {@link ConfirmedDispatchPolicy.capability_order_llm_ranked}.
- *
- * - LLM-authored submission: every id this submission newly ranked — i.e. not
- *   already in `priorOrder` — is ADDED. `mergeCapabilityOrder` never lets an
- *   LLM-authored submission move a previously-ranked id (its total-replacement
- *   escape is operator-only), so a prior id is never repositioned on this path and
- *   this function does not need to special-case "total" either: it is simply
- *   `answer \ priorOrder`.
- * - Operator-authored submission: every id the submission NAMES is REMOVED — naming
- *   a previously LLM-ranked id (and, via {@link capabilityOrderNonAnchors}'s
- *   non-anchor treatment, freely repositioning it) makes it operator-authored from
- *   here on, exactly like a first-time rank.
- * - No submission at all (`submitted` absent/empty): the running set is unchanged.
- */
-export declare function advanceCapabilityOrderLlmRanked(priorLlmRanked: readonly string[], priorOrder: readonly string[], submitted: readonly string[] | undefined, authoredByLlm: boolean): string[];
-/**
- * The anchor ids whose relative order the submission changed but the merge will NOT
- * honor — i.e. an operator reorder that is about to be silently discarded.
- *
- * {@link mergeCapabilityOrder} treats every submitted id already present in
- * `priorOrder` as a FIXED reference point, so a submission that swaps two of them
- * returns the prior order unchanged. Without this, that is invisible: the promotion
- * succeeds, the artifact is byte-identical, and nothing anywhere says the operator's
- * decision was dropped. `unrankedOnPromotion` cannot catch it either — a reordered id
- * IS present in `capability_order`, so it reports nothing.
- *
- * An accepted-then-discarded operator decision is the same defect class as laundering a
- * tool guess into operator policy: not corruption, but SILENCE. The standing rule is
- * that the operator must never have to notice — so the caller reports this loudly.
- *
- * Returns `[]` when the reorder will actually be honored: an OPERATOR-authored TOTAL
- * submission (every prior id restated) is applied verbatim, and a submission with
- * fewer than two anchors cannot express a reorder at all.
- *
- * NOTE this reports the LIMITATION, it does not lift it. Making a repositioning
- * expressible without restating the whole roster needs the anchor-provenance split
- * tracked in `docs/backlog.md`; this only ensures the drop is never silent.
- */
-export declare function detectDiscardedCapabilityReorder(priorOrder: readonly string[], submitted: readonly string[], 
-/**
- * R3-3: ids to exclude from anchor treatment — must be the SAME set passed to
- * {@link mergeCapabilityOrder} for this submission ({@link capabilityOrderNonAnchors}),
- * or the two disagree about what an "anchor" is and this reports a discard the
- * merge actually honored (or misses one it silently dropped).
- */
-nonAnchorIds?: ReadonlySet<string>, 
-/**
- * R3-3: mirrors the authorship-gated condition in {@link mergeCapabilityOrder} — the
- * total-submission escape is OPERATOR-only, so an LLM-authored submission that
- * happens to restate every prior id (a small roster's anchor sample can cover the
- * whole ordering) still has its anchor reorder detected and reported, never
- * silently honored via the escape.
- */
-authoredByLlm?: boolean): string[];
-/**
- * Merge an operator's capability answer into the previously confirmed ordering by
- * **ANCHORED INSERTION**.
- *
- * **The livelock this closes.** The capability prompt is DELTA-SCOPED — it renders only
- * the models with no evidence — while `annotateConfirmedPool` built its positions from
- * the submission ALONE, i.e. total replacement. So each answer erased the last: rank A,
- * the delta asks C, rank C, A loses its rank, the delta asks A, forever. `PRIORITY[0]`
- * never converges. Reproduced across three promotions.
- *
- * The fix cannot be "render the whole ordering" (the roster may be hundreds of models —
- * the prompt must stay O(new + constant)) and it cannot be an absolute score or tier
- * (only a RELATIVE ordering is representable, by standing decision). Anchored insertion
- * is what remains: show a bounded, spread sample of the confirmed ordering
- * ({@link selectCapabilityAnchors}) as fixed reference points, and interpolate the new
- * models into the coordinate space those points define.
- *
- * Semantics, exactly:
- *
- * - **Anchors** = submitted entries that already appear in `priorOrder`. They are
- *   REFERENCE POINTS: their prior positions define the coordinate space, and **a
- *   reordering of anchors relative to each other is deliberately NOT honored** on a
- *   partial submission. The operator saw at most a handful of them out of a possibly
- *   enormous ordering, so a swap between two anchors carries no information about the
- *   models BETWEEN them — honoring it would silently reshuffle models the operator
- *   never saw.
- * - **Exception — an OPERATOR-authored TOTAL submission is a total replacement.**
- *   When the submission mentions every model in `priorOrder` there are no unmentioned
- *   models, so the coordinate space is fully respecified and the answer is honored
- *   verbatim. This is the only case where "reorder what you already confirmed" is a
- *   well-defined request, and it is the pre-existing behavior for a complete
- *   re-ranking. **R3-3: this escape is OPERATOR-only** (`authoredByLlm: false`,
- *   the default) — on a SMALL roster the bounded anchor sample
- *   ({@link selectCapabilityAnchors}) can cover the entire prior ordering, so an
- *   LLM's answer over "new models + all the anchors it was shown" becomes total BY
- *   ACCIDENT, not by the LLM's intent to reorder. Honoring it verbatim would let an
- *   LLM silently reorder ranks an operator (or a prior LLM) set; an LLM-authored
- *   submission therefore NEVER takes this exception — every previously-ranked id
- *   stays a fixed anchor regardless of coverage, and an attempted reorder is
- *   discarded and reported exactly like a partial submission's would be (see
- *   {@link detectDiscardedCapabilityReorder}).
- * - **New models** (not in `priorOrder`) interpolate to a fractional position between
- *   the prior positions of the nearest preceding and following anchors IN THE SUBMITTED
- *   LIST. Before the first anchor ⇒ just below it (more capable); after the last ⇒ just
- *   above it. Consecutive new models keep their submitted relative order.
- * - **Every model in `priorOrder` the submission does not mention keeps its prior
- *   position.** THIS IS THE LIVELOCK FIX.
- * - **No anchors at all** (a partial submission naming only unknown models): there is no
- *   coordinate to interpolate against, so the new models are appended AFTER the whole
- *   prior ordering — the conservative direction, since a higher rank is less capable and
- *   therefore trusted with less.
- * - **Duplicates**: first occurrence wins, matching `annotateConfirmedPool`'s rule that a
- *   positional list is the operator's ordering and a later repeat must not re-rank it.
- * - **Result** is every model sorted by resolved position, ties broken by model id.
- *   Deterministic by construction: an incidentally-ordered array here would churn the
- *   confirmation's content hash on every promotion and cascade phantom staleness.
- *
- * Degenerate cases: an empty `priorOrder` (the first-ever answer) returns the submission;
- * an empty submission returns the prior ordering unchanged (an omitted answer is
- * "said nothing" — there is no way to express "delete the whole ranking", and the
- * un-delete direction is the one that cannot livelock).
- *
- * Pure — no I/O, no clock, no config. Exported so the merge that decides whether the
- * gate converges is directly testable.
- */
-export declare function mergeCapabilityOrder(priorOrder: readonly string[], submitted: readonly string[], 
-/**
- * R3-3: ids to treat as NOT anchored even though they already appear in
- * `priorOrder` — the operator-authored path passes the current
- * `capability_order_llm_ranked` set here ({@link capabilityOrderNonAnchors}) so an
- * operator may freely reposition a previously LLM-ranked id, exactly like a new
- * model. Empty by default (today's behavior: every previously-ranked id anchors).
- */
-nonAnchorIds?: ReadonlySet<string>, 
-/**
- * R3-3: true when THIS submission is LLM-authored. Gates the total-replacement
- * escape below (OPERATOR-only — see the docstring's exception): an LLM-authored
- * submission never takes it, so a previously-ranked id is NEVER repositioned on
- * this path, regardless of how much of `priorOrder` the submission happens to
- * cover.
- */
-authoredByLlm?: boolean): string[];
-/**
- * Read the operator's Gate-0 input from `<artifactsDir>/provider-confirmation.input.json`.
- * Returns `null` when the file is absent, unreadable, or malformed — the "operator
- * has not acted yet" signal the gate uses to decide emit-vs-consume.
- *
- * ⚠ Throws on exactly one condition, inherited from
- * {@link parseProviderConfirmationInput}: an ungrammatical `exclude` rule. That is a
- * REFUSAL, not a degrade — swallowing it here would turn a typo'd exclusion into
- * "operator has not acted yet" and re-emit the same prompt forever, which is the
- * silent failure the check exists to prevent. Every other malformed input still
- * yields `null`.
- */
-export declare function readProviderConfirmationInput(artifactsDir: string): Promise<ProviderConfirmationInput | null>;
-/**
- * Invalidate a CONSUMED Gate-0 input by deleting it — the second half of
- * consume-and-invalidate, paired here with {@link readProviderConfirmationInput} so
- * the two cannot drift apart.
- *
- * The input's presence is the "operator has acted" signal the gate reads to decide
- * emit-vs-consume. Once promoted into the canonical artifacts it is SPENT: leaving it
- * on disk means a later reconciliation delta silently re-consumes a submission that
- * answered an older question, auto-satisfying the gate instead of asking the
- * operator. Deleting it is what makes the gate able to fire a second time at all.
- *
- * Best-effort and never throws: an already-absent file is the desired end state, and
- * a failed unlink must not break the in-flight obligation (the promotion itself
- * already succeeded).
- */
-export declare function unlinkProviderConfirmationInput(artifactsDir: string): Promise<void>;
-//# sourceMappingURL=sharedProviderConfirmation.d.ts.map