@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/lib/facts/stock/call.js

@@ -0,0 +1,281 @@
+/**
+ * One retried, transcripted call — the core the stock connectors (ext-source.ts, ai-check.ts) and
+ * `tools.http.json` (a provider's handler) all share. The retry budget is §A.14.4 /
+ * evaluator-spec §6: 3 attempts, exponential backoff, ~30s total cap, a per-attempt timeout chosen
+ * by the caller.
+ *
+ * ONE attempt loop, two façades: `withRetryBudget` does the fetching, the JSON read and the
+ * transcript, and a per-attempt CLASSIFIER decides what an answer means — "done, here is the value"
+ * or "retry, here is why". `callWithRetryBudget` classifies against a source/model contract (a
+ * contract miss is the unreachable path, never a verdict); `jsonRequest` classifies on the HTTP
+ * status alone and hands the outcome back for the handler to interpret. Keeping the loop single is
+ * the point: retry semantics, the ~30s cap and the frozen transcript must not drift between the
+ * lane the kit runs and the lane a provider's handler runs.
+ */
+import { sha256Hex } from "../../hash.js";
+import { fetchClient, fetchGuarded, parseRetryAfter, RedirectRefused, readCappedBytes, } from "../../http/client.js";
+const SOURCE_ATTEMPTS = 3;
+const BACKOFF_BASE_MS = 1000;
+const TOTAL_BUDGET_MS = 30_000;
+/**
+ * The most of one answer this lane reads. `tools.http.json` fetches URLs a claim answer names, so a
+ * public host can stream without end; a JSON answer a fact is made of is kilobytes, and 10 MiB is
+ * the AI lane's attachment cap — nothing an isolate cannot hold.
+ */
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Never freeze a credential into a transcript — the §A.14.1 record is durable, travels to the engine
+ * and is served on `GET /v1/claims/:claimId`. `authorization` alone is not enough: vendors spell
+ * their key every way (`x-api-key`, `apikey`, `X-RapidAPI-Key`, `Ocp-Apim-Subscription-Key`,
+ * `cf-aig-authorization`, a cookie …), so the rule is by NAME SHAPE, not a list of vendors: any
+ * name ending in `key`, or containing authorization / token / secret / password / credential /
+ * signature, plus the cookies. `idempotency-key` is the one key kept — it is part of the record
+ * (ext-source.ts) and authenticates nothing.
+ */
+const COOKIE_HEADERS = new Set(["cookie", "set-cookie"]);
+const SECRET_HEADER_NAME = /key$|authorization|token|secret|password|credential|signature/i;
+const isSecretHeader = (name) => {
+    const lower = name.toLowerCase();
+    return (lower !== "idempotency-key" && (COOKIE_HEADERS.has(lower) || SECRET_HEADER_NAME.test(lower)));
+};
+export const redactHeaders = (headers) => Object.fromEntries(Object.entries(headers).filter(([k]) => !isSecretHeader(k)));
+/**
+ * The same rule for the URL: many vendors take the key as a query parameter (`?key=`, `?api_key=`,
+ * a signed URL's `sig`). The VALUE of a parameter named like a credential is masked; its name and
+ * the rest of the URL stay byte-for-byte, so the record still says where the call went. Done on the
+ * raw string, never re-serialized through `URLSearchParams` (which would re-encode the rest).
+ */
+const SECRET_PARAM_NAME = /key|token|secret|password|signature|sig|auth|credential/i;
+export function redactUrl(url) {
+    const q = url.indexOf("?");
+    if (q === -1)
+        return url;
+    const hash = url.indexOf("#", q);
+    const query = url.slice(q + 1, hash === -1 ? undefined : hash);
+    const masked = query
+        .split("&")
+        .map((pair) => {
+        const eq = pair.indexOf("=");
+        const name = eq === -1 ? pair : pair.slice(0, eq);
+        let decoded = name;
+        try {
+            decoded = decodeURIComponent(name.replace(/\+/g, " "));
+        }
+        catch {
+            /* a malformed escape — judge the raw name */
+        }
+        return eq !== -1 && SECRET_PARAM_NAME.test(decoded) ? `${name}=[redacted]` : pair;
+    })
+        .join("&");
+    return `${url.slice(0, q + 1)}${masked}${hash === -1 ? "" : url.slice(hash)}`;
+}
+/**
+ * The most of a response body the TRANSCRIPT keeps. The caller still gets the whole parsed body (up
+ * to `MAX_RESPONSE_BYTES`); the transcript freezes into the FactSet and lands in `decisions.facts`,
+ * where a multi-MiB answer breaks D1's row limit AFTER the engine has decided and billed — and the
+ * recovery path rebuilds the same facts and fails the same way. Past the cap the transcript records
+ * the body's size and digest instead: a pure function of the bytes, so a review fold's re-pull
+ * freezes the same thing (the engine's `response.body` is `unknown` — any JSON is valid there).
+ */
+export const MAX_TRANSCRIPT_BODY_BYTES = 64 * 1024;
+/** The stand-in `transcriptBody` freezes past the cap. */
+export const isTruncated = (body) => typeof body === "object" && body !== null && body.truncated === true;
+/** A transcript's `response.body`: `readable` itself, or past the cap the bytes' size + digest. */
+export async function transcriptBody(bytes, readable) {
+    return bytes.byteLength > MAX_TRANSCRIPT_BODY_BYTES
+        ? { truncated: true, bytes: bytes.byteLength, sha256: await sha256Hex(bytes) }
+        : readable;
+}
+/** The answers that mean "later", not "no": a 5xx, a 408 (timeout) or a 429 (rate limited). */
+export const isTransientStatus = (status) => status >= 500 || status === 408 || status === 429;
+/**
+ * A 4xx the endpoint will answer again: anything but 408 (a timeout, retried like one) and 429
+ * (rate limited, the one 4xx that means "later"). 5xx stays the transient path.
+ */
+export const isFinalStatus = (status) => status >= 400 && status < 500 && status !== 408 && status !== 429;
+/**
+ * The shared attempt loop. Everything on the unreachable path — network error, an answer the
+ * classifier refuses — burns an attempt and retries with backoff until the attempts or the budget
+ * are spent, unless the classifier calls the refusal `final` (a 4xx other than 408/429). The
+ * transcript freezes the LAST attempt's request/response, never an auth header.
+ */
+async function withRetryBudget(deps, req, classify) {
+    const started = Date.now();
+    const safeHeaders = redactHeaders(req.headers);
+    let lastResponse = null;
+    let lastStatus = null;
+    let lastBody = null;
+    let lastDetail = "no attempts made";
+    let transient = false;
+    let retryAfterMs = null;
+    let latencyMs;
+    let attempt = 0;
+    let ok = false;
+    let value = null;
+    while (attempt < req.attempts && Date.now() - started < TOTAL_BUDGET_MS) {
+        if (attempt > 0) {
+            // A `Retry-After` the budget cannot honour ends the loop: the step's own retry (minutes
+            // later) is the one that waits it out — never an attempt the endpoint asked us not to make.
+            const wait = Math.max(BACKOFF_BASE_MS * 2 ** (attempt - 1), retryAfterMs ?? 0);
+            if (Date.now() + wait - started >= TOTAL_BUDGET_MS)
+                break;
+            await sleep(wait);
+        }
+        attempt++;
+        const attemptStart = Date.now();
+        let res;
+        try {
+            // A transport rides fetchClient too (one attempt here — this loop owns the retries): the
+            // attempt's deadline aborts it, and the call lands on the `upstream` metric. A fetch walks
+            // its redirects by hand, every hop re-guarded (`fetchGuarded`); a POST sends JSON.
+            res = req.send
+                ? await fetchClient(req.url, {
+                    attempts: 1,
+                    timeoutMs: Math.max(1, Math.min(req.timeoutMs, started + TOTAL_BUDGET_MS - Date.now())),
+                    send: req.send,
+                })
+                : await fetchGuarded(req.url, {
+                    method: req.method,
+                    trace: deps.trace,
+                    timeoutMs: req.timeoutMs,
+                    deadline: started + TOTAL_BUDGET_MS,
+                    ...(req.method === "POST"
+                        ? {
+                            headers: { "content-type": "application/json", ...req.headers },
+                            body: JSON.stringify(req.body ?? null),
+                        }
+                        : { headers: req.headers }),
+                });
+        }
+        catch (err) {
+            if (err instanceof RedirectRefused) {
+                // Where the answer lives is not somewhere we go — the same every attempt, so stop here.
+                lastDetail = err.message;
+                lastResponse = null;
+                lastStatus = null;
+                lastBody = null;
+                transient = false;
+                latencyMs = Date.now() - attemptStart;
+                break;
+            }
+            // No HTTP answer at all: `response: null` in the transcript and a null status say exactly
+            // that. Never classified — there is nothing to classify.
+            lastDetail = `unreachable: ${String(err)}`;
+            lastResponse = null;
+            lastStatus = null;
+            lastBody = null;
+            transient = true;
+            retryAfterMs = null;
+            latencyMs = Date.now() - attemptStart;
+            continue;
+        }
+        const bytes = await readCappedBytes(res, MAX_RESPONSE_BYTES).catch(() => new Uint8Array(0));
+        latencyMs = Date.now() - attemptStart;
+        if (bytes === null) {
+            // Too large to be an answer — and the same every attempt, so stop here, unread.
+            lastDetail = `response body over ${MAX_RESPONSE_BYTES} bytes`;
+            lastResponse = null;
+            lastStatus = null;
+            lastBody = null;
+            transient = false;
+            break;
+        }
+        const raw = new TextDecoder().decode(bytes);
+        let parsed = null;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            /* non-JSON — recorded raw below */
+        }
+        lastStatus = res.status;
+        lastBody = parsed;
+        transient = isTransientStatus(res.status);
+        retryAfterMs = parseRetryAfter(res.headers.get("retry-after")) ?? null;
+        lastResponse = {
+            status: res.status,
+            body: await transcriptBody(bytes, parsed ?? raw.slice(0, 4096)),
+        };
+        const verdict = classify({ status: res.status, ok: res.ok, body: parsed });
+        if (verdict.done) {
+            ok = true;
+            value = verdict.value;
+            break;
+        }
+        lastDetail = verdict.detail;
+        if (verdict.final)
+            break;
+    }
+    return {
+        ok,
+        value,
+        detail: ok ? "" : lastDetail,
+        transient: !ok && transient,
+        retryAfterMs,
+        status: lastStatus,
+        body: lastBody,
+        transcript: {
+            request: { url: redactUrl(req.url), body: req.recordedBody, headers: safeHeaders },
+            response: lastResponse,
+            attempts: attempt,
+            elapsedMs: Date.now() - started,
+            ...(latencyMs === undefined ? {} : { latencyMs }),
+        },
+    };
+}
+/**
+ * The connectors' façade: a POST under the budget, read against a strict contract. A non-2xx, an
+ * unparseable body and a contract MISS are all the unreachable path (§A.14.4: a contract miss is
+ * NEVER a `valid:false`). `transcriptBody` substitutes the recorded request body when the real one
+ * must not be persisted verbatim (base64 image payloads → CID + digest).
+ */
+export async function callWithRetryBudget(deps, url, body, headers, timeoutMs, read, transcriptBody, send) {
+    const { ok, value, detail, transient, retryAfterMs, body: answered, transcript, } = await withRetryBudget(deps, {
+        url,
+        method: "POST",
+        headers,
+        body,
+        recordedBody: transcriptBody === undefined ? body : transcriptBody,
+        timeoutMs,
+        attempts: SOURCE_ATTEMPTS,
+        send,
+    }, (answer) => {
+        if (!answer.ok) {
+            return {
+                done: false,
+                detail: `endpoint returned ${answer.status}`,
+                final: isFinalStatus(answer.status),
+            };
+        }
+        if (answer.body === null || typeof answer.body !== "object") {
+            return { done: false, detail: "response body is not a JSON object" };
+        }
+        const outcome = read(answer.body);
+        return outcome.ok
+            ? { done: true, value: outcome.value }
+            : { done: false, detail: outcome.detail, final: outcome.final };
+    });
+    return { ok, value, detail, transient, retryAfterMs, body: answered, transcript };
+}
+/**
+ * The handler's façade: the same call with NO contract reader — what `tools.http.json` gives a
+ * provider's handler (facts/types.ts `HttpJsonResult`). The difference is only what an answer
+ * MEANS: here every HTTP outcome, 404 and 500 included, comes back as `{ ok, status, body }`
+ * instead of becoming an error fact, because only the handler knows whether a 404 is a failure or
+ * a "no such batch, so false". A 5xx, a 408 or a 429 burns an attempt and retries; any other 4xx
+ * ends the loop on the spot — the same request gets the same answer (a handler that wants one shot
+ * even on a 5xx passes `attempts: 1`). Nothing here throws for an HTTP outcome — a network error on every attempt is
+ * `status: null`, the "no response at all" case.
+ */
+export async function jsonRequest(deps, req) {
+    const { ok, status, body, transcript } = await withRetryBudget(deps, { ...req, recordedBody: req.method === "POST" ? (req.body ?? null) : null }, (answer) => answer.ok
+        ? { done: true, value: null }
+        : {
+            done: false,
+            detail: `endpoint returned ${answer.status}`,
+            final: isFinalStatus(answer.status),
+        });
+    return { ok, status, body, transcript };
+}
+//# sourceMappingURL=call.js.map

package/dist/lib/facts/stock/call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call.js","sourceRoot":"","sources":["../../../../src/lib/facts/stock/call.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EACL,WAAW,EACX,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,GAEhB,MAAM,mBAAmB,CAAC;AAI3B,MAAM,eAAe,GAAG,CAAC,CAAC;AAC1B,MAAM,eAAe,GAAG,IAAI,CAAC;AAC7B,MAAM,eAAe,GAAG,MAAM,CAAC;AAC/B;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEnF;;;;;;;;GAQG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;AACzD,MAAM,kBAAkB,GAAG,gEAAgE,CAAC;AAC5F,MAAM,cAAc,GAAG,CAAC,IAAY,EAAW,EAAE;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,OAAO,CACL,KAAK,KAAK,iBAAiB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAC7F,CAAC;AACJ,CAAC,CAAC;AACF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAA+B,EAA0B,EAAE,CACvF,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAElF;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG,0DAA0D,CAAC;AACrF,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC;IACzB,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACjC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,KAAK;SACjB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,MAAM,IAAI,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,OAAO,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC;YACH,OAAO,GAAG,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,6CAA6C;QAC/C,CAAC;QACD,OAAO,EAAE,KAAK,CAAC,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC;IACpF,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;AAChF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAa,EAA8C,EAAE,CACvF,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAK,IAAgC,CAAC,SAAS,KAAK,IAAI,CAAC;AAEpG,mGAAmG;AACnG,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAiB,EAAE,QAAiB;IACvE,OAAO,KAAK,CAAC,UAAU,GAAG,yBAAyB;QACjD,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC,KAAK,CAAC,EAAE;QAC9E,CAAC,CAAC,QAAQ,CAAC;AACf,CAAC;AAoBD,+FAA+F;AAC/F,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAc,EAAW,EAAE,CAC3D,MAAM,IAAI,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,MAAc,EAAW,EAAE,CACvD,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC;AAyCpE;;;;;GAKG;AACH,KAAK,UAAU,eAAe,CAC5B,IAAiC,EACjC,GAAgB,EAChB,QAAsD;IAEtD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC3B,MAAM,WAAW,GAAG,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,YAAY,GAA2B,IAAI,CAAC;IAChD,IAAI,UAAU,GAAkB,IAAI,CAAC;IACrC,IAAI,QAAQ,GAAY,IAAI,CAAC;IAC7B,IAAI,UAAU,GAAG,kBAAkB,CAAC;IACpC,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,YAAY,GAAkB,IAAI,CAAC;IACvC,IAAI,SAA6B,CAAC;IAClC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,EAAE,GAAG,KAAK,CAAC;IACf,IAAI,KAAK,GAAa,IAAI,CAAC;IAE3B,OAAO,OAAO,GAAG,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,eAAe,EAAE,CAAC;QACxE,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,wFAAwF;YACxF,4FAA4F;YAC5F,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,eAAe,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,YAAY,IAAI,CAAC,CAAC,CAAC;YAC/E,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,OAAO,IAAI,eAAe;gBAAE,MAAM;YAC1D,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;QACD,OAAO,EAAE,CAAC;QAEV,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAChC,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,yFAAyF;YACzF,2FAA2F;YAC3F,mFAAmF;YACnF,GAAG,GAAG,GAAG,CAAC,IAAI;gBACZ,CAAC,CAAC,MAAM,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE;oBACzB,QAAQ,EAAE,CAAC;oBACX,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;oBACvF,IAAI,EAAE,GAAG,CAAC,IAAI;iBACf,CAAC;gBACJ,CAAC,CAAC,MAAM,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE;oBAC1B,MAAM,EAAE,GAAG,CAAC,MAAM;oBAClB,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,SAAS,EAAE,GAAG,CAAC,SAAS;oBACxB,QAAQ,EAAE,OAAO,GAAG,eAAe;oBACnC,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM;wBACvB,CAAC,CAAC;4BACE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE;4BAC/D,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC;yBACvC;wBACH,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;iBAC9B,CAAC,CAAC;QACT,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,eAAe,EAAE,CAAC;gBACnC,wFAAwF;gBACxF,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC;gBACzB,YAAY,GAAG,IAAI,CAAC;gBACpB,UAAU,GAAG,IAAI,CAAC;gBAClB,QAAQ,GAAG,IAAI,CAAC;gBAChB,SAAS,GAAG,KAAK,CAAC;gBAClB,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC;gBACtC,MAAM;YACR,CAAC;YACD,0FAA0F;YAC1F,yDAAyD;YACzD,UAAU,GAAG,gBAAgB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3C,YAAY,GAAG,IAAI,CAAC;YACpB,UAAU,GAAG,IAAI,CAAC;YAClB,QAAQ,GAAG,IAAI,CAAC;YAChB,SAAS,GAAG,IAAI,CAAC;YACjB,YAAY,GAAG,IAAI,CAAC;YACpB,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC;YACtC,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5F,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC;QACtC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,gFAAgF;YAChF,UAAU,GAAG,sBAAsB,kBAAkB,QAAQ,CAAC;YAC9D,YAAY,GAAG,IAAI,CAAC;YACpB,UAAU,GAAG,IAAI,CAAC;YAClB,QAAQ,GAAG,IAAI,CAAC;YAChB,SAAS,GAAG,KAAK,CAAC;YAClB,MAAM;QACR,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,MAAM,GAAY,IAAI,CAAC;QAC3B,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,mCAAmC;QACrC,CAAC;QACD,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC;QACxB,QAAQ,GAAG,MAAM,CAAC;QAClB,SAAS,GAAG,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1C,YAAY,GAAG,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,IAAI,CAAC;QACvE,YAAY,GAAG;YACb,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,IAAI,EAAE,MAAM,cAAc,CAAC,KAAK,EAAE,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;SAChE,CAAC;QAEF,MAAM,OAAO,GAAG,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC3E,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,EAAE,GAAG,IAAI,CAAC;YACV,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;YACtB,MAAM;QACR,CAAC;QACD,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;QAC5B,IAAI,OAAO,CAAC,KAAK;YAAE,MAAM;IAC3B,CAAC;IAED,OAAO;QACL,EAAE;QACF,KAAK;QACL,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU;QAC5B,SAAS,EAAE,CAAC,EAAE,IAAI,SAAS;QAC3B,YAAY;QACZ,MAAM,EAAE,UAAU;QAClB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,OAAO,EAAE,EAAE,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE;YAClF,QAAQ,EAAE,YAAY;YACtB,QAAQ,EAAE,OAAO;YACjB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;YAC/B,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;SAClD;KACF,CAAC;AACJ,CAAC;AAcD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAiC,EACjC,GAAW,EACX,IAAa,EACb,OAA+B,EAC/B,SAAiB,EACjB,IAE4E,EAC5E,cAAwB,EACxB,IAAgB;IAEhB,MAAM,EACJ,EAAE,EACF,KAAK,EACL,MAAM,EACN,SAAS,EACT,YAAY,EACZ,IAAI,EAAE,QAAQ,EACd,UAAU,GACX,GAAG,MAAM,eAAe,CACvB,IAAI,EACJ;QACE,GAAG;QACH,MAAM,EAAE,MAAM;QACd,OAAO;QACP,IAAI;QACJ,YAAY,EAAE,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc;QAClE,SAAS;QACT,QAAQ,EAAE,eAAe;QACzB,IAAI;KACL,EACD,CAAC,MAAM,EAAE,EAAE;QACT,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,MAAM,EAAE,qBAAqB,MAAM,CAAC,MAAM,EAAE;gBAC5C,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC;aACpC,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC5D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,oCAAoC,EAAE,CAAC;QACvE,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,IAA+B,CAAC,CAAC;QAC7D,OAAO,OAAO,CAAC,EAAE;YACf,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE;YACtC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;IACpE,CAAC,CACF,CAAC;IACF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AACpF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAiC,EACjC,GAOC;IAED,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,MAAM,eAAe,CAC5D,IAAI,EACJ,EAAE,GAAG,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAC3E,CAAC,MAAM,EAAE,EAAE,CACT,MAAM,CAAC,EAAE;QACP,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE;QAC7B,CAAC,CAAC;YACE,IAAI,EAAE,KAAK;YACX,MAAM,EAAE,qBAAqB,MAAM,CAAC,MAAM,EAAE;YAC5C,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC;SACpC,CACR,CAAC;IACF,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC1C,CAAC"}

package/dist/lib/facts/stock/capability.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What this oracle's key may sign for an external call — node-safe (no runtime imports), so
+ * `testing/fake-tools.ts` refuses exactly what the real `tools.http` does.
+ */
+/**
+ * The ONE capability the stock lane signs, whatever the rubric declares. Also what
+ * `http.json(url, { ucan: true })` and `http.ucanHeaders()` sign with by default, so a handler
+ * calling a source by hand presents exactly what the stock connector would.
+ */
+export declare const DEFAULT_CAPABILITY: {
+    readonly can: "*";
+    readonly with: "ixo:external-source";
+};
+/**
+ * Refuse to sign an IXO SERVICE capability for an external call: any `ixo:` resource other than
+ * exactly `ixo:external-source` (`ixo:eval-engine`, `ixo:ixo-pay-facilitator`, `ixo:eval-oracle`,
+ * `ixo:oracle/…`, `ixo:matrix-*-bot`, `ixo:*`, …), and any resource carrying whitespace or a
+ * control character. The engine and the facilitator accept a self-signed token rooted at this
+ * oracle's did:web AS this oracle, so such a token handed to a third party is this oracle's
+ * authority handed over. The stock lane never reaches it (it signs `DEFAULT_CAPABILITY` only);
+ * `tools.http` does.
+ *
+ * A PLAIN `Error`, deliberately — not an `AppError`, which the runner rethrows as a retry
+ * (runner.ts `detailForThrow`). A refused capability is deterministic: the runner freezes it as a
+ * `facts.handler-threw` error fact carrying the rubric's `onError`, and the claim is decided.
+ *
+ * Redundant once the engine and the facilitator accept oracle authority only from the oracle
+ * itself (S1c/S4/S10); it stays until then.
+ */
+export declare function assertExternalCapability(capability: {
+    can: string;
+    with: string;
+}): void;
+/**
+ * The audience a call to `url` is signed for: exactly its host's did:web (`:port` percent-encoded).
+ * A token is only ever signed for the host it is sent to.
+ */
+export declare function urlAudience(url: string | URL): string;
+//# sourceMappingURL=capability.d.ts.map

package/dist/lib/facts/stock/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../../../src/lib/facts/stock/capability.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;aAAK,GAAG,EAAE,GAAG;aAAE,IAAI,EAAE,qBAAqB;CAAW,CAAC;AAmBrF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMxF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,MAAM,CAErD"}

package/dist/lib/facts/stock/capability.js

@@ -0,0 +1,59 @@
+/**
+ * What this oracle's key may sign for an external call — node-safe (no runtime imports), so
+ * `testing/fake-tools.ts` refuses exactly what the real `tools.http` does.
+ */
+import { webDidOf } from "../../ixo/web-did.js";
+/**
+ * The ONE capability the stock lane signs, whatever the rubric declares. Also what
+ * `http.json(url, { ucan: true })` and `http.ucanHeaders()` sign with by default, so a handler
+ * calling a source by hand presents exactly what the stock connector would.
+ */
+export const DEFAULT_CAPABILITY = { can: "*", with: "ixo:external-source" };
+// Whitespace or a control character anywhere in a resource: a URL parser strips or skips them
+// (`"\tixo:eval-engine"` parses as `ixo:`), and a counterparty's comparison may too — refused
+// outright rather than guessed at.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters IS the point
+const UNSAFE_CHARS = /[\s\x00-\x1f\x7f]/;
+function isIxoServiceResource(resource) {
+    if (resource === DEFAULT_CAPABILITY.with)
+        return false;
+    if (UNSAFE_CHARS.test(resource))
+        return true;
+    if (resource.toLowerCase().startsWith("ixo:"))
+        return true;
+    try {
+        return new URL(resource).protocol === "ixo:";
+    }
+    catch {
+        return false; // not a URL at all — not an IXO resource either
+    }
+}
+/**
+ * Refuse to sign an IXO SERVICE capability for an external call: any `ixo:` resource other than
+ * exactly `ixo:external-source` (`ixo:eval-engine`, `ixo:ixo-pay-facilitator`, `ixo:eval-oracle`,
+ * `ixo:oracle/…`, `ixo:matrix-*-bot`, `ixo:*`, …), and any resource carrying whitespace or a
+ * control character. The engine and the facilitator accept a self-signed token rooted at this
+ * oracle's did:web AS this oracle, so such a token handed to a third party is this oracle's
+ * authority handed over. The stock lane never reaches it (it signs `DEFAULT_CAPABILITY` only);
+ * `tools.http` does.
+ *
+ * A PLAIN `Error`, deliberately — not an `AppError`, which the runner rethrows as a retry
+ * (runner.ts `detailForThrow`). A refused capability is deterministic: the runner freezes it as a
+ * `facts.handler-threw` error fact carrying the rubric's `onError`, and the claim is decided.
+ *
+ * Redundant once the engine and the facilitator accept oracle authority only from the oracle
+ * itself (S1c/S4/S10); it stays until then.
+ */
+export function assertExternalCapability(capability) {
+    if (isIxoServiceResource(capability.with)) {
+        throw new Error(`Refusing to sign ${JSON.stringify(capability.with)} for an external call: an IXO service capability is this oracle's own authority, never an external source's`);
+    }
+}
+/**
+ * The audience a call to `url` is signed for: exactly its host's did:web (`:port` percent-encoded).
+ * A token is only ever signed for the host it is sent to.
+ */
+export function urlAudience(url) {
+    return webDidOf(new URL(url).host);
+}
+//# sourceMappingURL=capability.js.map

package/dist/lib/facts/stock/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../../src/lib/facts/stock/capability.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,qBAAqB,EAAW,CAAC;AAErF,8FAA8F;AAC9F,8FAA8F;AAC9F,mCAAmC;AACnC,oGAAoG;AACpG,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAEzC,SAAS,oBAAoB,CAAC,QAAgB;IAC5C,IAAI,QAAQ,KAAK,kBAAkB,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACvD,IAAI,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,QAAQ,KAAK,MAAM,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC,CAAC,gDAAgD;IAChE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,wBAAwB,CAAC,UAAyC;IAChF,IAAI,oBAAoB,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,oBAAoB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,6GAA6G,CACjK,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAiB;IAC3C,OAAO,QAAQ,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/dist/lib/facts/stock/ext-source.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The external-source connector (§A.14) — the stock way a rubric's `ext.<name>` gets its value: a
+ * self-signed UCAN invocation minted to the source's did:web audience, the declared `send` payload
+ * (plus the whole claim body) POSTed under the retry budget, the strict §A.14.3 contract read, and
+ * the frozen transcript. Run as the stock `ext` lane (../tools.ts `stockLanes`) for every source in
+ * the work order; a provider's handler may wrap it (`tools.stock()`) or replace it per name.
+ *
+ * `sourceEndpointUrl` / `readSourceContract` are the engine's own (its editor "Test" harness shares
+ * them).
+ *
+ * What the oracle's key signs is ITS DEVELOPER's choice, never the rubric's. The rubric belongs to
+ * the protocol — written by its owner, shared by every oracle serving it — so it may say WHERE to
+ * call (endpoint + audience) and WHAT to send, never what this oracle's key grants: a rubric that
+ * could name the capability could mint itself a token for any service that trusts this oracle's
+ * did:web. So the stock lane signs `DEFAULT_CAPABILITY` only (a declared `capability` is logged
+ * and ignored), signs only for an audience that IS the endpoint's own did:web, and never an IXO
+ * service resource (`assertExternalCapability`). A developer who needs another capability sets it
+ * in their own handler: `tools.http.json(url, { ucan: { capability } })`, signed for that URL's host.
+ */
+import type { Config } from "../../../config.js";
+import type { PulledClaim } from "../../ixo/index.js";
+import type { ExpectedExt } from "../expected.js";
+import type { ExtFact } from "../factset.js";
+import type { ProducerDeps } from "../producer.js";
+/** One external source call (§A.14): the claim, the declared source and its resolved `send` payload. */
+export interface ExtSourceInput {
+    claim: PulledClaim;
+    /** The `<name>` in `ext.<name>` — the work-order key (expected.ts). */
+    name: string;
+    source: ExpectedExt;
+    /** `send` refs resolved against the claim body / ctx (send.ts), literals passed through. */
+    payload: Record<string, unknown>;
+}
+/**
+ * Endpoint policy (§A.14.2): HTTPS everywhere, HTTP only in development. Throws a 400-shaped
+ * AppError — the caller turns it into the unreachable path.
+ */
+export declare function sourceEndpointUrl(config: Config, endpoint: string): URL;
+/**
+ * The strict §A.14.3 response contract. Extra keys are ignored (it's their API); a missing/wrong-typed
+ * declared field is a contract MISS — the unreachable path, never a `valid:false`.
+ */
+export declare function readSourceContract(expect: ExpectedExt["expect"], body: Record<string, unknown>): {
+    ok: boolean;
+    value: boolean | number;
+    reason: string | null;
+    detail: string;
+};
+/** One external source (§A.14): self-signed UCAN, idempotency key `{claimId}:{sourceName}`. */
+export declare function resolveExtSource(input: ExtSourceInput, deps: Pick<ProducerDeps, "config" | "logger" | "trace">): Promise<ExtFact>;
+//# sourceMappingURL=ext-source.d.ts.map

package/dist/lib/facts/stock/ext-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext-source.d.ts","sourceRoot":"","sources":["../../../../src/lib/facts/stock/ext-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQhD,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,CAevE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,EAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAkBjF;AAED,+FAA+F;AAC/F,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC,GACtD,OAAO,CAAC,OAAO,CAAC,CAsJlB"}