audit-tools 0.32.67 → 0.33.0

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

@@ -2,43 +2,51 @@
  * 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 confirmed provider pool 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 unless the roster has
- * since changed. "Session" = the shared `.audit-tools` dir for that repo+run, so
- * no new identity scheme is needed.
- *
- * Two invariants are in tension and are reconciled here by the CE-012 third
- * state:
- *   - INV-DC1-6 (never-block): remediate run standalone with no prior audit must
- *     resolve its provider independently, exactly as today — absence of the
- *     artifact is NOT an error.
- *   - INV-DC2-3 (roster-stale-re-confirm): a confirmation whose discovered roster
- *     no longer matches the current one must NOT be silently honored (it could
- *     pin a provider that has since disappeared) — it must re-confirm.
- * A single `null` return cannot carry both meanings (CE-012). So the accessor
- * returns a THREE-valued result: `null` for absent/malformed (never-block),
- * `{ status: 'confirmed' }` for a fresh honor, and the DISTINCT
- * `{ status: 'reconfirm' }` for roster-stale — so honoring INV-DC2-3 no longer
- * contradicts INV-DC1-6.
+ * 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 roster 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.
+ * 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, HostModelCostEntry, SourcePoolCostEntry, ProviderConfirmationInput } from "../types/providerConfirmation.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, a distinct shape that also carries the
- * roster snapshot used for staleness.
+ * 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";
 /**
@@ -52,22 +60,88 @@ export declare const SHARED_PROVIDER_CONFIRMATION_FILENAME = "provider-confirmat
 /** `<root>/.audit-tools/provider-confirmation.json` (absolute). */
 export declare function sharedProviderConfirmationPath(root: string): string;
 /**
- * The shared session-level provider confirmation. Single-sourced so both
- * orchestrators read/write exactly the same shape.
+ * 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}).
  *
- * `roster` is the sorted snapshot of the provider names discovered at write
- * time. Staleness is "the current discovered roster differs from this snapshot"
- * — a provider appearing or disappearing forces a re-confirm.
+ * 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.
+     */
+    exclude?: DispatchExclusionPattern[];
+    /** Self-spawn-blocked provider names the operator explicitly opted back IN. */
+    include?: ResolvedProviderName[];
+}
+/**
+ * One rule in the operator's exclusion grammar — **reach-independent by
+ * construction**, so a rule authored on one auditor means the same thing to an
+ * auditor with a different reachable set (spec/unified-dispatch-worker-model.md).
+ *
+ * Three forms, disambiguated by the head token against the CLOSED set of provider
+ * names ({@link RESOLVED_PROVIDER_NAMES}) — so no form can shadow another:
+ *
+ * | Pattern | Head is a provider name? | Matches |
+ * |---|---|---|
+ * | `openai-compatible:gpt-oss-120b` | yes | that provider AND that exact model — the **default** granularity |
+ * | `codex` | yes (no `:`) | every backend of that provider — the coarse provider tier |
+ * | `integrate.api.nvidia.com` / `localhost:8000` | no | every source whose `endpoint` host (and port, when the pattern names one) matches — the coarse endpoint tier |
+ *
+ * ⚠ This is a THIRD keyspace, deliberately distinct from the quota-ledger pool
+ * identity (`provider[#account]/model`, `buildProviderModelKey`): 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 {
+    provider: 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;
+}
 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;
-    /** Confirmed provider pool, with exclusion flags. */
-    provider_pool: ConfirmedPoolEntry[];
+    /**
+     * 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
@@ -92,34 +166,26 @@ export interface SharedProviderConfirmation {
      * (or a headless run) behaves exactly as before.
      */
     dispatch_bias?: number;
-    /**
-     * Sorted snapshot of the provider NAMES discovered when this was written.
-     * Compared against the current discovered roster to detect staleness.
-     */
-    roster: ResolvedProviderName[];
 }
 /**
- * Outcome of reading the shared confirmation. THREE-valued (CE-012):
- *   - `null`                       absent or malformed → never-block (INV-DC1-6)
- *   - `{ status: 'confirmed' }`    present + roster matches → honor it
- *   - `{ status: 'reconfirm' }`    present + roster changed → re-confirm (INV-DC2-3)
+ * 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 type SharedProviderConfirmationRead = {
-    status: "confirmed";
-    confirmation: SharedProviderConfirmation;
-} | {
-    status: "reconfirm";
-    confirmation: SharedProviderConfirmation;
-    reason: string;
-} | null;
+export interface RenderedProviderConfirmation extends Omit<SharedProviderConfirmation, "provider_pool"> {
+    provider_pool: ConfirmedPoolEntry[];
+}
 /**
- * The current discovered provider roster: the sorted set of provider names
- * `discoverProviders` surfaces for this session config + environment. PB-1's
- * opencode opt-in is inherited from `discoverProviders` (a bare-PATH opencode is
- * not surfaced unless explicitly configured), so it never spuriously perturbs
- * the roster.
+ * 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 currentProviderRoster(sessionConfig: SessionConfig, env?: NodeJS.ProcessEnv, detectCommand?: (command: string) => boolean): ResolvedProviderName[];
+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
@@ -137,7 +203,10 @@ export declare function currentProviderRoster(sessionConfig: SessionConfig, env?
  *
  * @param sessionConfig - Current session config; may be an empty `{}`.
  * @param env           - Process env snapshot; defaults to `process.env`.
- * @param exclude       - Provider names to pre-exclude (from a prior gate).
+ * @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
@@ -150,7 +219,100 @@ export declare function currentProviderRoster(sessionConfig: SessionConfig, env?
  *   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 buildSharedProviderConfirmation(sessionConfig?: SessionConfig, env?: NodeJS.ProcessEnv, exclude?: ResolvedProviderName[], include?: ResolvedProviderName[], detectCommand?: (command: string) => boolean, input?: ProviderConfirmationInput, sources?: DispatchableSource[]): SharedProviderConfirmation;
+export declare function buildProviderConfirmationRender(sessionConfig?: SessionConfig, env?: NodeJS.ProcessEnv, exclude?: DispatchExclusionPattern[], include?: ResolvedProviderName[], detectCommand?: (command: string) => boolean, input?: ProviderConfirmationInput, sources?: DispatchableSource[]): 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.
+ */
+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 — `model_id ?? provider name`. Stable, operator-facing. */
+    key: string;
+    /** The backend's provider name. Display only — the prompt names it beside `key`. */
+    provider: ResolvedProviderName;
+    /**
+     * The {@link DispatchExclusionPattern} that rules out **exactly this backend** —
+     * `provider:model` where the model is knowable, else the coarse `provider` tier.
+     * Built HERE rather than re-derived by the autonomous fail-closed write, so the
+     * rule the gate persists cannot drift from the key the gate compared.
+     */
+    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_SOURCE_PROVIDERS`, 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;
+/**
+ * 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
@@ -161,44 +323,55 @@ export declare function buildSharedProviderConfirmation(sessionConfig?: SessionC
  */
 export declare function writeSharedProviderConfirmation(root: string, confirmation: SharedProviderConfirmation, logger?: RunLogger): Promise<void>;
 /**
- * Read + interpret the shared confirmation for `root`. THREE-valued (CE-012):
+ * 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 `{ status: 'confirmed', confirmation }` when the artifact is valid
- *     AND the stamped roster still matches the currently-discovered roster — the
- *     caller honors the recorded pool.
- *   - returns `{ status: 'reconfirm', confirmation, reason }` when the artifact
- *     is valid but the roster has CHANGED since it was written (a provider
- *     appeared or disappeared) — a DISTINCT signal so the caller re-confirms
- *     rather than pinning a stale pool (INV-DC2-3). This is the CE-012 third
- *     state that keeps INV-DC2-3 from collapsing into the never-block `null`.
+ *   - 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, sessionConfig?: SessionConfig, env?: NodeJS.ProcessEnv): Promise<SharedProviderConfirmationRead>;
+export declare function readSharedProviderConfirmation(root: string): Promise<SharedProviderConfirmation | null>;
 /**
  * Read the operator-confirmed cost ordering (rung 1 of costRank; see
  * spec/cost-first-routing.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`, a missing/malformed confirmation, or a roster that has since changed
- * (`reconfirm`) all yield an empty map — dispatch then falls to real price then
- * tier. Only a `confirmed` (roster-fresh) confirmation contributes positions.
+ * `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, sessionConfig?: SessionConfig, env?: NodeJS.ProcessEnv): Promise<Map<string, number>>;
+export declare function readConfirmedCostPositions(root: string | undefined): Promise<Map<string, number>>;
 /**
  * Read the operator-confirmed cost↔speed dispatch bias (λ ∈ [0,1]) from the shared
  * Gate-0 confirmation for the dispatch build sites (spec/dispatch-cost-speed-dial.md).
  * Single-sourced so audit and remediate apply the identical operating point.
- * Best-effort and never throws: an absent `root`, a missing/malformed confirmation, a
- * roster that has since changed (`reconfirm`), or an absent field all yield the
- * cost-first default `0`. Only a `confirmed` (roster-fresh) confirmation contributes.
+ * 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, sessionConfig?: SessionConfig, env?: NodeJS.ProcessEnv): Promise<number>;
+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";
 /**
@@ -215,4 +388,20 @@ export declare function parseProviderConfirmationInput(value: unknown): Provider
  * has not acted yet" signal the gate uses to decide emit-vs-consume. Never throws.
  */
 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

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

@@ -1 +1 @@
-{"version":3,"file":"sharedProviderConfirmation.d.ts","sourceRoot":"","sources":["../../../src/shared/providers/sharedProviderConfirmation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sharedProviderConfirmation.d.ts","sourceRoot":"","sources":["../../../src/shared/providers/sharedProviderConfirmation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAMzG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAQ5D,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EAC1B,MAAM,kCAAkC,CAAC;AAO1C;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,EAAG,OAAgB,CAAC;AAErE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGpE;AAED,gFAAgF;AAChF,eAAO,MAAM,qCAAqC,+BACpB,CAAC;AAE/B,mEAAmE;AACnE,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACrC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAE9C,kGAAkG;AAClG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;CAC/C;AAED,MAAM,WAAW,0BAA0B;IACzC,uDAAuD;IACvD,cAAc,EAAE,OAAO,oCAAoC,CAAC;IAC5D;;;;;OAKG;IACH,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,0EAA0E;IAC1E,aAAa,EAAE,IAAI,CAAC;IACpB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC7C;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC/C;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BACf,SAAQ,IAAI,CAAC,0BAA0B,EAAE,eAAe,CAAC;IACzD,aAAa,EAAE,kBAAkB,EAAE,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,GAAG,IAAI,EAAE,UAAU,CAAC,OAAO,+BAA+B,CAAC,GAC1D,0BAA0B,CAM5B;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,+BAA+B,CAC7C,aAAa,GAAE,aAAkB,EACjC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,wBAAwB,EAAO,EACxC,OAAO,GAAE,oBAAoB,EAAO,EACpC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,EAC5C,KAAK,CAAC,EAAE,yBAAyB,EACjC,OAAO,GAAE,kBAAkB,EAAO,GACjC,4BAA4B,CAuE9B;AAiGD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,0BAA0B,GACvC,GAAG,CAAC,MAAM,CAAC,CAYb;AAED,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;;;;;OAKG;IACH,iBAAiB,EAAE,wBAAwB,CAAC;CAC7C;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,0BAA0B,EACxC,aAAa,EAAE,aAAa,EAC5B,OAAO,GAAE,SAAS,kBAAkB,EAAO,EAC3C,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,GAC3C,qBAAqB,EAAE,CAsBzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,EAClD,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,iBAAiB,CASnB;AAoGD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAYzC;AAMD;;;;;;;GAOG;AACH,wBAAsB,+BAA+B,CACnD,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,0BAA0B,EACxC,MAAM,CAAC,EAAE,SAAS,GACjB,OAAO,CAAC,IAAI,CAAC,CAef;AA2ID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,0BAA0B,GAAG,IAAI,CAAC,CAa5C;AAuCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAgC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAAC,MAAM,CAAC,CAKjB;AAMD,gFAAgF;AAChF,eAAO,MAAM,oCAAoC,qCACb,CAAC;AAErC;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,yBAAyB,GAAG,IAAI,CA0ClC;AAED;;;;GAIG;AACH,wBAAsB,6BAA6B,CACjD,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAS3C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,+BAA+B,CACnD,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAMf"}