@cleocode/core 2026.9.19 → 2026.9.21

package/dist/decide/operations.js

@@ -0,0 +1,199 @@
+/**
+ * Operator-facing decision operations behind `cleo decide config|status|ask`.
+ *
+ * All logic lives here (the CLI handlers are thin, arch gate 6). Every value
+ * these functions return is secret-free: the API key appears only as a masked
+ * last-4 preview.
+ *
+ * @task T12491
+ * @epic T12486
+ */
+import { getProjectRoot } from '../paths.js';
+import { createJsonlDecisionAudit, } from './audit.js';
+import { decide } from './client.js';
+import { clearDecideCredentials, DecideCredentialsError, describeDecideCredentials, loadDecideConnection, sameDecideHost, saveDecideCredentials, } from './credentials.js';
+import { listJevModels } from './jev-wire.js';
+import { DecisionProviderError } from './provider.js';
+/** Default deadline for the `GET /v1/models` probe, ms. */
+export const DEFAULT_DECIDE_PROBE_TIMEOUT_MS = 3_000;
+/** Default deadline for `cleo decide ask`, ms (generous: it is a debug tool). */
+export const DEFAULT_DECIDE_ASK_TIMEOUT_MS = 10_000;
+const NO_MODEL_WARNING = 'No default model is configured. The Jev /v1/systemone endpoint requires a model; set one with `cleo decide config --model <name>` (see `models`).';
+function stateForError(err) {
+    if (err instanceof DecisionProviderError) {
+        if (err.kind === 'unauthorized')
+            return { state: 'unauthorized', httpStatus: err.status };
+        if (err.kind === 'invalid_response')
+            return { state: 'reachable', httpStatus: err.status };
+        return {
+            state: 'unreachable',
+            ...(err.status !== undefined ? { httpStatus: err.status } : {}),
+        };
+    }
+    return { state: 'unreachable' };
+}
+/**
+ * Probe the provider with `GET {baseUrl}/v1/models` under a short deadline.
+ * Never throws.
+ *
+ * @param opts - Connection, `fetch` and deadline.
+ * @returns The reachability verdict and, when listed, the available models.
+ */
+export async function probeDecideProvider(opts = {}) {
+    const sealed = opts.connection === undefined ? loadDecideConnection() : opts.connection;
+    if (!sealed) {
+        return {
+            state: 'unconfigured',
+            modelsEndpoint: 'skipped',
+            detail: 'Run `cleo decide config`.',
+        };
+    }
+    const base = {
+        baseUrl: sealed.baseUrl,
+        keyPreview: sealed.keyPreview,
+        ...(sealed.model ? { model: sealed.model } : {}),
+    };
+    const started = performance.now();
+    const signal = AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_DECIDE_PROBE_TIMEOUT_MS);
+    try {
+        const models = await listJevModels(sealed.connection(), signal, { fetch: opts.fetch });
+        return {
+            ...base,
+            state: 'reachable',
+            modelsEndpoint: 'ok',
+            models,
+            httpStatus: 200,
+            latencyMs: Math.round(performance.now() - started),
+            ...(sealed.model ? {} : { detail: NO_MODEL_WARNING }),
+        };
+    }
+    catch (err) {
+        const verdict = stateForError(err);
+        return {
+            ...base,
+            ...verdict,
+            modelsEndpoint: 'failed',
+            latencyMs: Math.round(performance.now() - started),
+            detail: err instanceof Error ? err.message : 'probe failed',
+        };
+    }
+}
+/**
+ * Store the provider settings, merging omitted values with the stored ones.
+ *
+ * The Jev `/v1/systemone` endpoint requires a `model`, and no model literal
+ * may be hard-coded in core (arch gate 13). So when no model is given (and
+ * none is stored for the same URL), this asks the provider (`GET /v1/models`)
+ * and stores the FIRST model it lists — the provider's own ordering; layahost
+ * lists its routing default first. When that lookup fails the settings are
+ * still stored, without a model, and a warning says how to set one.
+ *
+ * @param input - URL, key, optional model.
+ * @returns Secret-free summary plus the model's provenance.
+ * A URL whose host differs from the stored one must come with a fresh key:
+ * the stored key is never re-used (or sent in the model probe) for a new host.
+ *
+ * @throws {DecideCredentialsError} On an invalid URL, blank key, invalid model
+ *   name, or a host change without a fresh key.
+ */
+export async function configureDecide(input) {
+    const stored = loadDecideConnection();
+    const baseUrl = input.baseUrl?.trim() || stored?.baseUrl || '';
+    const freshKey = input.apiKey?.trim();
+    if (!freshKey && stored && !sameDecideHost(stored.baseUrl, baseUrl)) {
+        throw new DecideCredentialsError('changing the provider host requires a fresh key; pass --key-stdin (the stored key is never sent to a new host)');
+    }
+    const apiKey = freshKey || stored?.connection().apiKey || '';
+    const explicit = input.model?.trim();
+    if (explicit) {
+        return {
+            ...(await saveDecideCredentials({ baseUrl, apiKey, model: explicit })),
+            modelSource: 'flag',
+        };
+    }
+    if (stored?.model && stored.baseUrl === baseUrl) {
+        const kept = await saveDecideCredentials({ baseUrl, apiKey, model: stored.model });
+        return { ...kept, modelSource: 'stored' };
+    }
+    const saved = await saveDecideCredentials({ baseUrl, apiKey });
+    const probe = await probeDecideProvider({
+        connection: loadDecideConnection(),
+        fetch: input.fetch,
+        timeoutMs: input.timeoutMs,
+    });
+    const first = probe.models?.[0];
+    if (!first) {
+        const why = probe.state === 'reachable' ? 'the provider listed no models' : `probe ${probe.state}`;
+        return {
+            ...saved,
+            modelSource: 'none',
+            warning: `No model stored (${why}). ${NO_MODEL_WARNING}`,
+        };
+    }
+    const withModel = await saveDecideCredentials({ baseUrl, apiKey, model: first });
+    return { ...withModel, modelSource: 'provider-listing' };
+}
+/**
+ * Remove the stored settings (and rotated backups of them).
+ *
+ * @returns Whether anything was stored, plus the (now empty) summary.
+ */
+export async function clearDecideConfig() {
+    const cleared = await clearDecideCredentials();
+    return { ...describeDecideCredentials(), cleared };
+}
+/** Neutral heuristic for the debug question: 50/50 with zero confidence. */
+const NEUTRAL_NOUL = {
+    type: 'noul',
+    value: false,
+    probability: 0.5,
+    confidence: 0,
+};
+function teeAudit(projectRoot) {
+    let last;
+    let file = null;
+    try {
+        file = createJsonlDecisionAudit(projectRoot ?? getProjectRoot());
+    }
+    catch {
+        file = null;
+    }
+    return {
+        sink: {
+            write: (e) => {
+                last = e;
+                file?.write(e);
+            },
+        },
+        last: () => last,
+    };
+}
+/**
+ * Ask one yes/no question through the configured provider (debug surface).
+ * Uses no cache, so a repeat is a real round trip. Never throws.
+ *
+ * @param input - State, question and deadline.
+ * @returns The typed answer with source, fallback reason, latency and cost.
+ */
+export async function askDecideDebug(input) {
+    const sealed = loadDecideConnection();
+    const audit = teeAudit(input.projectRoot);
+    const outcome = await decide('cli.decide-ask', { state: input.state, questions: { answer: { type: 'noul', criteria: input.question } } }, () => ({ answer: NEUTRAL_NOUL }), {
+        connection: sealed?.connection() ?? null,
+        cache: null,
+        audit: audit.sink,
+        timeoutMs: input.timeoutMs ?? DEFAULT_DECIDE_ASK_TIMEOUT_MS,
+    });
+    const reason = audit.last()?.fallbackReason;
+    return {
+        answer: outcome.answers['answer'] ?? NEUTRAL_NOUL,
+        source: outcome.source,
+        ...(reason ? { fallbackReason: reason } : {}),
+        latencyMs: Math.round(outcome.latencyMs),
+        ...(outcome.costUsd !== undefined ? { costUsd: outcome.costUsd } : {}),
+        ...(outcome.requestId ? { requestId: outcome.requestId } : {}),
+        ...(sealed?.model ? { model: sealed.model } : {}),
+        ...(sealed ? { keyPreview: sealed.keyPreview } : {}),
+    };
+}
+//# sourceMappingURL=operations.js.map

package/dist/decide/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/decide/operations.ts"],"names":[],"mappings":"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"}

package/dist/decide/provider.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Decision-provider port — the swap point for "System One" typed decisions.
+ *
+ * A {@link DecisionProvider} executes one {@link DecisionRequest} and returns a
+ * {@link DecisionOutcome} with `source: 'provider'`. It knows nothing about
+ * caching, budgets, fallbacks or audit — those belong to the client
+ * (`./client.ts`). A provider SIGNALS failure by throwing a
+ * {@link DecisionProviderError}; the client converts every failure into a
+ * heuristic fallback, so callers of the client never see these errors.
+ *
+ * Swapping vendors means writing a new provider; the client, cache, budget and
+ * audit layers stay unchanged.
+ *
+ * @task T12490
+ * @epic T12486
+ */
+import type { DecisionOutcome, DecisionProviderConfig, DecisionRequest } from '@cleocode/contracts';
+/**
+ * Connection settings for a key-authenticated decision provider: the base URL
+ * from the contract plus the API key. The key is sent as a bearer token and is
+ * never logged, cached or audited.
+ */
+export interface DecisionProviderConnection extends DecisionProviderConfig {
+    /** API key, sent as `Authorization: Bearer <apiKey>`. */
+    readonly apiKey: string;
+    /**
+     * Default model for requests that do not name one. Absent → the request is
+     * sent without a model and the provider's own default (if any) applies.
+     */
+    readonly model?: string;
+}
+/**
+ * A typed-decision backend.
+ *
+ * Implementations MUST honour `signal` (abort the in-flight request when it
+ * fires) and MUST throw a {@link DecisionProviderError} — never return a
+ * partial outcome — when they cannot answer every question in the request.
+ */
+export interface DecisionProvider {
+    /**
+     * Execute one decision request.
+     *
+     * @param req - The (already redacted and validated) request.
+     * @param signal - Aborts the call; fired by the client's per-site timeout.
+     * @returns An outcome whose `answers` cover every question in `req`.
+     */
+    decide(req: DecisionRequest, signal: AbortSignal): Promise<DecisionOutcome>;
+}
+/**
+ * Why a provider call failed. Drives the client's fallback reason and, for
+ * `rate_limited`, the shared budget cool-down.
+ *
+ * - `unauthorized`        — 401: bad or missing key.
+ * - `insufficient_credits` — 402: the account is out of credit.
+ * - `rate_limited`        — 429: slow down; see `retryAfterMs`.
+ * - `invalid_request`     — 422 or another 4xx: the provider rejected the request.
+ * - `server_error`        — 5xx.
+ * - `network`             — the request never produced an HTTP response.
+ * - `aborted`             — the caller's signal fired (timeout).
+ * - `invalid_response`    — a 2xx whose body did not match the expected shape.
+ */
+export type DecisionProviderErrorKind = 'unauthorized' | 'insufficient_credits' | 'rate_limited' | 'invalid_request' | 'server_error' | 'network' | 'aborted' | 'invalid_response';
+/** Construction options for {@link DecisionProviderError}. */
+export interface DecisionProviderErrorOptions {
+    /** HTTP status, when the failure came from an HTTP response. */
+    readonly status?: number;
+    /** Server-requested back-off in milliseconds (429 `retry-after`). */
+    readonly retryAfterMs?: number;
+    /** Underlying cause, for diagnostics. */
+    readonly cause?: Error;
+}
+/**
+ * The single error type a {@link DecisionProvider} throws. The message never
+ * contains the API key or the request state.
+ */
+export declare class DecisionProviderError extends Error {
+    /** Failure classification. */
+    readonly kind: DecisionProviderErrorKind;
+    /** HTTP status, when known. */
+    readonly status?: number;
+    /** Server-requested back-off in milliseconds, when known. */
+    readonly retryAfterMs?: number;
+    /**
+     * @param kind - Failure classification.
+     * @param message - Human-readable, secret-free description.
+     * @param opts - Status, retry-after and cause.
+     */
+    constructor(kind: DecisionProviderErrorKind, message: string, opts?: DecisionProviderErrorOptions);
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/decide/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/decide/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEpG;;;;GAIG;AACH,MAAM,WAAW,0BAA2B,SAAQ,sBAAsB;IACxE,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7E;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,yBAAyB,GACjC,cAAc,GACd,sBAAsB,GACtB,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,SAAS,GACT,SAAS,GACT,kBAAkB,CAAC;AAEvB,8DAA8D;AAC9D,MAAM,WAAW,4BAA4B;IAC3C,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;gBAED,IAAI,EAAE,yBAAyB,EAC/B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,4BAAiC;CAQ1C"}

package/dist/decide/provider.js

@@ -0,0 +1,43 @@
+/**
+ * Decision-provider port — the swap point for "System One" typed decisions.
+ *
+ * A {@link DecisionProvider} executes one {@link DecisionRequest} and returns a
+ * {@link DecisionOutcome} with `source: 'provider'`. It knows nothing about
+ * caching, budgets, fallbacks or audit — those belong to the client
+ * (`./client.ts`). A provider SIGNALS failure by throwing a
+ * {@link DecisionProviderError}; the client converts every failure into a
+ * heuristic fallback, so callers of the client never see these errors.
+ *
+ * Swapping vendors means writing a new provider; the client, cache, budget and
+ * audit layers stay unchanged.
+ *
+ * @task T12490
+ * @epic T12486
+ */
+/**
+ * The single error type a {@link DecisionProvider} throws. The message never
+ * contains the API key or the request state.
+ */
+export class DecisionProviderError extends Error {
+    /** Failure classification. */
+    kind;
+    /** HTTP status, when known. */
+    status;
+    /** Server-requested back-off in milliseconds, when known. */
+    retryAfterMs;
+    /**
+     * @param kind - Failure classification.
+     * @param message - Human-readable, secret-free description.
+     * @param opts - Status, retry-after and cause.
+     */
+    constructor(kind, message, opts = {}) {
+        super(message, opts.cause ? { cause: opts.cause } : undefined);
+        this.name = 'DecisionProviderError';
+        this.kind = kind;
+        if (opts.status !== undefined)
+            this.status = opts.status;
+        if (opts.retryAfterMs !== undefined)
+            this.retryAfterMs = opts.retryAfterMs;
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/decide/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/decide/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAsEH;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,8BAA8B;IACrB,IAAI,CAA4B;IACzC,+BAA+B;IACtB,MAAM,CAAU;IACzB,6DAA6D;IACpD,YAAY,CAAU;IAE/B;;;;OAIG;IACH,YACE,IAA+B,EAC/B,OAAe,EACf,OAAqC,EAAE;QAEvC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QACzD,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;YAAE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IAC7E,CAAC;CACF"}

package/dist/decide/site.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Shared plumbing for System One call sites: the `off | shadow | on` mode,
+ * the generative-fallback opt-in, and redact-then-clip for state text.
+ *
+ * Every site resolves its settings the same way, so the rule that an
+ * unconfigured provider means `off` (and therefore zero network) lives here
+ * once. Heavy modules (credentials, config registry) load lazily: importing
+ * this file costs nothing on a path that never asks a decision.
+ *
+ * @task T12493
+ * @epic T12486
+ */
+import type { DecisionAnswer, DecisionOutcomeSource, DecisionRequest } from '@cleocode/contracts';
+import type { DecisionAuditAnswer, DecisionShadowRecord } from './audit.js';
+import type { DecideOptions } from './client.js';
+/**
+ * How a call site uses System One.
+ *
+ * - `off` — never ask; the heuristic acts.
+ * - `shadow` — ask, audit both answers, act on the heuristic.
+ * - `on` — ask and act on the decision when it is confident enough.
+ */
+export type DecisionSiteMode = 'off' | 'shadow' | 'on';
+/** Resolved settings for one call-site invocation. */
+export interface DecisionSiteSettings {
+    /** Effective mode; always `off` when no provider is configured. */
+    readonly mode: DecisionSiteMode;
+    /** Whether the site's older generative-LLM path runs. */
+    readonly llmTier: boolean;
+}
+/** Inputs to {@link resolveDecisionSiteSettings}. */
+export interface ResolveDecisionSiteSettingsInput {
+    /** Config key holding the site mode, e.g. `decide.sites.duplicateDetection`. */
+    readonly modeKey: string;
+    /**
+     * Config key holding the generative opt-in, e.g. `decide.generativeFallback.duplicateDetection`.
+     * Absent for a site with no generative path: `llmTier` then comes from the
+     * explicit input or {@link ResolveDecisionSiteSettingsInput.llmTierDefault}.
+     */
+    readonly llmTierKey?: string;
+    /** Explicit mode; wins over config when a provider is configured. */
+    readonly mode?: DecisionSiteMode;
+    /** Explicit generative opt-in; wins over config. */
+    readonly llmTier?: boolean;
+    /**
+     * Generative default when the config key is absent, given the effective
+     * mode (`off` whenever System One is unconfigured). Sites whose generative
+     * path ran unconditionally before System One use it to stay
+     * behaviour-neutral outside `on`. Default: always `false`.
+     */
+    readonly llmTierDefault?: (mode: DecisionSiteMode) => boolean;
+    /** The `decide()` wiring the site will use; an explicit provider or connection decides "configured". */
+    readonly wiring?: DecideOptions;
+    /** Project root for config lookup. Default: the resolved CLEO project root. */
+    readonly projectRoot?: string;
+}
+/**
+ * Type guard for {@link DecisionSiteMode}.
+ *
+ * @param value - Any config value.
+ * @returns Whether `value` is `off`, `shadow` or `on`.
+ */
+export declare function isDecisionSiteMode(value: unknown): value is DecisionSiteMode;
+/**
+ * Redact secrets, THEN clip to `max` characters, marking the cut.
+ *
+ * The order matters: clipping first can cut a secret in half, and a partial
+ * secret no longer matches the redaction patterns — `decide()`'s own redaction
+ * would then let the prefix through.
+ *
+ * @param text - Raw text.
+ * @param max - Maximum length of the result, in UTF-16 characters.
+ * @param redact - The redaction function (the memory redaction patterns).
+ * @returns Redacted text of at most `max` characters.
+ */
+export declare function redactThenClip(text: string, max: number, redact: (s: string) => string): string;
+/**
+ * Resolve a site's mode and generative opt-in.
+ *
+ * Unconfigured (no explicit provider/connection and nothing stored by
+ * `cleo decide config`) always resolves to `off`, whatever the config says,
+ * so an unconfigured site never opens a socket. Never throws: unreadable
+ * credentials or config fall back to the defaults.
+ *
+ * @param input - Config keys, explicit overrides and wiring.
+ * @returns The effective settings.
+ */
+export declare function resolveDecisionSiteSettings(input: ResolveDecisionSiteSettingsInput): Promise<DecisionSiteSettings>;
+/** Inputs to {@link askSiteDecision}. */
+export interface AskSiteDecisionInput {
+    /** Call-site id; keys the audit line. */
+    readonly siteId: string;
+    /**
+     * Budget in ms for WAITING on the decision: request building, redaction, the
+     * shared request budget and the provider round trip. It starts once the
+     * decision modules are loaded — module loading is a cold-start cost, not
+     * provider wait, and charging it would starve every fresh CLI process.
+     */
+    readonly budgetMs: number;
+    /** Minimum confidence EVERY answer needs before `on` mode may act on the decision. */
+    readonly minConfidence: number;
+    /** Effective mode (`off` never reaches a decision). */
+    readonly mode: Exclude<DecisionSiteMode, 'off'>;
+    /** The heuristic's overall verdict, in the site's vocabulary. */
+    readonly heuristicVerdict: string;
+    /** Build the request; `redact` is the memory redaction, to apply BEFORE clipping. */
+    readonly buildRequest: (redact: (s: string) => string) => DecisionRequest;
+    /** The heuristic's answer to every question; also the fallback. */
+    readonly heuristicAnswers: Readonly<Record<string, DecisionAnswer>>;
+    /**
+     * Site-level validity beyond the client's type check (e.g. a `choice` value
+     * among the offered options). An answered but invalid outcome is audited as
+     * `rejected: "invalid_choice"` and the heuristic acts. Default: valid.
+     */
+    readonly isValid?: (answers: Readonly<Record<string, DecisionAuditAnswer>>) => boolean;
+    /** Whether valid decided answers agree with the heuristic, on the axis the site acts on. */
+    readonly agree: (answers: Readonly<Record<string, DecisionAuditAnswer>>) => boolean;
+    /** Per-question extras for the shadow record. */
+    readonly shadowExtras?: Pick<DecisionShadowRecord, 'heuristicVerdicts' | 'heuristicScores' | 'subjects'>;
+    /** Provider, connection, budget, cache and audit wiring forwarded to `decide()`. */
+    readonly wiring?: DecideOptions;
+    /** Project root for the default audit sink. */
+    readonly projectRoot?: string;
+}
+/** A provider (or cached) answer that passed the site's validity check. */
+export interface SiteDecision {
+    /** The decided answers. */
+    readonly answers: Readonly<Record<string, DecisionAnswer>>;
+    /** `provider` or `cache`. */
+    readonly source: Exclude<DecisionOutcomeSource, 'fallback'>;
+    /** Whether every answer met `minConfidence`; only then may `on` act. */
+    readonly confident: boolean;
+}
+/**
+ * Ask one budgeted System One decision for a call site, auditing the
+ * heuristic's answers beside the decision's in the same `decisions.jsonl` line.
+ *
+ * Never throws. Heavy modules load lazily FIRST; then the deadline starts, and
+ * the provider is never waited on longer than `budgetMs` (request building,
+ * redaction, the audit sink and the client's own setup are inside it). Module
+ * load is excluded on purpose: in a cold process it alone can exceed the
+ * budget, and a budget that includes it means a fast provider never answers.
+ *
+ * @param input - Site id, budget, mode, request builder, heuristic and wiring.
+ * @returns The decision, or `null` when the heuristic answered (fallback) or the answer was invalid.
+ */
+export declare function askSiteDecision(input: AskSiteDecisionInput): Promise<SiteDecision | null>;
+//# sourceMappingURL=site.d.ts.map

package/dist/decide/site.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site.d.ts","sourceRoot":"","sources":["../../src/decide/site.ts"],"names":[],"mappings":"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"}