@loomwork/llm 0.0.0-stage → 0.1.0

package/dist/reasoning.d.ts

@@ -0,0 +1,154 @@
+import { type TaintedValue } from "@loomwork/classify";
+import type { EffectContext } from "@loomwork/effect-runtime";
+import type { LlmReasoning, LlmReasoningKind, LlmReasoningPart } from "./parts";
+import type { ContentResolver } from "./resolveContent";
+/** The event the capture emits (userspace: the fold ignores it). */
+export declare const LLM_REASONING_CAPTURED = "LLM_REASONING_CAPTURED";
+/**
+ * Write and read view of the sidecar store (structural: a `ContentStore` satisfies it, with no
+ * package dependency). Content-addressed and idempotent by hash, so a crash-recovery rerun that
+ * produces the same bytes stores nothing new.
+ */
+export interface ReasoningStore {
+    put(bytes: Uint8Array): Promise<{
+        readonly __loomContent: string;
+    }>;
+    get(ref: {
+        readonly __loomContent: string;
+    }): Promise<Uint8Array | null>;
+}
+/** Read-only view, for {@link readReasoning}. */
+export type ReasoningReader = Pick<ReasoningStore, "get">;
+export interface LlmReasoningOptions {
+    /** Where readable text is kept. Without one, text is dropped and only signatures are recorded. */
+    store?: ReasoningStore;
+    /** Default: on iff a store is configured. `false` is the explicit opt-out. */
+    capture?: boolean | ((ctx: EffectContext) => boolean);
+    /** Deliver readable reasoning deltas live (D6): through the per-call sink under a runtime pipe, else to `onDelta`. Off by default. */
+    live?: boolean;
+    /**
+     * The configured live sink for reasoning, the analogue of `createLlmEffect`'s text `onDelta`
+     * (a transport such as `ConversationHub.reasoningSink()`). Called only when `live` is on and the
+     * call is streamed, with the increment still WRAPPED as untrusted content
+     * (`llm-reasoning:<stepId>`): the sink unwraps it at its own transport edge, never earlier.
+     * Never journaled; not called on replay.
+     */
+    onDelta?: (delta: TaintedValue<string>, ctx: EffectContext) => void;
+    /** Recorded on the audit event (the provider SPI does not expose its model id). */
+    model?: string;
+    /**
+     * An AUTHORIZING resolver for a reasoning part's `textRef` (the ADR 0120 `ContentResolver` seam,
+     * called with `origin: "reasoning"` and the call's executionId / stepId / principal). It returns the
+     * readable text's bytes, or `null` for absent / not yours; a throw is an outage and fails the call.
+     * Default: {@link reasoningStoreResolver} over `store`, which serves only blobs sealed to the
+     * calling execution.
+     */
+    resolve?: ContentResolver;
+}
+/** One part of an `LLM_REASONING_CAPTURED` payload: references and digests, never text. */
+export interface CapturedReasoningPart {
+    kind: LlmReasoningKind;
+    ref?: string;
+    digest?: string;
+    size?: number;
+}
+export interface LlmReasoningCaptured {
+    stepId: string;
+    attempt: number;
+    provider: string;
+    model?: string;
+    parts: CapturedReasoningPart[];
+}
+/** The bytes stored for `text`: sealed to `executionId`. */
+export declare function sealReasoningText(text: string, executionId: string): Uint8Array;
+/** The text bytes inside a sealed blob, or `null` when it is not sealed to `executionId` (or is not a sealed blob). */
+export declare function openReasoningText(bytes: Uint8Array, executionId: string): Uint8Array | null;
+/** The default reasoning resolver: reads the sidecar and serves a blob only to the execution it is sealed to. */
+export declare function reasoningStoreResolver(store: ReasoningReader): ContentResolver;
+/** SHA-256 hex of the canonical UTF-8 bytes of `text`. */
+export declare function reasoningDigest(bytes: Uint8Array): string;
+/** Whether capture is on for this call: an explicit choice wins, else on iff a store is configured. */
+export declare function captureOn(options: LlmReasoningOptions | undefined, ctx: EffectContext): boolean;
+/**
+ * Reduce a response's reasoning to its recorded parts and (when anything was captured) emit the
+ * audit event. Pure with respect to the response; the only side effects are the store `put`s and
+ * the one `ctx.emit`. A failing `put` throws: audit evidence that cannot be kept fails the step
+ * (and retries it) instead of silently recording less than was configured.
+ */
+export declare function captureReasoning(reasoning: readonly LlmReasoning[], options: LlmReasoningOptions | undefined, ctx: EffectContext): Promise<LlmReasoningPart[]>;
+/**
+ * ADR 0133 D2 - the text-free form of anything reasoning-shaped: a recorded part loses any `text`
+ * it carries; a raw {@link LlmReasoning} becomes a part with kind, provider and signature, flagged
+ * `omitted` when it had readable text (the text was not kept, so it cannot be continued). For a
+ * layer that sits between a provider and a journal (a decision, a cache) and has no sidecar:
+ * readable reasoning must reach a sidecar via `createLlmEffect`, or nowhere.
+ */
+export declare function textFreeReasoning(reasoning: readonly (LlmReasoning | LlmReasoningPart)[]): LlmReasoningPart[];
+/** The minimal log view `readReasoning` needs: an `EventStore` satisfies it. */
+export interface ReasoningLogReader {
+    read(executionId: string): Promise<readonly {
+        eventType: string;
+        payload: unknown;
+    }[]>;
+}
+/**
+ * `redacted`: the vendor withheld this block (opaque data in `signature`, never any text), so there is
+ * nothing to verify or erase; it is NOT `ok` (which would read as "readable and checked").
+ */
+export type ReasoningPartStatus = "ok" | "redacted" | "erased" | "digest-mismatch";
+export interface ReasoningPartRead {
+    kind: LlmReasoningKind;
+    provider: string;
+    status: ReasoningPartStatus;
+    /** Present only when `status` is `"ok"` and the part had readable text; wrapped as untrusted. */
+    text?: TaintedValue<string>;
+}
+export interface ReasoningAttemptRead {
+    attempt: number;
+    provider: string;
+    model?: string;
+    /** This attempt's value is the one the step recorded (the last capture before `STEP_COMPLETED`). */
+    recorded: boolean;
+    parts: ReasoningPartRead[];
+}
+export interface ReasoningStepRead {
+    stepId: string;
+    /** In log order; superseded attempts are kept. */
+    attempts: ReasoningAttemptRead[];
+    /** The attempt whose value the step recorded, when the step completed. */
+    recordedAttempt?: number;
+}
+/** Which steps to read and how much: every bound is applied BEFORE a blob is fetched. */
+export interface ReasoningQuery {
+    executionId: string;
+    /** Exactly this step. */
+    stepId?: string;
+    /** Only steps whose id starts with this (a conversation turn's steps), filtered before any `store.get`. */
+    stepPrefix?: string;
+}
+/** Bounds for {@link readReasoningBounded}. Reading stops at the first one reached. */
+export interface ReasoningReadLimits {
+    /** Most parts read (each part with a stored text costs one `store.get`). */
+    maxParts?: number;
+    /** Most readable-text bytes read in total. */
+    maxBytes?: number;
+}
+/**
+ * Join `LLM_REASONING_CAPTURED` events to their blobs. Each part is checked against its digest:
+ * an absent blob reports `erased`, an altered one `digest-mismatch`. Readable text comes back
+ * wrapped as untrusted content (origin `llm-reasoning:<stepId>`), so it cannot be put in a prompt
+ * instruction position. Grouped by step with every attempt; the attempt whose value the step
+ * recorded is the last capture before that step's `STEP_COMPLETED`.
+ */
+export declare function readReasoning(log: ReasoningLogReader, store: ReasoningReader, query: ReasoningQuery): Promise<ReasoningStepRead[]>;
+/**
+ * {@link readReasoning} for an endpoint: the same join, but bounded. `stepId` / `stepPrefix` select
+ * events before any blob is fetched, and `limits` cap the parts and the readable bytes read; when a
+ * cap is reached the first parts (in log order) come back with `truncated: true` and nothing past
+ * the cap is fetched. A part whose declared text size would cross `maxBytes` is neither read nor included.
+ */
+export declare function readReasoningBounded(log: ReasoningLogReader, store: ReasoningReader, query: ReasoningQuery, limits?: ReasoningReadLimits): Promise<{
+    steps: ReasoningStepRead[];
+    truncated: boolean;
+}>;
+//# sourceMappingURL=reasoning.d.ts.map

package/dist/reasoning.d.ts.map

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

package/dist/reasoning.js

@@ -0,0 +1,256 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLM_REASONING_CAPTURED = void 0;
+exports.sealReasoningText = sealReasoningText;
+exports.openReasoningText = openReasoningText;
+exports.reasoningStoreResolver = reasoningStoreResolver;
+exports.reasoningDigest = reasoningDigest;
+exports.captureOn = captureOn;
+exports.captureReasoning = captureReasoning;
+exports.textFreeReasoning = textFreeReasoning;
+exports.readReasoning = readReasoning;
+exports.readReasoningBounded = readReasoningBounded;
+const node_crypto_1 = require("node:crypto");
+const classify_1 = require("@loomwork/classify");
+// ── ADR 0133 — model reasoning as audit evidence ─────────────────────────────
+//
+// The provider returns reasoning next to its answer. `captureReasoning` runs BEFORE `parse`
+// and reduces it to its recorded form: kind, provider, signature and a reference to the readable
+// text in a sidecar store. The text never reaches a step value; the audit fact is a userspace
+// event naming references and digests, never text and never signatures. `readReasoning` joins
+// those events back to their blobs for an auditor.
+/** The event the capture emits (userspace: the fold ignores it). */
+exports.LLM_REASONING_CAPTURED = "LLM_REASONING_CAPTURED";
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+// ── the execution seal (ADR 0133 D5, "who may resolve a ref") ─────────────────
+//
+// The sidecar is content-addressed and, like every ContentStore, has no tenancy of its own: whoever
+// can name an address can read it, and a reasoning part's `textRef` rides in a transcript a caller
+// may have assembled. So the stored bytes are SEALED to the execution that captured them (a tiny
+// JSON envelope naming it), and the default resolver serves a blob only to that execution. A forged
+// or copied ref to another execution's blob resolves to `null` (not yours), which the drop rule
+// treats as a hole. The part's `digest` and the audit event's `digest`/`size` stay those of the
+// readable text itself.
+/** The bytes stored for `text`: sealed to `executionId`. */
+function sealReasoningText(text, executionId) {
+    return enc.encode(JSON.stringify({ e: executionId, t: text }));
+}
+/** The text bytes inside a sealed blob, or `null` when it is not sealed to `executionId` (or is not a sealed blob). */
+function openReasoningText(bytes, executionId) {
+    try {
+        const v = JSON.parse(dec.decode(bytes));
+        if (v === null || typeof v !== "object" || v.e !== executionId || typeof v.t !== "string") {
+            return null;
+        }
+        return enc.encode(v.t);
+    }
+    catch {
+        return null;
+    }
+}
+/** The default reasoning resolver: reads the sidecar and serves a blob only to the execution it is sealed to. */
+function reasoningStoreResolver(store) {
+    return async (ref, ctx) => {
+        const bytes = await store.get({ __loomContent: ref.address });
+        return bytes === null ? null : openReasoningText(bytes, ctx.executionId);
+    };
+}
+/** SHA-256 hex of the canonical UTF-8 bytes of `text`. */
+function reasoningDigest(bytes) {
+    return (0, node_crypto_1.createHash)("sha256").update(bytes).digest("hex");
+}
+/** Whether capture is on for this call: an explicit choice wins, else on iff a store is configured. */
+function captureOn(options, ctx) {
+    if (options === undefined || options.store === undefined)
+        return false;
+    const c = options.capture;
+    return c === undefined ? true : typeof c === "function" ? c(ctx) : c;
+}
+/**
+ * Reduce a response's reasoning to its recorded parts and (when anything was captured) emit the
+ * audit event. Pure with respect to the response; the only side effects are the store `put`s and
+ * the one `ctx.emit`. A failing `put` throws: audit evidence that cannot be kept fails the step
+ * (and retries it) instead of silently recording less than was configured.
+ */
+async function captureReasoning(reasoning, options, ctx) {
+    const store = captureOn(options, ctx) ? options?.store : undefined;
+    const parts = [];
+    const audit = [];
+    for (const r of reasoning) {
+        const part = {
+            type: "reasoning",
+            kind: r.kind,
+            provider: r.provider,
+            ...(r.signature !== undefined && { signature: r.signature }),
+        };
+        const text = r.text ?? "";
+        if (text !== "") {
+            if (store !== undefined) {
+                const bytes = enc.encode(text);
+                const ref = await store.put(sealReasoningText(text, ctx.executionId));
+                part.textRef = { address: ref.__loomContent, size: bytes.byteLength };
+                part.digest = reasoningDigest(bytes);
+                audit.push({
+                    kind: r.kind,
+                    ref: ref.__loomContent,
+                    digest: part.digest,
+                    size: bytes.byteLength,
+                });
+            }
+            else {
+                // Readable text existed and was not kept: the part cannot be reproduced for continuation.
+                part.omitted = true;
+            }
+        }
+        else if (store !== undefined) {
+            audit.push({ kind: r.kind });
+        }
+        parts.push(part);
+    }
+    if (store !== undefined && audit.length > 0) {
+        const payload = {
+            stepId: ctx.stepId,
+            attempt: ctx.attempt,
+            provider: reasoning[0]?.provider ?? "",
+            ...(options?.model !== undefined && { model: options.model }),
+            parts: audit,
+        };
+        ctx.emit(exports.LLM_REASONING_CAPTURED, payload);
+    }
+    return parts;
+}
+/**
+ * ADR 0133 D2 - the text-free form of anything reasoning-shaped: a recorded part loses any `text`
+ * it carries; a raw {@link LlmReasoning} becomes a part with kind, provider and signature, flagged
+ * `omitted` when it had readable text (the text was not kept, so it cannot be continued). For a
+ * layer that sits between a provider and a journal (a decision, a cache) and has no sidecar:
+ * readable reasoning must reach a sidecar via `createLlmEffect`, or nowhere.
+ */
+function textFreeReasoning(reasoning) {
+    return reasoning.map((r) => {
+        if (r.type === "reasoning") {
+            const { text: _text, ...recorded } = r;
+            return recorded;
+        }
+        const raw = r;
+        return {
+            type: "reasoning",
+            kind: raw.kind,
+            provider: raw.provider,
+            ...(raw.signature !== undefined && { signature: raw.signature }),
+            ...((raw.text ?? "") !== "" && { omitted: true }),
+        };
+    });
+}
+/**
+ * Join `LLM_REASONING_CAPTURED` events to their blobs. Each part is checked against its digest:
+ * an absent blob reports `erased`, an altered one `digest-mismatch`. Readable text comes back
+ * wrapped as untrusted content (origin `llm-reasoning:<stepId>`), so it cannot be put in a prompt
+ * instruction position. Grouped by step with every attempt; the attempt whose value the step
+ * recorded is the last capture before that step's `STEP_COMPLETED`.
+ */
+async function readReasoning(log, store, query) {
+    return (await readReasoningBounded(log, store, query)).steps;
+}
+/**
+ * {@link readReasoning} for an endpoint: the same join, but bounded. `stepId` / `stepPrefix` select
+ * events before any blob is fetched, and `limits` cap the parts and the readable bytes read; when a
+ * cap is reached the first parts (in log order) come back with `truncated: true` and nothing past
+ * the cap is fetched. A part whose declared text size would cross `maxBytes` is neither read nor included.
+ */
+async function readReasoningBounded(log, store, query, limits = {}) {
+    const maxParts = limits.maxParts ?? Number.POSITIVE_INFINITY;
+    const maxBytes = limits.maxBytes ?? Number.POSITIVE_INFINITY;
+    const events = await log.read(query.executionId);
+    const steps = new Map();
+    const latest = new Map();
+    let parts = 0;
+    let bytes = 0;
+    let truncated = false;
+    for (const ev of events) {
+        if (ev.eventType === exports.LLM_REASONING_CAPTURED) {
+            if (truncated)
+                continue;
+            const p = asCaptured(ev.payload);
+            if (p === undefined ||
+                (query.stepId !== undefined && p.stepId !== query.stepId) ||
+                (query.stepPrefix !== undefined && !p.stepId.startsWith(query.stepPrefix))) {
+                continue;
+            }
+            const attempt = {
+                attempt: p.attempt,
+                provider: p.provider,
+                ...(p.model !== undefined && { model: p.model }),
+                recorded: false,
+                parts: [],
+            };
+            for (const part of p.parts) {
+                if (parts >= maxParts) {
+                    truncated = true;
+                    break;
+                }
+                // The event's own `size` (the text's bytes) gates the fetch, so nothing past the cap is read.
+                const size = part.ref !== undefined ? (part.size ?? 0) : 0;
+                if (bytes + size > maxBytes) {
+                    truncated = true;
+                    break;
+                }
+                parts += 1;
+                bytes += size;
+                attempt.parts.push(await readPart(store, part, p.provider, p.stepId, query.executionId));
+            }
+            if (attempt.parts.length > 0 || !truncated) {
+                let step = steps.get(p.stepId);
+                if (step === undefined) {
+                    step = { stepId: p.stepId, attempts: [] };
+                    steps.set(p.stepId, step);
+                }
+                step.attempts.push(attempt);
+                latest.set(p.stepId, attempt);
+            }
+        }
+        else if (ev.eventType === "STEP_COMPLETED") {
+            const id = ev.payload?.stepId;
+            const attempt = typeof id === "string" ? latest.get(id) : undefined;
+            if (attempt !== undefined && typeof id === "string") {
+                attempt.recorded = true;
+                const step = steps.get(id);
+                if (step !== undefined)
+                    step.recordedAttempt = attempt.attempt;
+            }
+        }
+    }
+    return { steps: [...steps.values()], truncated };
+}
+function asCaptured(payload) {
+    const p = payload;
+    if (p === null ||
+        typeof p !== "object" ||
+        typeof p.stepId !== "string" ||
+        typeof p.attempt !== "number" ||
+        typeof p.provider !== "string" ||
+        !Array.isArray(p.parts)) {
+        return undefined;
+    }
+    return p;
+}
+async function readPart(store, part, provider, stepId, executionId) {
+    const base = { kind: part.kind, provider };
+    if (part.kind === "redacted")
+        return { ...base, status: "redacted" };
+    if (part.ref === undefined)
+        return { ...base, status: "ok" };
+    const stored = await store.get({ __loomContent: part.ref });
+    if (stored === null)
+        return { ...base, status: "erased" };
+    // A blob not sealed to this execution is not what this execution captured.
+    const bytes = openReasoningText(stored, executionId);
+    if (bytes === null)
+        return { ...base, status: "digest-mismatch" };
+    if (part.digest === undefined || reasoningDigest(bytes) !== part.digest) {
+        return { ...base, status: "digest-mismatch" };
+    }
+    return { ...base, status: "ok", text: (0, classify_1.tainted)(dec.decode(bytes), `llm-reasoning:${stepId}`) };
+}
+//# sourceMappingURL=reasoning.js.map

package/dist/reasoning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning.js","sourceRoot":"","sources":["../src/reasoning.ts"],"names":[],"mappings":";;;AAuFA,8CAEC;AAGD,8CAUC;AAGD,wDAKC;AAGD,0CAEC;AAGD,8BAIC;AAQD,4CAgDC;AASD,8CAiBC;AAgED,sCAMC;AAQD,oDAmEC;AA7VD,6CAAyC;AACzC,iDAAgE;AAKhE,gFAAgF;AAChF,EAAE;AACF,4FAA4F;AAC5F,iGAAiG;AACjG,8FAA8F;AAC9F,8FAA8F;AAC9F,mDAAmD;AAEnD,oEAAoE;AACvD,QAAA,sBAAsB,GAAG,wBAAwB,CAAC;AA0D/D,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC;AAC9B,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC;AAE9B,iFAAiF;AACjF,EAAE;AACF,oGAAoG;AACpG,mGAAmG;AACnG,iGAAiG;AACjG,oGAAoG;AACpG,gGAAgG;AAChG,gGAAgG;AAChG,wBAAwB;AAExB,4DAA4D;AAC5D,SAAgB,iBAAiB,CAAC,IAAY,EAAE,WAAmB;IACjE,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,uHAAuH;AACvH,SAAgB,iBAAiB,CAAC,KAAiB,EAAE,WAAmB;IACtE,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAwC,CAAC;QAC/E,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,KAAK,WAAW,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC1F,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,iHAAiH;AACjH,SAAgB,sBAAsB,CAAC,KAAsB;IAC3D,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE,aAAa,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9D,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;IAC3E,CAAC,CAAC;AACJ,CAAC;AAED,0DAA0D;AAC1D,SAAgB,eAAe,CAAC,KAAiB;IAC/C,OAAO,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,uGAAuG;AACvG,SAAgB,SAAS,CAAC,OAAwC,EAAE,GAAkB;IACpF,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACvE,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAC1B,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,gBAAgB,CACpC,SAAkC,EAClC,OAAwC,EACxC,GAAkB;IAElB,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,MAAM,KAAK,GAAuB,EAAE,CAAC;IACrC,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAqB;YAC7B,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;SAC7D,CAAC;QACF,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;QAC1B,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YAChB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC/B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;gBACtE,IAAI,CAAC,OAAO,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;gBACtE,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;gBACrC,KAAK,CAAC,IAAI,CAAC;oBACT,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,GAAG,EAAE,GAAG,CAAC,aAAa;oBACtB,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,IAAI,EAAE,KAAK,CAAC,UAAU;iBACvB,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,0FAA0F;gBAC1F,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACtB,CAAC;QACH,CAAC;aAAM,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,OAAO,GAAyB;YACpC,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,IAAI,EAAE;YACtC,GAAG,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAC7D,KAAK,EAAE,KAAK;SACb,CAAC;QACF,GAAG,CAAC,IAAI,CAAC,8BAAsB,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAC/B,SAAuD;IAEvD,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAoB,EAAE;QAC3C,IAAK,CAAuB,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAClD,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE,GAAG,CAAqB,CAAC;YAC3D,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,GAAG,GAAG,CAAiB,CAAC;QAC9B,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,GAAG,CAAC,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;YAChE,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAa,EAAE,CAAC;SAC3D,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAyDD;;;;;;GAMG;AACI,KAAK,UAAU,aAAa,CACjC,GAAuB,EACvB,KAAsB,EACtB,KAAqB;IAErB,OAAO,CAAC,MAAM,oBAAoB,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AAC/D,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,oBAAoB,CACxC,GAAuB,EACvB,KAAsB,EACtB,KAAqB,EACrB,SAA8B,EAAE;IAEhC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,iBAAiB,CAAC;IAC7D,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,iBAAiB,CAAC;IAC7D,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;IACnD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAgC,CAAC;IACvD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;QACxB,IAAI,EAAE,CAAC,SAAS,KAAK,8BAAsB,EAAE,CAAC;YAC5C,IAAI,SAAS;gBAAE,SAAS;YACxB,MAAM,CAAC,GAAG,UAAU,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;YACjC,IACE,CAAC,KAAK,SAAS;gBACf,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC;gBACzD,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,EAC1E,CAAC;gBACD,SAAS;YACX,CAAC;YACD,MAAM,OAAO,GAAyB;gBACpC,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;gBAChD,QAAQ,EAAE,KAAK;gBACf,KAAK,EAAE,EAAE;aACV,CAAC;YACF,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;gBAC3B,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;oBACtB,SAAS,GAAG,IAAI,CAAC;oBACjB,MAAM;gBACR,CAAC;gBACD,8FAA8F;gBAC9F,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC3D,IAAI,KAAK,GAAG,IAAI,GAAG,QAAQ,EAAE,CAAC;oBAC5B,SAAS,GAAG,IAAI,CAAC;oBACjB,MAAM;gBACR,CAAC;gBACD,KAAK,IAAI,CAAC,CAAC;gBACX,KAAK,IAAI,IAAI,CAAC;gBACd,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;YAC3F,CAAC;YACD,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;gBAC3C,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;gBAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;oBACvB,IAAI,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;oBAC1C,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBAC5B,CAAC;gBACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC5B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;aAAM,IAAI,EAAE,CAAC,SAAS,KAAK,gBAAgB,EAAE,CAAC;YAC7C,MAAM,EAAE,GAAI,EAAE,CAAC,OAAuC,EAAE,MAAM,CAAC;YAC/D,MAAM,OAAO,GAAG,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACpE,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;gBACpD,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;gBACxB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC3B,IAAI,IAAI,KAAK,SAAS;oBAAE,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;YACjE,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC;AACnD,CAAC;AAED,SAAS,UAAU,CAAC,OAAgB;IAClC,MAAM,CAAC,GAAG,OAA+C,CAAC;IAC1D,IACE,CAAC,KAAK,IAAI;QACV,OAAO,CAAC,KAAK,QAAQ;QACrB,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAC5B,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;QAC7B,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ;QAC9B,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EACvB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,CAAyB,CAAC;AACnC,CAAC;AAED,KAAK,UAAU,QAAQ,CACrB,KAAsB,EACtB,IAA2B,EAC3B,QAAgB,EAChB,MAAc,EACd,WAAmB;IAEnB,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC3C,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IACrE,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5D,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC1D,2EAA2E;IAC3E,MAAM,KAAK,GAAG,iBAAiB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAClE,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,eAAe,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;QACxE,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAA,kBAAO,EAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,iBAAiB,MAAM,EAAE,CAAC,EAAE,CAAC;AAChG,CAAC"}

package/dist/resolveContent.d.ts

@@ -0,0 +1,74 @@
+import type { PrincipalChain } from "@loomwork/effect-runtime";
+import type { LlmContentRef, LlmMediaPart } from "./parts";
+import type { LlmRequest } from "./types";
+/**
+ * What a resolver is told about the call it is serving — enough for a store to AUTHORIZE the read.
+ *
+ * **A resolver MUST authorize the ref.** The ContentStore is content-addressed and has no tenancy:
+ * whoever can name an address can read its bytes. `executionId` / `principal` identify who is asking;
+ * a store shared across tenants must check them (typically against the execution that wrote the blob)
+ * rather than serving any address it is handed. `origin: "tool"` marks a ref that came out of a tool
+ * result (a tool's output is data from outside the prompt author), `"app"` one the application put in
+ * a message itself. A ref named by an untrusted party never reaches a resolver: the guard refuses it.
+ */
+export interface ContentResolveContext {
+    readonly executionId: string;
+    /**
+     * The workflow of the asking execution (ADR 0143). A store that seals per subject maps
+     * `(executionId, workflowId)` to the erasure subject with the SAME `subjectOf` the event store runs, and a
+     * `subjectOf` keyed by workflow needs it: pass it on as `store.get(ref, { executionId, workflowId })`.
+     * Absent only on a hand-built context (a caller that did not know it).
+     */
+    readonly workflowId?: string;
+    readonly stepId?: string;
+    readonly principal?: PrincipalChain;
+    readonly origin: "tool" | "app" | "reasoning";
+    /** Bytes still available under the request's budget; return fewer, or `null`/throw, rather than exceed it. */
+    readonly maxBytes: number;
+    /** Aborts when the call is cancelled or the request's byte budget is already spent. */
+    readonly signal?: AbortSignal;
+}
+/** Fetch a blob by address. `null` means erased/absent (never throw for absence). */
+export type ContentResolver = (ref: LlmContentRef, context: ContentResolveContext) => Promise<Uint8Array | null>;
+/** A `ref` source reached a provider (or the effect) with no resolver able to turn it into bytes. */
+export declare class UnresolvedContentError extends Error {
+    readonly address: string;
+    constructor(address: string, reason: string);
+}
+/** Default cap on the TOTAL resolved media bytes in one request (providers cap well below this). */
+export declare const MAX_RESOLVED_BYTES: number;
+/**
+ * Replace every `ref` source with inline base64 `data`, fetching each distinct address once.
+ * Returns the request unchanged (same object) when it has no refs.
+ *
+ * The byte budget is a RUNNING one: fetches start at most {@link FETCH_CONCURRENCY} at a time, each is
+ * told what is left, and the first to push the total over `maxBytes` aborts the rest (their signal
+ * fires and no queued fetch starts). A blob whose actual size differs from the size its ref declares
+ * is refused. Overshoot is bounded, not zero: at most {@link FETCH_CONCURRENCY} fetches are in flight when
+ * the budget is spent, so a resolver that ignores `maxBytes` can hold at most that many blobs before the
+ * abort lands. Resolvers SHOULD honour `maxBytes` (return `null` or throw rather than read more).
+ * A failure — absent, over budget, size mismatch, a throwing resolver — for a ref that
+ * sits inside a `tool_result` does NOT fail the call: the part becomes a text error and the
+ * `tool_result` is marked `isError`, so the model sees that the tool's media is unavailable and can
+ * carry on (the agent loop feeds a tool failure back the same way). The same failure for a ref the
+ * application put in a message itself throws {@link UnresolvedContentError}: the app asked for that
+ * content, so continuing without it would answer a different question.
+ */
+export declare function resolveRequestContent(request: LlmRequest, resolver: ContentResolver | undefined, options: {
+    maxBytes?: number;
+    signal?: AbortSignal;
+    /** REQUIRED: who is asking. A resolver cannot authorize a read it cannot attribute. */
+    context: Pick<ContentResolveContext, "executionId" | "workflowId" | "stepId" | "principal">;
+    /**
+     * ADR 0133 D5 - how an assistant `reasoning` part's `textRef` is read. Defaults to `resolver`.
+     * A request with no reasoning parts never calls it.
+     */
+    reasoningResolver?: ContentResolver;
+}): Promise<LlmRequest>;
+/**
+ * The base64 bytes of a media part for a provider mapper. A provider only ever sees
+ * `data` sources (the effect resolves refs first); a `ref` here means it was called
+ * directly with an unresolved request, which fails closed rather than sending nothing.
+ */
+export declare function inlineData(p: LlmMediaPart): string;
+//# sourceMappingURL=resolveContent.d.ts.map

package/dist/resolveContent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveContent.d.ts","sourceRoot":"","sources":["../src/resolveContent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAEV,aAAa,EACb,YAAY,EAGb,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,SAAS,CAAC;AAWtD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,WAAW,CAAC;IAC9C,8GAA8G;IAC9G,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,qFAAqF;AACrF,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;AAEhC,qGAAqG;AACrG,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBACb,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C;AAED,oGAAoG;AACpG,eAAO,MAAM,kBAAkB,QAAmB,CAAC;AAwCnD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,OAAO,EAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,uFAAuF;IACvF,OAAO,EAAE,IAAI,CAAC,qBAAqB,EAAE,aAAa,GAAG,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC,CAAC;IAC5F;;;OAGG;IACH,iBAAiB,CAAC,EAAE,eAAe,CAAC;CACrC,GACA,OAAO,CAAC,UAAU,CAAC,CAOrB;AA8QD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAMlD"}