@zackbart/connecta 0.34.1 → 0.35.0

package/dist/operator-ui/model.d.ts

@@ -1,6 +1,6 @@
 import type { ConnectaConfigDescription } from "../describe-config.js";
+import type { CatalogAccessObservation, ResourceTemplateRefusalCode } from "../types.js";
 import type { OperatorConnectorOverlay, OperatorTool } from "./contract.js";
-import type { CatalogAccessObservation, CatalogDriftReport, ResourceTemplateRefusalCode } from "../types.js";
 /** Tool verdicts, independent of whether the selected pool is read-only. */
 export type UiToolSafety = "runs_in_programs" | "needs_approval";
 export interface UiTool extends Pick<OperatorTool, "name" | "address" | "description"> {
@@ -91,7 +91,6 @@ export interface UiConnector {
      * drifted — which is why the UI renders that as its own state rather than as
      * a clean one.
      */
-    catalogDrift?: CatalogDriftReport;
     /** Last agent-facing catalog read in this runtime; never persisted. */
     catalogAccess?: CatalogAccessObservation;
     resourceTemplateRefusals?: ResourceTemplateRefusalCode[];
@@ -114,7 +113,7 @@ export interface UiData {
      */
     pools?: string[];
 }
-export interface FilteredUiConnector {
+interface FilteredUiConnector {
     connector: UiConnector;
     tools: UiTool[];
 }

package/dist/operator-ui/overview.js

@@ -73,11 +73,14 @@ export function attentionItems(contract, options = {}) {
         }
     }
     const agents = contract.agents
-        .filter((agent) => agent.pools.length && agent.token.state !== "issued")
+        .filter((agent) => agent.pools.length &&
+        !agent.credentialTypes.includes("vercel_oidc") &&
+        agent.token &&
+        agent.token.state !== "issued")
         .map((agent) => {
         // An agent connects only at a pool's agent URL.
         const paths = agent.pools.map((name) => contract.pools.find((pool) => pool.name === name)?.agentPath ?? `/agent/${name}`);
-        const revoked = agent.token.state === "revoked";
+        const revoked = agent.token?.state === "revoked";
         return {
             key: `agent:${agent.name}`,
             kind: "agent",

package/dist/operator-ui/setup-commands.js

@@ -22,10 +22,6 @@ export function clientServerName(serverName, pool) {
         .slice(0, 48) || "connecta";
     return pool ? `${base}-${pool}` : base;
 }
-/** The URL for a pool: `/mcp` plus its name, which config limits to `[a-z0-9_-]`. */
-export function poolEndpointUrl(mcpUrl, pool) {
-    return `${mcpUrl.replace(/\/+$/, "")}/${encodeURIComponent(pool)}`;
-}
 /** POSIX single-quoting, only when the value needs it. */
 function shellWord(value) {
     return /^[A-Za-z0-9_./:@%+=,~-]+$/.test(value) ? value : `'${value.replace(/'/g, `'"'"'`)}'`;

package/dist/operator-ui/view.d.ts

@@ -1,8 +1,7 @@
+import type { AgentSlot } from "./agents.js";
 import type { OperatorRole, OperatorUiContractV2 } from "./contract.js";
-import type { CatalogDriftReport } from "../types.js";
-import type { CredentialManagementCapability, UiConnector, UiData, UiProblem } from "./model.js";
 import type { FixPromptKind } from "./fix-prompts.js";
-import type { AgentSlot } from "./agents.js";
+import type { UiConnector, UiData, UiProblem } from "./model.js";
 export declare function registrationPathLabel(path: NonNullable<UiConnector["registrationPath"]>): string;
 export type OperatorPage = "overview" | "endpoints" | "settings" | "connector" | "tokens" | "connections" | "activity";
 /** Pages the nav lists, in dashboard order. */
@@ -302,7 +301,6 @@ export declare function resetIdentity(state: OperatorState, gate?: Notice | null
  * typed credential, and the notices that answered the page just left.
  */
 export declare function withPage(state: OperatorState, page: OperatorPage): OperatorState;
-export declare function credentialUnavailableCopy(capability?: CredentialManagementCapability): string;
 /**
  * The status badge. An auth-needed connector is named by what it needs, so a
  * row whose fix is "Add credential" does not say "Authorization needed".
@@ -342,27 +340,6 @@ export declare function connectorVerdict(live: {
     status: string;
     problem?: UiProblem;
 }, signals?: ConnectorSignals): ConnectorVerdict;
-/**
- * Hosted-provider catalog drift, as an operator reads it
- * ([#343](https://github.com/zackbart/connecta/issues/343)).
- *
- * - `unavailable` — no refresh has been observed in this runtime, so there is
- *   nothing to report. Deliberately not `clean`: "we have not looked" and "we
- *   looked and it matches" are different answers, and only one of them is a
- *   reason to stop worrying.
- * - `clean` — a refresh happened and every category counted zero.
- * - `warning` — a refresh happened and at least one category did not.
- */
-export type DriftState = "clean" | "warning" | "unavailable";
-export declare function driftState(drift?: CatalogDriftReport): DriftState;
-/** Every category with its count, so a clean report still shows its zeros. */
-export declare function driftCounts(drift?: CatalogDriftReport): Array<{
-    key: string;
-    label: string;
-    count: number;
-}>;
-/** One line naming the state and when it was observed. Never what drifted. */
-export declare function driftSummary(drift?: CatalogDriftReport): string;
 /**
  * Only http/https may become a clickable href — the browser half of the gate
  * `src/ui.ts` applies before an authorizationUrl is ever serialized. A hostile

package/dist/operator-ui/view.js

@@ -345,15 +345,6 @@ export function withPage(state, page) {
         confirming: null,
     };
 }
-export function credentialUnavailableCopy(capability) {
-    if (capability === "no_slots") {
-        return "No connector declares a credential slot. Credentials stay in code.";
-    }
-    if (capability === "vault_not_configured") {
-        return "No credential vault is configured.";
-    }
-    return "Managing credentials needs an interactive sign-in. A bearer token can only view them.";
-}
 /**
  * The status badge. An auth-needed connector is named by what it needs, so a
  * row whose fix is "Add credential" does not say "Authorization needed".
@@ -445,73 +436,6 @@ export function connectorVerdict(live, signals = {}) {
     }
     return { tone: "ok", label: "Connected", action: null };
 }
-/**
- * The categories, in the order an operator should read them: what the
- * deployment refuses to call, what it can no longer call, what contradicts a
- * vetted verdict, and what changed shape underneath a reviewed schema. Counts
- * only — a name or a schema on this path would be the payload leak the whole
- * drift model exists to avoid.
- */
-const DRIFT_CATEGORIES = [
-    { key: "unclassifiedTools", label: "Unclassified" },
-    { key: "unservedTools", label: "Unserved" },
-    { key: "annotationConflicts", label: "Annotation conflicts" },
-    { key: "schemaChanges", label: "Schema changes" },
-    { key: "droppedTools", label: "Dropped tool names" },
-];
-function driftTotal(drift) {
-    if (!drift)
-        return 0;
-    return DRIFT_CATEGORIES.reduce((sum, { key }) => sum + (drift[key] || 0), 0);
-}
-export function driftState(drift) {
-    if (!drift)
-        return "unavailable";
-    if (driftTotal(drift) > 0)
-        return "warning";
-    if (drift.reviewedBaseline !== true ||
-        drift.verification !== "complete" ||
-        !drift.schemaCoverage ||
-        drift.schemaCoverage.unpinned > 0 ||
-        drift.schemaCoverage.pinned === 0)
-        return "unavailable";
-    return "clean";
-}
-/** Every category with its count, so a clean report still shows its zeros. */
-export function driftCounts(drift) {
-    if (!drift)
-        return [];
-    return DRIFT_CATEGORIES.filter(({ key }) => key !== "droppedTools" || drift.droppedTools !== undefined).map(({ key, label }) => ({
-        key,
-        label,
-        count: drift[key] || 0,
-    }));
-}
-/** One line naming the state and when it was observed. Never what drifted. */
-export function driftSummary(drift) {
-    if (!drift)
-        return "No catalog refresh yet.";
-    const observed = formatDate(drift.observedAt);
-    const when = observed ? ` · observed ${observed}` : "";
-    const total = driftTotal(drift);
-    const difference = total
-        ? `${total} difference${total === 1 ? "" : "s"}${drift.reviewedBaseline === false ? "" : " from the reviewed manifest"} · `
-        : "";
-    if (drift.reviewedBaseline === false)
-        return `${difference}No reviewed baseline${when}`;
-    if (drift.verification === "unavailable")
-        return `${difference}Schema verification unavailable${when}`;
-    const coverage = drift.schemaCoverage;
-    if (!coverage || coverage.pinned === 0)
-        return `${difference}Schemas not pinned${when}`;
-    if (coverage.unpinned > 0)
-        return `${difference}Partial schema coverage (${coverage.pinned} pinned, ${coverage.unpinned} not pinned)${when}`;
-    if (driftState(drift) === "clean")
-        return `Matches the reviewed manifest${when}`;
-    if (!total)
-        return `Schema verification unavailable${when}`;
-    return `${difference.replace(/ · $/, "")}${when}`;
-}
 /**
  * Only http/https may become a clickable href — the browser half of the gate
  * `src/ui.ts` applies before an authorizationUrl is ever serialized. A hostile
@@ -546,6 +470,7 @@ const ACTOR_KINDS = {
     "cloudflare-access": "Cloudflare Access",
     anonymous: "Anonymous",
     access_token: "Agent token",
+    vercel_oidc: "Vercel workload",
 };
 /** How a caller signed in, as a person reads it. An unknown kind is shown as sent. */
 function actorKindLabel(kind) {
@@ -628,6 +553,7 @@ export function activityOutcomeBadge(outcome) {
     return OUTCOME_BADGE[outcome] ?? { label: "Failed", tone: "danger" };
 }
 const SOURCE_LABELS = {
+    native: "Native tool call",
     execute_code: "In a program",
     call_tool: "Direct call",
     call_destructive_tool: "Direct call, approved by the host",

package/dist/program-writes.js

@@ -17,28 +17,38 @@ export function writeStateOf(outcome) {
             error: outcome.error,
             ...(outcome.answered !== undefined ? { answered: outcome.answered } : {}),
         });
-    return state === "unknown" && !outcome.ok && outcome.error.uncertainCall
+    if (state !== "unknown" || outcome.ok)
+        return state;
+    const { error } = outcome;
+    const handoff = (error.code === "auth_required" || error.code === "downstream_oauth_required") &&
+        error.nextAction &&
+        "tool" in error.nextAction &&
+        error.nextAction.tool === "authorize_connector"
         ? {
-            state,
-            uncertainCall: outcome.error.uncertainCall,
-            ...(outcome.error.details?.stage !== undefined
-                ? {
-                    deadline: {
-                        ...(outcome.error.details.operation !== undefined
-                            ? { operation: outcome.error.details.operation }
-                            : {}),
-                        stage: outcome.error.details.stage,
-                        ...(outcome.error.details.elapsedMs !== undefined
-                            ? { elapsedMs: outcome.error.details.elapsedMs }
-                            : {}),
-                        ...(outcome.error.details.deadlineMs !== undefined
-                            ? { deadlineMs: outcome.error.details.deadlineMs }
-                            : {}),
-                    },
-                }
-                : {}),
+            code: error.code,
+            ...(error.connector !== undefined ? { connector: error.connector } : {}),
+            ...(error.recovery !== undefined ? { recovery: error.recovery } : {}),
+            nextAction: error.nextAction,
+            ...(error.retry !== undefined ? { retry: error.retry } : {}),
         }
-        : state;
+        : undefined;
+    if (!error.uncertainCall && !handoff)
+        return state;
+    return {
+        state,
+        ...(error.uncertainCall ? { uncertainCall: error.uncertainCall } : {}),
+        ...(error.uncertainCall && error.details?.stage !== undefined
+            ? {
+                deadline: {
+                    ...(error.details.operation !== undefined ? { operation: error.details.operation } : {}),
+                    stage: error.details.stage,
+                    ...(error.details.elapsedMs !== undefined ? { elapsedMs: error.details.elapsedMs } : {}),
+                    ...(error.details.deadlineMs !== undefined ? { deadlineMs: error.details.deadlineMs } : {}),
+                },
+            }
+            : {}),
+        ...(handoff ? { handoff } : {}),
+    };
 }
 /**
  * The writes one program sends. The play closes this when the
@@ -55,6 +65,7 @@ export class ProgramWrites {
     uncertainCalls = [];
     uncertainCallsTruncated = false;
     deadlines = [];
+    handoff;
     /** Whether the program has settled: a write gated now is not sent. */
     get isClosed() {
         return this.closed;
@@ -80,12 +91,15 @@ export class ProgramWrites {
             recorded = true;
             const state = typeof completion === "string" ? completion : completion.state;
             if (typeof completion !== "string") {
-                if (this.uncertainCalls.length < 10)
-                    this.uncertainCalls.push(completion.uncertainCall);
-                else
-                    this.uncertainCallsTruncated = true;
+                if (completion.uncertainCall) {
+                    if (this.uncertainCalls.length < 10)
+                        this.uncertainCalls.push(completion.uncertainCall);
+                    else
+                        this.uncertainCallsTruncated = true;
+                }
                 if (completion.deadline && this.deadlines.length < 10)
                     this.deadlines.push(completion.deadline);
+                this.handoff ??= completion.handoff;
             }
             this.states.push(state);
             this.inFlight.delete(settled);
@@ -108,10 +122,17 @@ export class ProgramWrites {
             unknown: this.states.filter((state) => state === "unknown").length,
         };
         if (writes.unknown > 0) {
+            // Caught or not, an authorization verdict a write met after it left is
+            // the result, as a direct call reports it: its code and handoff, never
+            // retryable, with the write's outcome unknown.
+            const handoff = this.handoff;
             return errorEnvelope({
-                code: "write_outcome_unknown",
-                message: "A write this program sent has no known outcome, so that is the result rather than what the program returned. It will not be sent again. Check its target before doing anything that depends on it. Argument echoes may be partial or absent; use the original arguments if reconciliation requires another call.",
+                code: handoff?.code ?? "write_outcome_unknown",
+                message: handoff
+                    ? "A write this program sent failed authorization after it left, so whether it took effect is unknown, and that is the result rather than what the program returned. It will not be sent again. Check its target before doing anything that depends on it, and give nextAction to the operator to recover the connector. Argument echoes may be partial or absent; use the original arguments if reconciliation requires another call."
+                    : "A write this program sent has no known outcome, so that is the result rather than what the program returned. It will not be sent again. Check its target before doing anything that depends on it. Argument echoes may be partial or absent; use the original arguments if reconciliation requires another call.",
                 retryable: false,
+                ...(handoff ? { ...handoff, reconciliationRequired: true, writeOutcome: "unknown" } : {}),
                 ...(this.deadlines.length > 0 ? { details: this.deadlines[0] } : {}),
                 ...(this.deadlines.length > 1 ? { timeouts: this.deadlines } : {}),
                 ...(this.uncertainCalls.length === 1

package/dist/provider-call-facts.d.ts

@@ -0,0 +1,115 @@
+import { ConnectorCallError } from "./errors.js";
+import type { Connector } from "./types.js";
+export interface ProviderRequest {
+    readonly dispatched: boolean;
+    readonly status?: number;
+    auxiliary: boolean;
+    /** A kit auxiliary declared as a read lacked physical GET/HEAD proof at dispatch. */
+    readonly blocksAuxiliaryProof?: true;
+    provider: string;
+    /** The HTTP method it was sent with, when its channel knows it. */
+    readonly method?: string;
+    /** Positive operation/tool evidence; an HTTP method alone proves no read. */
+    classification?: "read" | "write" | undefined;
+    /** Remote MCP's source class said write, recorded at physical dispatch. */
+    readonly sourceWrite?: true;
+    /** The genuine, legal idempotency key the vendor honors that it carried; nothing else. */
+    key?: string;
+    /**
+     * Its answer was a 401 that the transport's reviewed `authBeforeExecution`
+     * evidence covers: the vendor rejected the credential before it acted on
+     * the request. Only that makes a 401 a refusal (`servedRefusal`).
+     */
+    authBeforeExecution?: true;
+    /**
+     * Its answer was a 401, and a renewal then replaced the credential it sent
+     * with a different one ({@link renewedAfterUnauthorized}). The 401 no
+     * longer needs the operator's recovery. The single `settleWrite` decider
+     * still reports unknown, without the handoff (Q8).
+     */
+    readonly renewed?: true;
+}
+export type CallTool = Connector["callTool"];
+interface Boundary {
+    /** The api() or remoteMcp() object whose own code enters the logical call. */
+    boundary: object;
+    own: CallTool;
+}
+export declare function originalCallIdentity(connector: object): object;
+export declare function boundaryFor(connector: object): Boundary | undefined;
+export declare function delegatorFor(connector: object): CallTool | undefined;
+/** A physical send owns its fields permanently; its own answer is recorded once. */
+export declare function recordRequestField(request: ProviderRequest, field: keyof ProviderRequest, value: unknown): void;
+export declare function recordProviderResponse(request: ProviderRequest, status: number): void;
+/**
+ * Declare that every request the connector's handlers send goes through a
+ * channel the call ledger records: a guarded transport, `ctx.fetch`, or
+ * `ctx.oauth.fetch`. Only then does an empty ledger prove that a failed
+ * write never left. Maintained providers declare it; an arbitrary `api()`
+ * handler can reach the network some other way, so its ledger proves nothing.
+ */
+export declare function tracksEveryRequest<T extends object>(connector: T): T;
+export declare function tracksRequests(connector: object): boolean;
+/**
+ * Declare a maintained connector whose `callTool` hands each call to at most
+ * one api() or remoteMcp() boundary and sends nothing else that could apply
+ * it (GitHub). Only then may that boundary's verdict stand for the call. The
+ * object and its function are recorded now, at construction: a later
+ * assignment to the property, or a copy of the object, declares nothing.
+ */
+export declare function delegatesEachCall<T extends Connector>(connector: T): T;
+/**
+ * Record a just-built api() or remoteMcp() object as a boundary, with its
+ * published `callTool`. Its own code then names the same object, from its
+ * closure, in {@link enterProviderBoundary}.
+ */
+export declare function providerBoundary(connector: Connector): void;
+/**
+ * `alias` serves `base` itself (`defineProvider`'s inheriting stamp), so it
+ * takes `base`'s recorded identities. Only construction code calls this.
+ */
+export declare function aliasCallIdentity(alias: object, base: object): void;
+/**
+ * Whether a served HTTP status says the request was refused, not applied: a
+ * 4xx other than 408. A 408 is a timeout, whose request may have been acted
+ * on; a 2xx or 5xx never proves a write unapplied. A 401 passes here, and
+ * `servedRefusal` still asks for the vendor's reviewed evidence.
+ */
+export declare function refusedStatus(status: number | undefined): boolean;
+/**
+ * Refusal provenance, recorded where the answer is observed: the request was
+ * served a refusing status (`refusedStatus`) and the mapper failed on it. An
+ * error code alone is never this evidence.
+ */
+export declare function vendorRefusal<T>(error: T, request: ProviderRequest): T;
+/** An authorization verdict, the kind that keeps the `authorize_connector` handoff. */
+export declare function authorizationFailure(error: unknown): error is ConnectorCallError;
+/**
+ * The authorization verdict `request`'s own 401 answer was mapped to, as
+ * {@link vendorRefusal} recorded it. Undefined when nothing mapped that
+ * answer, such as a body past the ceiling.
+ */
+export declare function unauthorizedAnswer(request: ProviderRequest): ConnectorCallError | undefined;
+/**
+ * A renewal answered `request`'s own 401 (a refresh, a login, a fresh token
+ * minted) with `fresh`, a credential other than `sent`, the one the request
+ * carried: that 401 no longer needs the operator's recovery (Q8). It names
+ * the one request it answered and never marks another. A renewal that hands
+ * back the credential the request already sent (an earlier recovery reused)
+ * renewed nothing.
+ */
+export declare function renewedAfterUnauthorized(request: ProviderRequest | undefined, sent: string, fresh: string): void;
+export declare function refusalRequest(error: unknown): ProviderRequest | undefined;
+export declare function knownProviderFailure<T>(error: T): T;
+export declare function isKnownProviderFailure(error: unknown): boolean;
+/** Withdraw a verdict that does not hold for the call that reports it. */
+export declare function forgetProviderFailure(error: object): void;
+/** Preserve internal verdicts and resend advice through redaction and provider recovery wording. */
+export declare function carryProviderFailure<T>(from: unknown, to: T): T;
+/** Mark a verdict that already accounts for a write's 401 in its own words. */
+export declare function explainedUnauthorizedVerdict<T>(error: T): T;
+export declare function explainsUnauthorized(error: unknown): boolean;
+/** Mark a verdict the Q8 decision made, final for every step after it. */
+export declare function settledWrite<T>(error: T): T;
+export declare function isSettledWrite(error: unknown): boolean;
+export {};

package/dist/provider-call-facts.js

@@ -0,0 +1,182 @@
+// Pure physical-request facts, failure provenance and construction identities.
+// No operation/call services or transport graph: provider definitions and
+// operator sinks can preserve provenance without acquiring Effect.
+import { carryResendAdvice, ConnectorCallError } from "./errors.js";
+import { followRedactedCopies } from "./redaction-identity.js";
+// A redacted copy of a failure is the same failure: its verdict follows it.
+const refusals = followRedactedCopies(new WeakMap());
+const knownFailures = followRedactedCopies(new WeakSet());
+// Verdicts that already account for a write's 401 in words of their own: a
+// renewal's (`unsentAfterUnauthorized`) or Q8's own. Q8 adds no sentence to them.
+const explainedUnauthorized = followRedactedCopies(new WeakSet());
+// Verdicts the one Q8 decision (`settleWrite`) made. They are final: nothing
+// after it may add retry, resend, key-reuse or wait advice to them.
+const settledWrites = followRedactedCopies(new WeakSet());
+// The authorization verdict a request's own 401 was mapped to, kept for the
+// call's verdict whatever failure surfaces after it (Q8).
+const unauthorizedAnswers = new WeakMap();
+const trackedConnectors = new WeakSet();
+const boundaries = new WeakMap();
+const delegators = new WeakMap();
+const aliases = new WeakMap();
+export function originalCallIdentity(connector) {
+    return aliases.get(connector) ?? connector;
+}
+export function boundaryFor(connector) {
+    return boundaries.get(connector);
+}
+export function delegatorFor(connector) {
+    return delegators.get(connector);
+}
+/** A physical send owns its fields permanently; its own answer is recorded once. */
+export function recordRequestField(request, field, value) {
+    Object.defineProperty(request, field, { value, enumerable: true, writable: false, configurable: false });
+}
+export function recordProviderResponse(request, status) {
+    if (request.status !== undefined)
+        throw new Error("Provider request already answered.");
+    recordRequestField(request, "status", status);
+}
+/**
+ * Declare that every request the connector's handlers send goes through a
+ * channel the call ledger records: a guarded transport, `ctx.fetch`, or
+ * `ctx.oauth.fetch`. Only then does an empty ledger prove that a failed
+ * write never left. Maintained providers declare it; an arbitrary `api()`
+ * handler can reach the network some other way, so its ledger proves nothing.
+ */
+export function tracksEveryRequest(connector) {
+    trackedConnectors.add(connector);
+    return connector;
+}
+export function tracksRequests(connector) {
+    return trackedConnectors.has(connector);
+}
+/**
+ * Declare a maintained connector whose `callTool` hands each call to at most
+ * one api() or remoteMcp() boundary and sends nothing else that could apply
+ * it (GitHub). Only then may that boundary's verdict stand for the call. The
+ * object and its function are recorded now, at construction: a later
+ * assignment to the property, or a copy of the object, declares nothing.
+ */
+export function delegatesEachCall(connector) {
+    delegators.set(connector, connector.callTool);
+    return connector;
+}
+/**
+ * Record a just-built api() or remoteMcp() object as a boundary, with its
+ * published `callTool`. Its own code then names the same object, from its
+ * closure, in {@link enterProviderBoundary}.
+ */
+export function providerBoundary(connector) {
+    boundaries.set(connector, { boundary: connector, own: connector.callTool });
+}
+/**
+ * `alias` serves `base` itself (`defineProvider`'s inheriting stamp), so it
+ * takes `base`'s recorded identities. Only construction code calls this.
+ */
+export function aliasCallIdentity(alias, base) {
+    aliases.set(alias, originalCallIdentity(base));
+    const boundary = boundaries.get(base);
+    const delegator = delegators.get(base);
+    if (boundary)
+        boundaries.set(alias, boundary);
+    if (delegator)
+        delegators.set(alias, delegator);
+}
+/**
+ * Whether a served HTTP status says the request was refused, not applied: a
+ * 4xx other than 408. A 408 is a timeout, whose request may have been acted
+ * on; a 2xx or 5xx never proves a write unapplied. A 401 passes here, and
+ * `servedRefusal` still asks for the vendor's reviewed evidence.
+ */
+export function refusedStatus(status) {
+    return status !== undefined && status >= 400 && status < 500 && status !== 408;
+}
+/**
+ * Refusal provenance, recorded where the answer is observed: the request was
+ * served a refusing status (`refusedStatus`) and the mapper failed on it. An
+ * error code alone is never this evidence.
+ */
+export function vendorRefusal(error, request) {
+    if (error !== null && typeof error === "object" && refusedStatus(request.status)) {
+        refusals.set(error, request);
+        if (request.status === 401 && authorizationFailure(error) && !unauthorizedAnswers.has(request))
+            unauthorizedAnswers.set(request, error);
+    }
+    return error;
+}
+/** An authorization verdict, the kind that keeps the `authorize_connector` handoff. */
+export function authorizationFailure(error) {
+    return (error instanceof ConnectorCallError &&
+        (error.code === "auth_required" || error.code === "downstream_oauth_required"));
+}
+/**
+ * The authorization verdict `request`'s own 401 answer was mapped to, as
+ * {@link vendorRefusal} recorded it. Undefined when nothing mapped that
+ * answer, such as a body past the ceiling.
+ */
+export function unauthorizedAnswer(request) {
+    return unauthorizedAnswers.get(request);
+}
+/**
+ * A renewal answered `request`'s own 401 (a refresh, a login, a fresh token
+ * minted) with `fresh`, a credential other than `sent`, the one the request
+ * carried: that 401 no longer needs the operator's recovery (Q8). It names
+ * the one request it answered and never marks another. A renewal that hands
+ * back the credential the request already sent (an earlier recovery reused)
+ * renewed nothing.
+ */
+export function renewedAfterUnauthorized(request, sent, fresh) {
+    if (request?.status === 401 && fresh !== sent && !request.renewed)
+        recordRequestField(request, "renewed", true);
+}
+export function refusalRequest(error) {
+    return error !== null && typeof error === "object" ? refusals.get(error) : undefined;
+}
+export function knownProviderFailure(error) {
+    if (error !== null && typeof error === "object")
+        knownFailures.add(error);
+    return error;
+}
+export function isKnownProviderFailure(error) {
+    return error !== null && typeof error === "object" && knownFailures.has(error);
+}
+/** Withdraw a verdict that does not hold for the call that reports it. */
+export function forgetProviderFailure(error) {
+    knownFailures.delete(error);
+    refusals.delete(error);
+}
+/** Preserve internal verdicts and resend advice through redaction and provider recovery wording. */
+export function carryProviderFailure(from, to) {
+    if (to !== null && typeof to === "object") {
+        const refusal = refusalRequest(from);
+        if (refusal)
+            refusals.set(to, refusal);
+        if (isKnownProviderFailure(from))
+            knownFailures.add(to);
+        if (explainsUnauthorized(from))
+            explainedUnauthorized.add(to);
+        if (isSettledWrite(from))
+            settledWrites.add(to);
+        carryResendAdvice(from, to);
+    }
+    return to;
+}
+/** Mark a verdict that already accounts for a write's 401 in its own words. */
+export function explainedUnauthorizedVerdict(error) {
+    if (error !== null && typeof error === "object")
+        explainedUnauthorized.add(error);
+    return error;
+}
+export function explainsUnauthorized(error) {
+    return error !== null && typeof error === "object" && explainedUnauthorized.has(error);
+}
+/** Mark a verdict the Q8 decision made, final for every step after it. */
+export function settledWrite(error) {
+    if (error !== null && typeof error === "object")
+        settledWrites.add(error);
+    return error;
+}
+export function isSettledWrite(error) {
+    return error !== null && typeof error === "object" && settledWrites.has(error);
+}