@cleocode/core 2026.9.20 → 2026.9.21

package/dist/decide/credentials.js

@@ -0,0 +1,383 @@
+/**
+ * Decision-provider credential store — the two settings a user supplies
+ * (an API base URL and an API key) plus an optional default model.
+ *
+ * Stored at `<cleoHome>/decide-credentials.json` (resolved through
+ * `@cleocode/paths`, arch gate 2) with 0600 permissions:
+ *
+ * - Writes go through `withLock` (cross-process lock) and
+ *   `writeJsonFileAtomic({ mode: 0o600 })`, so neither the live file, the
+ *   temp file nor a rotated backup ever exists at a looser mode. Modelled on
+ *   `../llm/credentials-store.ts`.
+ * - The file lives at the TOP level of the CLEO home so its rotated backups
+ *   land in the owner-only `<cleoHome>/.backups/`, and the portable-bundle
+ *   scanner classifies it as a secret (see `store/portable-bundle-scan.ts`).
+ * - Reads return a {@link SealedDecideConnection}: the key sits in a private
+ *   class field, so `JSON.stringify`, `util.inspect` and template strings of
+ *   the handle only ever show a masked last-4 preview. The plaintext is
+ *   materialised solely by {@link SealedDecideConnection.connection}, which the
+ *   decision client calls at the wire.
+ *
+ * The key never lands in `config.json`, logs, LAFS envelopes or the decisions
+ * audit: nothing here logs, and every summary this module returns carries the
+ * masked preview only.
+ *
+ * @task T12491
+ * @epic T12486
+ */
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { inspect } from 'node:util';
+import { decisionProviderConfigSchema } from '@cleocode/contracts';
+import { getCleoHome } from '@cleocode/paths';
+import { z } from 'zod';
+import { withLock } from '../store/file-utils.js';
+import { isValidDecisionModelName } from './jev-wire.js';
+/** File name of the store, directly under the CLEO home. */
+export const DECIDE_CREDENTIALS_FILE = 'decide-credentials.json';
+/** On-disk shape of the store. `null` settings mean "not configured". */
+const storeSchema = z.object({
+    version: z.literal(1),
+    baseUrl: z.string().nullable(),
+    apiKey: z.string().nullable(),
+    model: z.string().nullable().optional(),
+    updatedAt: z.string().optional(),
+});
+const EMPTY_STORE = { version: 1, baseUrl: null, apiKey: null };
+/**
+ * Absolute path of the decision-credential store.
+ *
+ * @returns `<cleoHome>/decide-credentials.json`.
+ */
+export function decideCredentialsPath() {
+    return join(getCleoHome(), DECIDE_CREDENTIALS_FILE);
+}
+/**
+ * Mask an API key down to its last four characters.
+ *
+ * @param apiKey - Plaintext key (read transiently, not retained).
+ * @returns `…` plus at most the last 4 characters; `…` alone for keys of 4 or fewer characters.
+ */
+export function maskApiKey(apiKey) {
+    const key = apiKey.trim();
+    return key.length > 4 ? `…${key.slice(-4)}` : '…';
+}
+/**
+ * Opaque handle to a stored connection. The key is held in a private field;
+ * serialising or inspecting the handle yields the masked preview only.
+ */
+export class SealedDecideConnection {
+    /** Provider base URL (not secret). */
+    baseUrl;
+    /** Default model, when configured. */
+    model;
+    /** Masked key preview (`…abcd`). */
+    keyPreview;
+    #apiKey;
+    /**
+     * @param baseUrl - Provider base URL.
+     * @param apiKey - Plaintext key; captured privately.
+     * @param model - Optional default model.
+     */
+    constructor(baseUrl, apiKey, model) {
+        this.baseUrl = baseUrl;
+        this.#apiKey = apiKey;
+        this.keyPreview = maskApiKey(apiKey);
+        if (model)
+            this.model = model;
+    }
+    /**
+     * Materialise the wire connection. Call only where the request is built.
+     *
+     * @returns Base URL, plaintext key and optional model.
+     */
+    connection() {
+        return {
+            baseUrl: this.baseUrl,
+            apiKey: this.#apiKey,
+            ...(this.model ? { model: this.model } : {}),
+        };
+    }
+    /** @returns The secret-free JSON form. */
+    toJSON() {
+        return {
+            baseUrl: this.baseUrl,
+            ...(this.model ? { model: this.model } : {}),
+            keyPreview: this.keyPreview,
+        };
+    }
+    /** @returns A secret-free string form. */
+    toString() {
+        return `SealedDecideConnection(${this.baseUrl}, key ${this.keyPreview})`;
+    }
+    /** Secret-free `util.inspect` / `console.log` form. */
+    [inspect.custom]() {
+        return this.toString();
+    }
+}
+/** Read and parse the store. Never throws; missing or malformed → empty. */
+function readStoreSync(path = decideCredentialsPath()) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return EMPTY_STORE;
+    }
+    if (!raw.trim())
+        return EMPTY_STORE;
+    try {
+        const parsed = storeSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : EMPTY_STORE;
+    }
+    catch {
+        return EMPTY_STORE;
+    }
+}
+/** `scheme://user:pass@` prefix of a URL — matched textually so an unparseable URL is covered too. */
+const USERINFO_RE = /^([a-z][a-z0-9+.-]*:\/\/)[^/?#@]*@/i;
+/** Whether `baseUrl` carries userinfo (`user:pass@`). */
+function hasUserinfo(baseUrl) {
+    return USERINFO_RE.test(baseUrl.trim());
+}
+/** `baseUrl` with any userinfo removed, for display. */
+function withoutUserinfo(baseUrl) {
+    return baseUrl.replace(USERINFO_RE, '$1');
+}
+/** Hostnames for which plain `http://` is allowed (the loopback interface only). */
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+/**
+ * Whether `baseUrl` is an acceptable provider URL: absolute `https://`, or
+ * plain `http://` to a loopback host (`localhost`, `127.0.0.1`, `::1`). A
+ * remote plain-http URL is rejected so the bearer key never crosses the
+ * network in clear text.
+ *
+ * @param baseUrl - Candidate base URL.
+ * @returns True when the URL may be stored and used.
+ */
+export function isAllowedDecideBaseUrl(baseUrl) {
+    if (!decisionProviderConfigSchema.safeParse({ baseUrl }).success)
+        return false;
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return false;
+    }
+    // Userinfo (`user:pass@host`) would be stored, echoed and sent as a second
+    // credential beside the key; the key is the only credential accepted.
+    if (url.username || url.password)
+        return false;
+    if (url.protocol === 'https:')
+        return true;
+    return url.protocol === 'http:' && LOOPBACK_HOSTNAMES.has(url.hostname.toLowerCase());
+}
+/**
+ * Whether two base URLs address the same host (hostname + port).
+ *
+ * @param a - First URL.
+ * @param b - Second URL.
+ * @returns True when both parse and share `host`; false otherwise.
+ */
+export function sameDecideHost(a, b) {
+    try {
+        return new URL(a).host.toLowerCase() === new URL(b).host.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Load the stored connection. Synchronous and total: missing, malformed or
+ * incomplete settings return `null` (the decision client then falls back to
+ * heuristics).
+ *
+ * @returns The sealed connection, or `null` when unconfigured.
+ */
+export function loadDecideConnection() {
+    const store = readStoreSync();
+    const baseUrl = store.baseUrl?.trim();
+    const apiKey = store.apiKey?.trim();
+    if (!baseUrl || !apiKey || !isAllowedDecideBaseUrl(baseUrl))
+        return null;
+    const model = store.model?.trim();
+    return new SealedDecideConnection(baseUrl, apiKey, model && isValidDecisionModelName(model) ? model : undefined);
+}
+/**
+ * Describe the stored settings without the key.
+ *
+ * @returns A secret-free summary.
+ */
+export function describeDecideCredentials() {
+    const path = decideCredentialsPath();
+    const store = readStoreSync(path);
+    const sealed = loadDecideConnection();
+    return {
+        configured: sealed !== null,
+        path,
+        ...(store.baseUrl ? { baseUrl: withoutUserinfo(store.baseUrl) } : {}),
+        ...(store.model ? { model: store.model } : {}),
+        ...(store.apiKey ? { keyPreview: maskApiKey(store.apiKey) } : {}),
+        ...(store.updatedAt ? { updatedAt: store.updatedAt } : {}),
+    };
+}
+/** Error thrown by {@link saveDecideCredentials} for invalid input. The message never contains the key. */
+export class DecideCredentialsError extends Error {
+    /** @param message - Secret-free description. */
+    constructor(message) {
+        super(message);
+        this.name = 'DecideCredentialsError';
+    }
+}
+/** Backup directory `withLock` rotates into (see `store/file-utils.ts`). */
+function backupDirFor(path) {
+    return join(dirname(path), '.backups');
+}
+/**
+ * Refuse to write through a symlink: the store file, the `.backups`
+ * directory and every rotated backup of the store must be real files or
+ * absent. `writeFileSync` (used for the backup copy) follows symlinks, so a
+ * planted link could otherwise redirect the key elsewhere.
+ *
+ * @throws {DecideCredentialsError} When any of those paths is a symlink.
+ */
+function assertNoSymlinks(path) {
+    const backupDir = backupDirFor(path);
+    const candidates = [path, backupDir];
+    try {
+        for (const entry of readdirSync(backupDir)) {
+            if (entry.startsWith(`${DECIDE_CREDENTIALS_FILE}.`))
+                candidates.push(join(backupDir, entry));
+        }
+    }
+    catch {
+        /* no backup dir yet */
+    }
+    for (const candidate of candidates) {
+        let isLink = false;
+        try {
+            isLink = lstatSync(candidate).isSymbolicLink();
+        }
+        catch {
+            continue;
+        }
+        if (isLink) {
+            throw new DecideCredentialsError(`refusing to write decision credentials through a symlink: ${candidate}`);
+        }
+    }
+}
+let warnedLooseHome = false;
+/** Warn once on stderr when the CLEO home is group- or world-writable. */
+function warnIfHomeWritableByOthers(path) {
+    if (warnedLooseHome)
+        return;
+    try {
+        const dirMode = statSync(dirname(path)).mode & 0o777;
+        if ((dirMode & 0o022) !== 0) {
+            warnedLooseHome = true;
+            process.stderr.write(`warning: ${dirname(path)} is group- or world-writable (mode ${dirMode.toString(8)}); ` +
+                'other users could tamper with the decision credentials. Run: chmod go-w <dir>\n');
+        }
+    }
+    catch {
+        /* home missing — created owner-only below */
+    }
+}
+/** Reset the once-only loose-home warning. Tests only. @internal */
+export function _resetDecideHomeWarningForTest() {
+    warnedLooseHome = false;
+}
+/** Pre-write checks shared by save and clear. */
+function guardWrite(path) {
+    warnIfHomeWritableByOthers(path);
+    assertNoSymlinks(path);
+}
+/**
+ * Seed the store file (0600, owner-only directory) so `withLock`'s JSON read
+ * never meets an empty placeholder.
+ */
+function ensureStoreFile(path) {
+    if (existsSync(path) && readFileSync(path, 'utf-8').trim())
+        return;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(EMPTY_STORE)}\n`, { encoding: 'utf-8', mode: 0o600 });
+}
+/**
+ * Store the base URL, API key and optional model (0600, locked, atomic).
+ *
+ * @param input - Settings to store; replaces any previous settings.
+ * @returns Secret-free summary of what is now stored.
+ * @throws {DecideCredentialsError} When the URL is not https (or loopback http), the key is
+ *   blank, the model name is invalid, or the store or its backups are symlinks.
+ */
+export async function saveDecideCredentials(input) {
+    const baseUrl = input.baseUrl.trim();
+    const apiKey = input.apiKey.trim();
+    const model = input.model?.trim();
+    if (hasUserinfo(baseUrl)) {
+        throw new DecideCredentialsError('base URL must not contain a username or password (user:pass@host); supply only the URL and the API key');
+    }
+    if (!isAllowedDecideBaseUrl(baseUrl)) {
+        throw new DecideCredentialsError('base URL must be an absolute https:// URL (plain http:// is allowed only for localhost, 127.0.0.1 and ::1)');
+    }
+    if (model && !isValidDecisionModelName(model)) {
+        throw new DecideCredentialsError('model name may contain only letters, digits and . _ : / @ - (1-128 characters)');
+    }
+    if (!apiKey)
+        throw new DecideCredentialsError('API key must not be empty');
+    if (/\s/.test(apiKey))
+        throw new DecideCredentialsError('API key must not contain whitespace');
+    const path = decideCredentialsPath();
+    guardWrite(path);
+    ensureStoreFile(path);
+    await withLock(path, () => ({
+        version: 1,
+        baseUrl,
+        apiKey,
+        model: model || null,
+        updatedAt: new Date().toISOString(),
+    }), { mode: 0o600 });
+    return describeDecideCredentials();
+}
+/**
+ * Remove the stored settings: the store is overwritten with empty settings
+ * and every rotated backup of it (which may hold an old key) is deleted.
+ *
+ * @returns True when settings were present before the call.
+ */
+export async function clearDecideCredentials() {
+    const path = decideCredentialsPath();
+    const before = readStoreSync(path);
+    const hadSettings = Boolean(before.baseUrl || before.apiKey || before.model);
+    guardWrite(path);
+    if (existsSync(path)) {
+        ensureStoreFile(path);
+        await withLock(path, () => EMPTY_STORE, { mode: 0o600 });
+    }
+    purgeBackups(path);
+    return hadSettings;
+}
+/** Delete `<dir>/.backups/<name>.N` copies of the store. */
+function purgeBackups(path) {
+    const backupDir = backupDirFor(path);
+    let entries;
+    try {
+        entries = readdirSync(backupDir);
+    }
+    catch {
+        return;
+    }
+    const prefix = `${DECIDE_CREDENTIALS_FILE}.`;
+    for (const entry of entries) {
+        if (!entry.startsWith(prefix))
+            continue;
+        try {
+            unlinkSync(join(backupDir, entry));
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+//# sourceMappingURL=credentials.js.map

package/dist/decide/credentials.js.map

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

package/dist/decide/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Typed "System One" decisions — provider port, Jev wire adapter, client,
+ * cache, budget and audit.
+ *
+ * @task T12490
+ * @epic T12486
+ */
+export { auditAnswers, createJsonlDecisionAudit, DECISION_AUDIT_FILE, DEFAULT_DECISION_AUDIT_KEEP, DEFAULT_DECISION_AUDIT_MAX_BYTES, type DecisionAuditAnswer, type DecisionAuditEntry, type DecisionAuditRotation, type DecisionAuditSink, type DecisionFallbackReason, type DecisionShadowRecord, } from './audit.js';
+export { type BudgetGrant, createFileTokenBucket, createMemoryTokenBucket, DEFAULT_BUDGET_CAPACITY, DEFAULT_BUDGET_REFILL_PER_MINUTE, DEFAULT_RATE_LIMIT_COOLDOWN_MS, type DecisionBudget, defaultBudgetStatePath, type FileTokenBucketOptions, MAX_RATE_LIMIT_COOLDOWN_MS, type TokenBucketOptions, } from './budget.js';
+export { createDecisionCache, DEFAULT_DECISION_CACHE_SIZE, type DecisionCache, decisionCacheKey, hashCanonical, } from './cache.js';
+export { _resetDecideDefaultsForTest, DEFAULT_DECISION_TIMEOUT_MS, type DecideOptions, type DecisionHeuristic, decide, redactDecisionState, } from './client.js';
+export { clearDecideCredentials, DECIDE_CREDENTIALS_FILE, DecideCredentialsError, type DecideCredentialsInput, type DecideCredentialsSummary, decideCredentialsPath, describeDecideCredentials, isAllowedDecideBaseUrl, loadDecideConnection, maskApiKey, SealedDecideConnection, sameDecideHost, saveDecideCredentials, } from './credentials.js';
+export { createJevProvider, DECISION_MODEL_NAME_PATTERN, fromJevSystemOneResponse, isValidDecisionModelName, JEV_ADAPTER_VERSION, type JevProviderOptions, type JevSystemOneBody, listJevModels, MAX_MODELS_LISTED, MAX_MODELS_RESPONSE_BYTES, parseRetryAfterMs, toJevSystemOneBody, } from './jev-wire.js';
+export { askDecideDebug, clearDecideConfig, configureDecide, DEFAULT_DECIDE_ASK_TIMEOUT_MS, DEFAULT_DECIDE_PROBE_TIMEOUT_MS, type DecideAskInput, type DecideAskResult, type DecideConfigureInput, type DecideConfigureResult, type DecideProbeOptions, type DecideProbeResult, type DecideProviderState, probeDecideProvider, } from './operations.js';
+export { type DecisionProvider, type DecisionProviderConnection, DecisionProviderError, type DecisionProviderErrorKind, type DecisionProviderErrorOptions, } from './provider.js';
+export { type AskSiteDecisionInput, askSiteDecision, type DecisionSiteMode, type DecisionSiteSettings, isDecisionSiteMode, type ResolveDecisionSiteSettingsInput, redactThenClip, resolveDecisionSiteSettings, type SiteDecision, } from './site.js';
+export { type DecideFetch, type DecideFetchInit, decideFetch } from './transport.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/decide/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,EACnB,2BAA2B,EAC3B,gCAAgC,EAChC,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,WAAW,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,gCAAgC,EAChC,8BAA8B,EAC9B,KAAK,cAAc,EACnB,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,0BAA0B,EAC1B,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAC3B,KAAK,aAAa,EAClB,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,MAAM,EACN,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,oBAAoB,EACpB,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,aAAa,EACb,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,6BAA6B,EAC7B,+BAA+B,EAC/B,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,0BAA0B,EAC/B,qBAAqB,EACrB,KAAK,yBAAyB,EAC9B,KAAK,4BAA4B,GAClC,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,oBAAoB,EACzB,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,kBAAkB,EAClB,KAAK,gCAAgC,EACrC,cAAc,EACd,2BAA2B,EAC3B,KAAK,YAAY,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/decide/index.js

@@ -0,0 +1,18 @@
+/**
+ * Typed "System One" decisions — provider port, Jev wire adapter, client,
+ * cache, budget and audit.
+ *
+ * @task T12490
+ * @epic T12486
+ */
+export { auditAnswers, createJsonlDecisionAudit, DECISION_AUDIT_FILE, DEFAULT_DECISION_AUDIT_KEEP, DEFAULT_DECISION_AUDIT_MAX_BYTES, } from './audit.js';
+export { createFileTokenBucket, createMemoryTokenBucket, DEFAULT_BUDGET_CAPACITY, DEFAULT_BUDGET_REFILL_PER_MINUTE, DEFAULT_RATE_LIMIT_COOLDOWN_MS, defaultBudgetStatePath, MAX_RATE_LIMIT_COOLDOWN_MS, } from './budget.js';
+export { createDecisionCache, DEFAULT_DECISION_CACHE_SIZE, decisionCacheKey, hashCanonical, } from './cache.js';
+export { _resetDecideDefaultsForTest, DEFAULT_DECISION_TIMEOUT_MS, decide, redactDecisionState, } from './client.js';
+export { clearDecideCredentials, DECIDE_CREDENTIALS_FILE, DecideCredentialsError, decideCredentialsPath, describeDecideCredentials, isAllowedDecideBaseUrl, loadDecideConnection, maskApiKey, SealedDecideConnection, sameDecideHost, saveDecideCredentials, } from './credentials.js';
+export { createJevProvider, DECISION_MODEL_NAME_PATTERN, fromJevSystemOneResponse, isValidDecisionModelName, JEV_ADAPTER_VERSION, listJevModels, MAX_MODELS_LISTED, MAX_MODELS_RESPONSE_BYTES, parseRetryAfterMs, toJevSystemOneBody, } from './jev-wire.js';
+export { askDecideDebug, clearDecideConfig, configureDecide, DEFAULT_DECIDE_ASK_TIMEOUT_MS, DEFAULT_DECIDE_PROBE_TIMEOUT_MS, probeDecideProvider, } from './operations.js';
+export { DecisionProviderError, } from './provider.js';
+export { askSiteDecision, isDecisionSiteMode, redactThenClip, resolveDecisionSiteSettings, } from './site.js';
+export { decideFetch } from './transport.js';
+//# sourceMappingURL=index.js.map

package/dist/decide/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/decide/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,EACnB,2BAA2B,EAC3B,gCAAgC,GAOjC,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,gCAAgC,EAChC,8BAA8B,EAE9B,sBAAsB,EAEtB,0BAA0B,GAE3B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAE3B,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAG3B,MAAM,EACN,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EAGtB,qBAAqB,EACrB,yBAAyB,EACzB,sBAAsB,EACtB,oBAAoB,EACpB,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EAGnB,aAAa,EACb,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,6BAA6B,EAC7B,+BAA+B,EAQ/B,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAGL,qBAAqB,GAGtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,eAAe,EAGf,kBAAkB,EAElB,cAAc,EACd,2BAA2B,GAE5B,MAAM,WAAW,CAAC;AACnB,OAAO,EAA0C,WAAW,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/decide/jev-wire.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Jev wire adapter — the ONLY module that knows the Jev/"System One" endpoint
+ * paths and wire JSON.
+ *
+ * Maps a provider-neutral {@link DecisionRequest} to a `POST {base}/v1/systemone`
+ * body, maps the response back to a {@link DecisionOutcome}, and validates the
+ * mapped answers with the contract zod schemas. Any service implementing the
+ * Jev wire format (layahost today) is reachable with just a base URL and an
+ * API key.
+ *
+ * Wire notes (from the provider's published OpenAPI document):
+ * - Request: `{ model?, state, questions: { name: { type, instructions, criteria } } }`.
+ *   `model` is sent only when the request names one; the server applies its
+ *   default otherwise. No model identifier is hard-coded here (arch gate 13).
+ * - A `noul` question's wire `criteria` is `{ "true": <description> }`; the
+ *   contract's single criteria string becomes that description, and it also
+ *   serves as the wire `instructions` (the question text) unless the request
+ *   supplies its own instructions.
+ * - Response answers: noul → `{ noul: <P(yes)>, confidence }`; choice →
+ *   `{ choice, probabilities: { option: p }, confidence }`; score →
+ *   `{ score: <expected level>, probabilities: { level: p }, confidence }`.
+ *   Score probabilities are keyed by level text (or, defensively, by 0-based
+ *   index) and re-aligned to the question's `criteria` order.
+ * - Errors: 401, 402 (`insufficient_credits`), 422 (FastAPI validation list),
+ *   429 (with `retry-after`), 5xx. All are thrown as {@link DecisionProviderError}.
+ *
+ * - Model: the provider's OpenAPI marks `SystemOneRequest.model` REQUIRED and
+ *   documents no server-side default for `/v1/systemone` (the `laya-auto`
+ *   default is documented for `/v1/decide` only). The body therefore carries
+ *   `req.model ?? connection.model`; a request with neither is sent without a
+ *   model and the provider may reject it (422 → heuristic fallback).
+ * - `GET /v1/models` → `{ models: [{ name, description?, ... }] }`; used by
+ *   {@link listJevModels} for the reachability probe.
+ *
+ * `/v1/decide` (single question, different body shape) is not used: every
+ * single-question call is a one-question `/v1/systemone` call, so one mapping
+ * covers every request.
+ *
+ * @task T12490
+ * @epic T12486
+ */
+import { type DecisionOutcome, type DecisionQuestion, type DecisionRequest } from '@cleocode/contracts';
+import { type DecisionProvider, type DecisionProviderConnection } from './provider.js';
+import { type DecideFetch } from './transport.js';
+/** Adapter identity + version; part of every cache key so a mapping change invalidates the cache. */
+export declare const JEV_ADAPTER_VERSION = "jev-wire/1";
+/** One question as the Jev wire expects it. */
+interface JevWireQuestion {
+    readonly type: DecisionQuestion['type'];
+    readonly instructions: DecisionQuestion['instructions'];
+    readonly criteria: DecisionQuestion['criteria'] | {
+        readonly true: string;
+    };
+}
+/** The `/v1/systemone` request body. */
+export interface JevSystemOneBody {
+    /** Model identifier; omitted to use the server default. */
+    readonly model?: string;
+    /** The state being judged. */
+    readonly state: DecisionRequest['state'];
+    /** Question name → wire question. */
+    readonly questions: Readonly<Record<string, JevWireQuestion>>;
+}
+/**
+ * Map a contract request to the `/v1/systemone` wire body.
+ *
+ * @param req - Provider-neutral request.
+ * @returns The JSON body to POST.
+ */
+export declare function toJevSystemOneBody(req: DecisionRequest): JevSystemOneBody;
+/**
+ * Map a `/v1/systemone` response body to a contract outcome.
+ *
+ * Every question in `req` must be answered with the matching type, and every
+ * mapped answer must pass {@link decisionAnswerSchema}; otherwise this throws
+ * `DecisionProviderError('invalid_response')`.
+ *
+ * @param req - The request that was sent (needed to align score levels).
+ * @param body - Parsed JSON response body.
+ * @param latencyMs - Measured wall-clock latency of the call.
+ * @returns The outcome, with `source: 'provider'`.
+ */
+export declare function fromJevSystemOneResponse(req: DecisionRequest, body: unknown, latencyMs: number): DecisionOutcome;
+/**
+ * Parse a `retry-after` header (delta seconds or HTTP date) into milliseconds,
+ * capped at {@link MAX_RATE_LIMIT_COOLDOWN_MS}.
+ *
+ * Negative seconds, past dates and anything unparseable are ignored
+ * (`undefined`, so the budget applies its default cool-down). A numeric-looking
+ * value is never re-read as a date: `Date.parse('-5')` is a valid year.
+ *
+ * @param header - Raw header value, or null.
+ * @param now - Current epoch ms (injectable for tests).
+ * @returns Milliseconds to wait (≤ 60 000), or undefined when absent, negative or unparseable.
+ */
+export declare function parseRetryAfterMs(header: string | null, now?: number): number | undefined;
+/** Options for {@link createJevProvider}. */
+export interface JevProviderOptions {
+    /**
+     * Transport; defaults to {@link decideFetch}, which releases every DNS,
+     * socket and TLS handle on abort (the global `fetch` does not). Tests
+     * inject a stub.
+     */
+    readonly fetch?: DecideFetch;
+    /** Monotonic clock in ms; defaults to `performance.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Create a {@link DecisionProvider} speaking the Jev wire format.
+ *
+ * @param connection - Base URL + API key. The key is only ever placed in the
+ *   `Authorization` header.
+ * @param opts - Injectable `fetch` and clock.
+ * @returns A provider whose `decide` throws {@link DecisionProviderError} on any failure.
+ *
+ * @example
+ * ```ts
+ * const provider = createJevProvider({ baseUrl: 'https://decide.example', apiKey });
+ * const outcome = await provider.decide(request, AbortSignal.timeout(300));
+ * ```
+ */
+export declare function createJevProvider(connection: DecisionProviderConnection, opts?: JevProviderOptions): DecisionProvider;
+/**
+ * Allowed shape of a model name: word characters plus `. : / @ -`, 1-128
+ * characters. Anything else (ANSI escapes, control characters, spaces) is
+ * never stored, sent or printed.
+ */
+export declare const DECISION_MODEL_NAME_PATTERN: RegExp;
+/** Byte cap on a `GET /v1/models` response body. */
+export declare const MAX_MODELS_RESPONSE_BYTES: number;
+/** Cap on the number of model names kept from a listing. */
+export declare const MAX_MODELS_LISTED = 500;
+/**
+ * Whether `name` is a safe model identifier (see {@link DECISION_MODEL_NAME_PATTERN}).
+ *
+ * @param name - Candidate model name.
+ * @returns True when it may be stored, sent and printed.
+ */
+export declare function isValidDecisionModelName(name: string): boolean;
+/**
+ * List the models the key may use (`GET {base}/v1/models`).
+ *
+ * The body is capped at {@link MAX_MODELS_RESPONSE_BYTES}; names failing
+ * {@link DECISION_MODEL_NAME_PATTERN} are skipped and at most
+ * {@link MAX_MODELS_LISTED} names are returned.
+ *
+ * @param connection - Base URL + API key (only ever placed in the `Authorization` header).
+ * @param signal - Aborts the request.
+ * @param opts - Injectable `fetch`.
+ * @returns Safe model names in the order the provider lists them.
+ * @throws {DecisionProviderError} On any HTTP, network, abort, size or shape failure.
+ */
+export declare function listJevModels(connection: Pick<DecisionProviderConnection, 'baseUrl' | 'apiKey'>, signal: AbortSignal, opts?: Pick<JevProviderOptions, 'fetch'>): Promise<string[]>;
+export {};
+//# sourceMappingURL=jev-wire.d.ts.map

package/dist/decide/jev-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jev-wire.d.ts","sourceRoot":"","sources":["../../src/decide/jev-wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAErB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,0BAA0B,EAEhC,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,WAAW,EAAe,MAAM,gBAAgB,CAAC;AAQ/D,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD,+CAA+C;AAC/C,UAAU,eAAe;IACvB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC,cAAc,CAAC,CAAC;IACxD,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7E;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IACzC,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;CAC/D;AA6BD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,gBAAgB,CAkBzE;AAoDD;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,MAAM,GAChB,eAAe,CA4BjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,GAAG,GAAE,MAAmB,GACvB,MAAM,GAAG,SAAS,CAapB;AAwBD,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,0BAA0B,EACtC,IAAI,GAAE,kBAAuB,GAC5B,gBAAgB,CAyDlB;AAED;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,QAAuB,CAAC;AAEhE,oDAAoD;AACpD,eAAO,MAAM,yBAAyB,QAAa,CAAC;AAEpD,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D;AAmCD;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,IAAI,CAAC,0BAA0B,EAAE,SAAS,GAAG,QAAQ,CAAC,EAClE,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,IAAI,CAAC,kBAAkB,EAAE,OAAO,CAAM,GAC3C,OAAO,CAAC,MAAM,EAAE,CAAC,CAkCnB"}