@loomwork/middleware 0.0.0-stage → 0.1.1

package/dist/streamTokenBudget.d.ts

@@ -0,0 +1,58 @@
+import type { EffectContext } from "@loomwork/effect-runtime";
+import type { Budget } from "./metering";
+/**
+ * Estimate output tokens from generated text. The default is the usual ~4
+ * characters-per-token heuristic — deliberately crude and deliberately visible.
+ * Pass a real tokenizer when the budget is tight enough for the difference to
+ * matter.
+ */
+export type TokenEstimator = (text: string) => number;
+export declare const estimateTokensByChars: TokenEstimator;
+export interface StreamTokenBudgetOptions {
+    /** Swap in a real tokenizer. Default {@link estimateTokensByChars}. */
+    estimate?: TokenEstimator;
+    /**
+     * Check at most every N deltas.
+     *
+     * The DEFAULT estimator is O(1) — `text.length / 4`, and `.length` is a field
+     * read — so with it this knob buys almost nothing. It exists for a real
+     * tokenizer, which scans the text and is therefore O(text) per call: at every
+     * delta that would be quadratic over a generation, and every 8 still divides
+     * the same quadratic by 8 rather than removing it. If you pass a scanning
+     * estimator, prefer one that can score an increment.
+     *
+     * (An earlier version of this comment credited `checkEvery` with bounding a
+     * cost that lived in `collectStream`, not here — the caller rebuilt the whole
+     * text per delta before this guard was ever consulted, so the knob could not
+     * have helped. That is fixed; the note stays because the reasoning it corrects
+     * is easy to repeat.)
+     */
+    checkEvery?: number;
+}
+/**
+ * Build the `collectStream` guard that enforces a token {@link Budget} mid-flight.
+ *
+ * ```ts
+ * createLlmEffect({
+ *   provider,
+ *   stream: true,
+ *   buildRequest,
+ *   guard: streamTokenBudget({ maxTokens: 50_000 }),
+ * });
+ * ```
+ *
+ * On breach it emits `QUOTA_EXCEEDED` — the same durable fact
+ * `meteringMiddleware` writes, so an over-budget run looks the same to analytics
+ * whichever gate caught it — and throws `QuotaExceededError`, which propagates
+ * out of the `for await` and releases the HTTP call through K8.1's abort path.
+ *
+ * What is already spent comes from `ctx.resources` (K3's running totals from the
+ * durable fold), so the ceiling covers the execution rather than this one call.
+ * With no `ctx.resources` wired, only this generation's own output counts —
+ * degraded, but never wrong in the dangerous direction.
+ */
+export declare function streamTokenBudget(budget: Budget, options?: StreamTokenBudgetOptions): (ctx: EffectContext) => (progress: {
+    text: string;
+    deltas: number;
+}) => void;
+//# sourceMappingURL=streamTokenBudget.d.ts.map

package/dist/streamTokenBudget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamTokenBudget.d.ts","sourceRoot":"","sources":["../src/streamTokenBudget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAuBzC;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAEtD,eAAO,MAAM,qBAAqB,EAAE,cAAqD,CAAC;AAE1F,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,wBAA6B,GACrC,CAAC,GAAG,EAAE,aAAa,KAAK,CAAC,QAAQ,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAgB9E"}

package/dist/streamTokenBudget.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateTokensByChars = void 0;
+exports.streamTokenBudget = streamTokenBudget;
+const metering_1 = require("./metering");
+const estimateTokensByChars = (text) => Math.ceil(text.length / 4);
+exports.estimateTokensByChars = estimateTokensByChars;
+/**
+ * Build the `collectStream` guard that enforces a token {@link Budget} mid-flight.
+ *
+ * ```ts
+ * createLlmEffect({
+ *   provider,
+ *   stream: true,
+ *   buildRequest,
+ *   guard: streamTokenBudget({ maxTokens: 50_000 }),
+ * });
+ * ```
+ *
+ * On breach it emits `QUOTA_EXCEEDED` — the same durable fact
+ * `meteringMiddleware` writes, so an over-budget run looks the same to analytics
+ * whichever gate caught it — and throws `QuotaExceededError`, which propagates
+ * out of the `for await` and releases the HTTP call through K8.1's abort path.
+ *
+ * What is already spent comes from `ctx.resources` (K3's running totals from the
+ * durable fold), so the ceiling covers the execution rather than this one call.
+ * With no `ctx.resources` wired, only this generation's own output counts —
+ * degraded, but never wrong in the dangerous direction.
+ */
+function streamTokenBudget(budget, options = {}) {
+    const estimate = options.estimate ?? exports.estimateTokensByChars;
+    const checkEvery = Math.max(1, options.checkEvery ?? 8);
+    return (ctx) => (progress) => {
+        if (budget.maxTokens === undefined)
+            return;
+        if (progress.deltas % checkEvery !== 0)
+            return;
+        const alreadySpent = ctx.resources?.tokens ?? 0;
+        const projected = alreadySpent + estimate(progress.text);
+        if (projected < budget.maxTokens)
+            return;
+        const reason = `maxTokens ${budget.maxTokens} exceeded mid-stream (~${projected} estimated, ${alreadySpent} already metered)`;
+        ctx.emit("QUOTA_EXCEEDED", { stepId: ctx.stepId, reason });
+        throw new metering_1.QuotaExceededError(reason);
+    };
+}
+//# sourceMappingURL=streamTokenBudget.js.map

package/dist/streamTokenBudget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamTokenBudget.js","sourceRoot":"","sources":["../src/streamTokenBudget.ts"],"names":[],"mappings":";;;AA8EA,8CAmBC;AA/FD,yCAAgD;AA8BzC,MAAM,qBAAqB,GAAmB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAA7E,QAAA,qBAAqB,yBAAwD;AAwB1F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,iBAAiB,CAC/B,MAAc,EACd,UAAoC,EAAE;IAEtC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,6BAAqB,CAAC;IAC3D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC;IAExD,OAAO,CAAC,GAAkB,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE;QAC1C,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;YAAE,OAAO;QAC3C,IAAI,QAAQ,CAAC,MAAM,GAAG,UAAU,KAAK,CAAC;YAAE,OAAO;QAE/C,MAAM,YAAY,GAAG,GAAG,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC;QAChD,MAAM,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzD,IAAI,SAAS,GAAG,MAAM,CAAC,SAAS;YAAE,OAAO;QAEzC,MAAM,MAAM,GAAG,aAAa,MAAM,CAAC,SAAS,0BAA0B,SAAS,eAAe,YAAY,mBAAmB,CAAC;QAC9H,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC3D,MAAM,IAAI,6BAAkB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@loomwork/middleware",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Reference effect middleware for Loom — cross-cutting concerns (retries, and later logging/idempotency/tracing) around effect execution, replay-safe and statically ordered",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@loomwork/classify": "^0.1.1",
+    "@loomwork/core": "^0.1.1",
+    "@loomwork/effect-runtime": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8",
+    "zod": "^3.23.8"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chhetrisushil/loom.git",
+    "directory": "packages/middleware"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "!src/**/__fixtures__",
+    "!src/**/__snapshots__",
+    "!src/**/__golden__",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck:tests": "tsc -p tsconfig.test.json"
+  }
 }

package/src/claimCheck.ts

@@ -0,0 +1,410 @@
+import { nestedTaintOrigin, tainted } from "@loomwork/classify";
+import type { EffectMiddleware } from "@loomwork/effect-runtime";
+
+// ── ADR 0051 D3 / ADR 0054 — claim-check: the reference IS the recorded value ─
+//
+// Effect results over an inline cap are stored in a content-addressed store and
+// the log records `{ ref, size, digest }` AS the step output. Deliberately NOT
+// ADR 0046 externalization: there is no resolving decorator on this path — the
+// fold never touches the content store, replay never resolves, and erasing an
+// unpinned blob is invisible to replay. Orchestration logic may branch only on
+// the recorded envelope (in practice: the digest — the tool's declared
+// deterministic projection). Reaching through the ref from flow control
+// reintroduces nondeterminism and is lintable (CC-5, tools/*).
+
+/**
+ * ADR 0143 - the execution a content operation is for (structural twin of `@loomwork/plugin-content`'s
+ * `ContentAccess`, ContentStore SPI 1.5.0). The middleware passes the running effect's execution on every
+ * `put`, so a store that seals per subject knows whose key to use; a plain store ignores it.
+ */
+export interface ClaimCheckAccess {
+  readonly executionId: string;
+  readonly workflowId: string;
+}
+
+/** Write-side view of the content store (structural — no plugin dependency). */
+export interface ClaimCheckStore {
+  /** Content-addressed, idempotent by hash — the `ContentStore.put` contract (ADR 0046). */
+  put(bytes: Uint8Array, access?: ClaimCheckAccess): Promise<{ __loomContent: string }>;
+  /** OPTIONAL (ST-1, ADR 0059) — streaming ingestion; required only for stream-typed results. */
+  putStream?(
+    stream: AsyncIterable<Uint8Array>,
+    access?: ClaimCheckAccess
+  ): Promise<{ __loomContent: string }>;
+}
+
+/** Read-side view, for {@link resolveClaimCheck} OUTSIDE the determinism boundary. */
+export interface ClaimCheckReader {
+  get(ref: { __loomContent: string }, access?: ClaimCheckAccess): Promise<Uint8Array | null>;
+  /**
+   * OPTIONAL (TS-10, ADR 0062) — batched get, positionally aligned, null per
+   * absent entry. A `ContentStore` with `getMany` satisfies this structurally.
+   */
+  getMany?(
+    refs: readonly { __loomContent: string }[],
+    access?: ClaimCheckAccess
+  ): Promise<(Uint8Array | null)[]>;
+}
+
+/** What STEP_COMPLETED records in place of an over-cap effect result. */
+export interface ClaimCheckEnvelope {
+  readonly __loomClaimCheck: true;
+  readonly ref: { readonly __loomContent: string };
+  /** Byte length of the offloaded payload. */
+  readonly size: number;
+  /** The tool's declared deterministic projection of the result (CC-2), if any. */
+  readonly digest?: unknown;
+  /**
+   * How the offloaded bytes decode. Absent = JSON (the classic offload path);
+   * stream-typed results record their declared codec ("bytes" default) —
+   * resolve those with {@link resolveClaimCheckBytes}, not JSON parsing.
+   */
+  readonly codec?: string;
+  /**
+   * ADR 0140 - `true`: the offloaded bytes are the ONLY copy of a value the log once held (the opt-in
+   * agent claim-check), so the content sweep treats the ref as LOAD-BEARING: kept while any live log,
+   * archive segment or snapshot cites it, freed only when that history is erased or discarded. Absent
+   * (the classic ADR 0054 telemetry offload): the ref is TTL-reclaimable (ADR 0055 D4).
+   */
+  readonly retain?: true;
+}
+
+// ── ST-2 (ADR 0059) — stream-typed tool results ───────────────────────────────
+//
+// A tool whose result is too large to hold in memory returns
+// `streamResult(stream, { digest })` instead of the payload: the middleware
+// streams it into the content store INSIDE the effect (transient side of the
+// determinism boundary) and the recorded value is still the small envelope.
+// The digest MUST come from the tool (computed while producing) — the bytes
+// are consumed by the upload, so no post-hoc projection is possible.
+
+export interface StreamedResult {
+  readonly __loomStreamResult: true;
+  readonly stream: AsyncIterable<Uint8Array>;
+  /** The declared deterministic projection (CC-2). Pure w.r.t. the streamed content. */
+  readonly digest?: unknown;
+  /** Recorded on the envelope; default "bytes". */
+  readonly codec?: string;
+}
+
+/** Wrap a byte stream as a tool result; Node `Readable`s satisfy the iterable directly. */
+export function streamResult(
+  stream: AsyncIterable<Uint8Array>,
+  opts: { digest?: unknown; codec?: string } = {}
+): StreamedResult {
+  return {
+    __loomStreamResult: true,
+    stream,
+    ...(opts.digest !== undefined && { digest: opts.digest }),
+    ...(opts.codec !== undefined && { codec: opts.codec }),
+  };
+}
+
+export function isStreamResult(value: unknown): value is StreamedResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __loomStreamResult?: unknown }).__loomStreamResult === true &&
+    typeof (value as { stream?: unknown }).stream === "object"
+  );
+}
+
+export function isClaimCheck(value: unknown): value is ClaimCheckEnvelope {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __loomClaimCheck?: unknown }).__loomClaimCheck === true &&
+    typeof (value as { ref?: { __loomContent?: unknown } }).ref?.__loomContent === "string"
+  );
+}
+
+/** CC-3 — offload observability: what, where, how big. */
+export interface ClaimCheckInfo {
+  toolId?: string;
+  stepId: string;
+  executionId: string;
+  workflowId: string;
+  size: number;
+  contentAddress: string;
+}
+
+export interface ClaimCheckOptions {
+  store: ClaimCheckStore;
+  /**
+   * Inline cap in bytes for the JSON-encoded effect result; results at or under
+   * the cap are recorded inline, untouched. Default 16 KiB.
+   */
+  inlineCapBytes?: number;
+  /**
+   * CC-2 — `toolId → digest` declarations. A digest is the tool's DETERMINISTIC
+   * projection of its result: the one part of an offloaded payload that
+   * orchestration may branch on, recorded inline in the envelope. MUST be a pure
+   * function of the result. Tools without a declared digest record `{ ref, size }`
+   * only — their orchestration can branch on nothing but existence.
+   */
+  digests?: Readonly<Record<string, (result: unknown) => unknown>>;
+  /**
+   * The projection used for an offloaded result whose tool has NO entry in {@link digests}
+   * (a per-tool digest always wins). Same contract as a digest: PURE w.r.t. the result, because it is
+   * recorded inline in the envelope. Unset (the default) keeps the classic behaviour: such a tool
+   * records `{ ref, size }` only. {@link previewDigest} is a ready-made one.
+   */
+  defaultDigest?: (result: unknown, toolId: string | undefined) => unknown;
+  /** CC-3 — called after each offload (metrics/log-budget regression tracking). */
+  onOffload?: (info: ClaimCheckInfo) => void;
+  /**
+   * ADR 0140 - mark the envelope `retain: true` (see {@link ClaimCheckEnvelope.retain}): the offloaded
+   * blob is audit evidence the content sweep must not TTL-reclaim. A function decides per tool id. Default
+   * unset: the classic reclaimable telemetry offload.
+   */
+  retain?: boolean | ((toolId: string | undefined) => boolean);
+  /**
+   * ADR 0140 - results this returns `true` for pass through UNTOUCHED, never offloaded (e.g. a media
+   * result, whose parts the loop renders itself). Runs before the cap.
+   */
+  passThrough?: (result: unknown, toolId: string | undefined) => boolean;
+  /**
+   * ADR 0140 - treat a result that already LOOKS like an envelope as DATA, not as a ref this middleware
+   * made: it is force-offloaded like any other value, so the log never records a tool-forged
+   * `{ __loomClaimCheck, ref }` the sweep, the resolvers or the model would trust. Default unset: an
+   * existing envelope passes through (stacked wiring, never double-wrapped).
+   */
+  envelopesAreData?: boolean;
+}
+
+/**
+ * CC-1 — claim-check middleware on the ADR 0006 seam. Runs only when the effect
+ * actually executes (replayed/completed steps short-circuit upstream), so replay
+ * determinism is automatic: the envelope is the recorded value. Crash-recovery
+ * re-runs re-offload the same bytes to the same content address (`put` is
+ * idempotent by hash), reproducing an identical envelope.
+ *
+ * Results that JSON cannot encode (circular, undefined) pass through untouched —
+ * offload is impossible for what the journal could not record anyway.
+ */
+export function claimCheckMiddleware(options: ClaimCheckOptions): EffectMiddleware {
+  const cap = options.inlineCapBytes ?? 16 * 1024;
+  const encoder = new TextEncoder();
+  return async (ctx, _input, next): Promise<unknown> => {
+    const result = await next();
+    const access: ClaimCheckAccess = { executionId: ctx.executionId, workflowId: ctx.workflowId };
+    if (options.passThrough?.(result, ctx.toolId) === true) return result;
+    // already an envelope (stacked wiring) — never double-wrap; unless envelopes are DATA (ADR 0140 M7)
+    const forged = options.envelopesAreData === true && isClaimCheck(result);
+    if (!forged && isClaimCheck(result)) return result;
+    const retain =
+      typeof options.retain === "function" ? options.retain(ctx.toolId) : options.retain === true;
+
+    // ST-2 — stream-typed result: ALWAYS offloads (a stream is a declared-big
+    // payload), never buffered by the middleware (a counting wrapper is the only
+    // thing between the tool and the store).
+    if (isStreamResult(result)) {
+      if (options.store.putStream === undefined) {
+        throw new TypeError(
+          `claim-check: tool "${ctx.toolId ?? ctx.stepId}" returned a streamed result but the content store does not implement putStream() (ST-1, ADR 0059)`
+        );
+      }
+      let size = 0;
+      const source = result.stream;
+      const counted = (async function* () {
+        for await (const chunk of source) {
+          size += chunk.byteLength;
+          yield chunk;
+        }
+      })();
+      let streamedRef: { __loomContent: string };
+      try {
+        streamedRef = await options.store.putStream(counted, access);
+      } finally {
+        // W-audit leak fix: if putStream threw mid-consumption, `counted` is
+        // suspended at a yield and nobody would ever finalize it — resuming it
+        // with a return completion propagates through its for-await to the
+        // SOURCE iterator's return(), closing whatever the tool handed us
+        // (file handle, socket). A no-op when the stream was fully consumed.
+        await counted.return(undefined).then(
+          () => {},
+          () => {} // the offload is already failing; source cleanup errors don't mask it
+        );
+      }
+      const envelope: ClaimCheckEnvelope = {
+        __loomClaimCheck: true,
+        ref: { __loomContent: streamedRef.__loomContent },
+        size,
+        codec: result.codec ?? "bytes",
+        ...(result.digest !== undefined && { digest: result.digest }),
+        ...(retain && { retain: true as const }),
+      };
+      options.onOffload?.({
+        ...(ctx.toolId !== undefined && { toolId: ctx.toolId }),
+        stepId: ctx.stepId,
+        executionId: ctx.executionId,
+        workflowId: ctx.workflowId,
+        size,
+        contentAddress: streamedRef.__loomContent,
+      });
+      return envelope;
+    }
+
+    let json: string | undefined;
+    try {
+      json = JSON.stringify(result);
+    } catch {
+      return result;
+    }
+    if (json === undefined) return result;
+    const bytes = encoder.encode(json);
+    // ADR 0140 D11: under `envelopesAreData` a lookalike envelope NESTED anywhere in the result is data
+    // too: the whole result is force-offloaded, so the log never records a tool-authored
+    // `{ __loomClaimCheck, ref, retain }` the sweep or erasure could mistake for one this middleware wrote.
+    const nestedForged = options.envelopesAreData === true && json.includes('"__loomClaimCheck"');
+    if (!forged && !nestedForged && bytes.byteLength <= cap) return result;
+
+    const ref = await options.store.put(bytes, access);
+    const declared = ctx.toolId === undefined ? undefined : options.digests?.[ctx.toolId];
+    const projected =
+      declared !== undefined ? declared(result) : options.defaultDigest?.(result, ctx.toolId);
+    const envelope: ClaimCheckEnvelope = {
+      __loomClaimCheck: true,
+      ref: { __loomContent: ref.__loomContent },
+      size: bytes.byteLength,
+      ...(projected !== undefined && { digest: projected }),
+      ...(retain && { retain: true as const }),
+    };
+    options.onOffload?.({
+      ...(ctx.toolId !== undefined && { toolId: ctx.toolId }),
+      stepId: ctx.stepId,
+      executionId: ctx.executionId,
+      workflowId: ctx.workflowId,
+      size: bytes.byteLength,
+      contentAddress: ref.__loomContent,
+    });
+    // ADR 0085 / 0140 - an offloaded result that carried untrusted content (a tainted top level OR a
+    // nested marker) must not launder it into a clean-looking envelope + digest: the envelope itself is
+    // tainted, so the loop fences it and records the taint (the sweep still finds the inner envelope).
+    let origin: string | undefined;
+    if (json.includes("__loomTainted")) {
+      // Scan the SERIALIZED form (what the log and the prompt hold). A marker that is only text still
+      // taints (fail closed).
+      try {
+        origin = nestedTaintOrigin(JSON.parse(json)) ?? "unknown:taint-marker-in-text";
+      } catch {
+        origin = "unknown:taint-marker-in-text";
+      }
+    }
+    return origin === undefined ? envelope : tainted(envelope, origin);
+  };
+}
+
+/** What {@link previewDigest} records: the head of the result's JSON text. */
+export interface PreviewDigest {
+  /** The first `maxChars` UTF-16 code units of `JSON.stringify(result)`, never ending mid-surrogate-pair. */
+  readonly preview: string;
+  /** `true` when the result's JSON continues past the preview (the tail is NOT shown); absent when the preview is the whole text. */
+  readonly truncated?: true;
+}
+
+/**
+ * A ready-made `defaultDigest` (CC-2): the first `maxChars` (default 256) characters of the result's
+ * JSON text, so the model sees what an offloaded tool result BEGAN with instead of a bare hash. Pure
+ * and deterministic (a function of the result only). It is NOT a summary: it is a head, and it can cut
+ * a JSON string anywhere.
+ *
+ * Untrusted content is never previewed: a result carrying an ADR 0085 taint marker ANYWHERE (a nested
+ * `{ __loomTainted }` wrapper, such as an A2A reply's `content`) yields no digest at all, because a
+ * digest rides into the model's prompt as ordinary text and would launder the taint. A result JSON cannot
+ * encode yields none either.
+ */
+export function previewDigest(
+  maxChars = 256
+): (result: unknown, toolId?: string) => PreviewDigest | undefined {
+  return (result) => {
+    let json: string | undefined;
+    try {
+      json = JSON.stringify(result);
+    } catch {
+      return undefined;
+    }
+    if (json === undefined || json.includes('"__loomTainted"')) return undefined;
+    let end = Math.min(maxChars, json.length);
+    // Never end on a lone high surrogate (it would not round-trip through UTF-8).
+    if (end < json.length && end > 0) {
+      const last = json.charCodeAt(end - 1);
+      if (last >= 0xd800 && last <= 0xdbff) end--;
+    }
+    return { preview: json.slice(0, end), ...(end < json.length && { truncated: true as const }) };
+  };
+}
+
+/**
+ * CC-4 — resolve an envelope back to its payload, for use OUTSIDE the
+ * determinism boundary (rendering evidence in a UI, exporting a report).
+ * Returns `null` when the bytes were erased/never stored — the store's
+ * null-on-absence contract, surfaced as-is so callers decide loudness.
+ * Flow control must NOT branch on the resolved payload (CC-5 lint).
+ */
+export async function resolveClaimCheck<T = unknown>(
+  reader: ClaimCheckReader,
+  envelope: ClaimCheckEnvelope,
+  access?: ClaimCheckAccess
+): Promise<T | null> {
+  if (envelope.codec !== undefined && envelope.codec !== "json") {
+    throw new TypeError(
+      `resolveClaimCheck: envelope codec is "${envelope.codec}", not JSON — use resolveClaimCheckBytes for stream-offloaded content`
+    );
+  }
+  const bytes = await reader.get(envelope.ref, access);
+  if (bytes === null) return null;
+  return JSON.parse(new TextDecoder().decode(bytes)) as T;
+}
+
+/**
+ * CC-4 for stream-offloaded content (ST-2): the raw bytes, `null` on absence.
+ * Same boundary rule as {@link resolveClaimCheck}: OUTSIDE the determinism
+ * boundary only.
+ */
+export async function resolveClaimCheckBytes(
+  reader: ClaimCheckReader,
+  envelope: ClaimCheckEnvelope,
+  access?: ClaimCheckAccess
+): Promise<Uint8Array | null> {
+  return reader.get(envelope.ref, access);
+}
+
+/**
+ * TS-10 (ADR 0062) — the batch twin of {@link resolveClaimCheck}, for
+ * interactive read paths (frozen-snapshot serving: a completed run's envelopes,
+ * one human waiting). One `getMany` round-trip when the reader supports it
+ * (coalesced parallel `get`s otherwise), deduped by content address; results
+ * positionally aligned with `envelopes`, `null` per erased/absent entry.
+ * Same boundary rule: OUTSIDE the determinism boundary only.
+ */
+export async function resolveClaimChecks<T = unknown>(
+  reader: ClaimCheckReader,
+  envelopes: readonly ClaimCheckEnvelope[],
+  access?: ClaimCheckAccess
+): Promise<(T | null)[]> {
+  for (const envelope of envelopes) {
+    if (envelope.codec !== undefined && envelope.codec !== "json") {
+      throw new TypeError(
+        `resolveClaimChecks: envelope codec is "${envelope.codec}", not JSON — use resolveClaimCheckBytes for stream-offloaded content`
+      );
+    }
+  }
+  const distinct = new Map<string, { __loomContent: string }>();
+  for (const e of envelopes) {
+    if (!distinct.has(e.ref.__loomContent)) distinct.set(e.ref.__loomContent, e.ref);
+  }
+  const refs = [...distinct.values()];
+  const fetched =
+    reader.getMany !== undefined
+      ? await reader.getMany(refs, access)
+      : await Promise.all(refs.map((r) => reader.get(r, access)));
+  const byAddress = new Map<string, Uint8Array | null>();
+  refs.forEach((r, i) => byAddress.set(r.__loomContent, fetched[i] ?? null));
+  const decoder = new TextDecoder();
+  return envelopes.map((e) => {
+    const bytes = byAddress.get(e.ref.__loomContent) ?? null;
+    // Decode per-occurrence so callers never alias one parsed object.
+    return bytes === null ? null : (JSON.parse(decoder.decode(bytes)) as T);
+  });
+}

package/src/index.ts

@@ -0,0 +1,79 @@
+export { effectTimingMiddleware } from "./profile";
+export type { EffectProfile, EffectProfiler } from "./profile";
+export { retryMiddleware, type RetryOptions } from "./retry";
+export {
+  claimCheckMiddleware,
+  isClaimCheck,
+  isStreamResult,
+  previewDigest,
+  resolveClaimCheck,
+  resolveClaimCheckBytes,
+  resolveClaimChecks,
+  streamResult,
+  type ClaimCheckEnvelope,
+  type ClaimCheckInfo,
+  type ClaimCheckOptions,
+  type ClaimCheckAccess,
+  type ClaimCheckReader,
+  type ClaimCheckStore,
+  type PreviewDigest,
+  type StreamedResult,
+} from "./claimCheck";
+export {
+  meteringMiddleware,
+  llmUsageTokens,
+  QuotaExceededError,
+  type Budget,
+  type MeterInfo,
+  type MeteringOptions,
+  type Pricing,
+  type ResourceDelta,
+} from "./metering";
+export {
+  redactionMiddleware,
+  redactOutputFrom,
+  secretOutputPathsByStep,
+  secretRef,
+  isSecretRef,
+  InMemorySecretResolver,
+  type SecretRef,
+  type SecretResolver,
+  type RedactionOptions,
+} from "./redaction";
+export {
+  nestedBudgetMiddleware,
+  BudgetLedger,
+  type BudgetScope,
+  type NestedBudgetOptions,
+  type ScopeSpend,
+} from "./nestedBudget";
+export {
+  safetyMiddleware,
+  SafetyViolationError,
+  denyPatterns,
+  piiValidator,
+  schemaValidator,
+  killSwitch,
+  type SafetyPhase,
+  type SafetyCheckInfo,
+  type SafetyVerdict,
+  type SafetyValidator,
+  type SafetyOptions,
+  type SchemaLike,
+} from "./safety";
+export { estimateTokensByChars, streamTokenBudget } from "./streamTokenBudget";
+export type { StreamTokenBudgetOptions, TokenEstimator } from "./streamTokenBudget";
+export {
+  rateLimitMiddleware,
+  RateLimitExceededError,
+  type RateLimitOptions,
+  type RateLimitScope,
+} from "./rateLimit";
+export {
+  killSwitchMiddleware,
+  InMemoryKillSwitch,
+  KillSwitchEngagedError,
+  type KillScope,
+  type KillSwitchRegistry,
+  type KillVerdict,
+} from "./killSwitchRegistry";