@loomwork/classify 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@loomwork/classify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Data-handling vocabulary for Loom — the sensitive()/secret()/internal() confidentiality markers + a schema walker, so a field is classified ONCE at its schema and every mechanism (crypto, redaction, egress) derives its wiring from that; plus the integrity axis (tainted()/unwrapTainted()), which attaches provenance to a VALUE at ingress because trustworthiness is not a property a schema can know. Kernel stays ignorant of both (G3).",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/esm/index.js",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "node": "./dist/index.js",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chhetrisushil/loom.git",
+    "directory": "packages/classify"
+  },
+  "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 && rm -rf dist/esm && tsc -p tsconfig.esm.json",
+    "build:esm": "rm -rf dist/esm && tsc -p tsconfig.esm.json",
+    "dev": "tsc --build --watch",
+    "test": "vitest run",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck:tests": "tsc -p tsconfig.test.json"
+  }
 }

package/src/classify.ts

@@ -0,0 +1,175 @@
+import type { z } from "zod";
+
+// ── K10-R1 — the data-protection classification taxonomy ──────────────────────
+//
+// A field's sensitivity is authored ONCE, at its schema, instead of hand-wired as
+// dot-paths at every store/middleware seam. Three *handling* classes, each named for
+// the downstream mechanism that acts on it — so a marker tells you what will happen,
+// not just "this is secret-ish":
+//
+//   • "secret"    — credential material that MUST NOT be persisted at all. Substituted
+//                   out before the value reaches the log (K10-R2 secretRef / K10.3 redaction).
+//   • "sensitive" — personal/confidential data, persisted only encrypted-at-rest and
+//                   crypto-shreddable (K10.2), and scrubbed from external egress (K10-R6).
+//   • "internal"  — persisted in the clear but scrubbed from EXTERNAL egress
+//                   (telemetry / agent-surface / CLI, K10-R6); never crosses the trust boundary.
+//
+// The kernel stays ignorant of these names (G3 — the mechanism lives below in the crypto
+// plugin / middleware; the policy *vocabulary* lives here, above the kernel). A field with
+// no marker is unclassified and handled by nothing — omitting the marker is a true no-op.
+
+/** The three data-protection handling classes, ordered most-restrictive first. */
+export type DataClass = "secret" | "sensitive" | "internal";
+
+/** Rank for "the strictest class wins" merges (secret > sensitive > internal). */
+const RANK: Record<DataClass, number> = { secret: 3, sensitive: 2, internal: 1 };
+
+// A schema instance → its class. A WeakMap (not a mutated property) keeps the marker
+// non-invasive: the Zod schema is returned byte-identical, its validation untouched, and
+// a schema that is GC'd drops its entry. Keyed by the exact instance the author passed,
+// which is the same instance a walker meets in `.shape`, so lookups line up.
+const registry = new WeakMap<object, DataClass>();
+
+/**
+ * Tag a schema with a {@link DataClass}. Returns the SAME schema (validation unchanged) so
+ * it drops into a `z.object({ … })` shape transparently. Prefer the {@link secret} /
+ * {@link sensitive} / {@link internal} sugar; use this directly only for a computed class.
+ */
+export function classify<T extends z.ZodTypeAny>(schema: T, dataClass: DataClass): T {
+  registry.set(schema, dataClass);
+  return schema;
+}
+
+/** Mark a field `"secret"` — never persisted; substituted before it reaches the log. */
+export const secret = <T extends z.ZodTypeAny>(schema: T): T => classify(schema, "secret");
+/** Mark a field `"sensitive"` — encrypted-at-rest, crypto-shreddable, scrubbed from egress. */
+export const sensitive = <T extends z.ZodTypeAny>(schema: T): T => classify(schema, "sensitive");
+/** Mark a field `"internal"` — persisted in the clear but never egressed externally. */
+export const internal = <T extends z.ZodTypeAny>(schema: T): T => classify(schema, "internal");
+
+/** The class a schema was tagged with, or `undefined` if unclassified. */
+export function classOf(schema: unknown): DataClass | undefined {
+  return typeof schema === "object" && schema !== null ? registry.get(schema as object) : undefined;
+}
+
+// Unwrap the transparent wrappers Zod adds (.optional()/.nullable()/.default()/.refine())
+// so a marker survives being wrapped AFTER classification, and so an object nested under a
+// wrapper is still walked. Returns the wrapper chain (outermost→innermost) for class lookup
+// plus the innermost node for shape inspection.
+function chain(schema: z.ZodTypeAny): { nodes: z.ZodTypeAny[]; inner: z.ZodTypeAny } {
+  const nodes: z.ZodTypeAny[] = [];
+  let cur: z.ZodTypeAny = schema;
+  // Guard against a pathological self-referential def; real schemas terminate quickly.
+  for (let i = 0; i < 100; i++) {
+    nodes.push(cur);
+    const def = (cur as { _def?: Record<string, unknown> })._def;
+    const typeName = def?.typeName as string | undefined;
+    let next: unknown;
+    if (typeName === "ZodOptional" || typeName === "ZodNullable" || typeName === "ZodDefault") {
+      next = def?.innerType;
+    } else if (typeName === "ZodEffects") {
+      next = def?.schema;
+    } else {
+      break;
+    }
+    if (next === undefined) break;
+    cur = next as z.ZodTypeAny;
+  }
+  return { nodes, inner: cur };
+}
+
+/** The object `.shape` of a node, or `undefined` when it is not a `ZodObject`. */
+function objectShape(node: z.ZodTypeAny): Record<string, z.ZodTypeAny> | undefined {
+  const def = (node as { _def?: { typeName?: string; shape?: () => unknown } })._def;
+  if (def?.typeName !== "ZodObject" || typeof def.shape !== "function") return undefined;
+  return def.shape() as Record<string, z.ZodTypeAny>;
+}
+
+/** The mark on a schema, looking through any transparent wrappers around it (first wins). */
+function effectiveMark<T>(schema: z.ZodTypeAny, markOf: (node: z.ZodTypeAny) => T | undefined) {
+  for (const node of chain(schema).nodes) {
+    const mark = markOf(node);
+    if (mark !== undefined) return mark;
+  }
+  return undefined;
+}
+
+/**
+ * Generic marked-path walker — the shared engine behind {@link collectClassifiedPaths} and the
+ * {@link externalized} marker. Walks an object schema, and for every node whose `markOf`
+ * returns a value emits `{ path, mark }`, recursing through nested objects and transparent
+ * wrappers. A marked *object* is reported at its own path and NOT descended into (the coarser
+ * mark wins — a marked address object is treated as a unit). Recurses THROUGH arrays with a
+ * `[]` crossing segment (`people[].ssn`), which the sinks expand against the concrete value
+ * (#260) — a mark inside an array element used to collect no path and silently do nothing.
+ * Deterministic: schema-declaration order (P2).
+ */
+export function collectMarkedPaths<T>(
+  schema: z.ZodTypeAny,
+  markOf: (node: z.ZodTypeAny) => T | undefined,
+  prefix = ""
+): { path: string; mark: T }[] {
+  const out: { path: string; mark: T }[] = [];
+  const mark = effectiveMark(schema, markOf);
+  if (mark !== undefined && prefix !== "") {
+    out.push({ path: prefix, mark });
+    return out;
+  }
+  const inner = chain(schema).inner;
+  const element = arrayElement(inner);
+  if (element !== undefined) {
+    // Cross the array. The prefix gains `[]`, so `people` + element mark `ssn` yields
+    // `people[].ssn`; a mark on the ELEMENT type itself yields `people[]`.
+    return collectMarkedPaths(element, markOf, `${prefix}[]`);
+  }
+  const shape = objectShape(inner);
+  if (shape !== undefined) {
+    for (const [key, child] of Object.entries(shape)) {
+      const childPath = prefix === "" ? key : `${prefix}.${key}`;
+      out.push(...collectMarkedPaths(child, markOf, childPath));
+    }
+  }
+  return out;
+}
+
+/** The element type, if this node is an array. */
+function arrayElement(node: z.ZodTypeAny): z.ZodTypeAny | undefined {
+  const def = (node as { _def?: { typeName?: string; type?: unknown } })._def;
+  if (def?.typeName !== "ZodArray") return undefined;
+  return def.type as z.ZodTypeAny | undefined;
+}
+
+/** A classified leaf/subtree and its dot-path from the walked root. */
+export interface ClassifiedPath {
+  /** Dot-path from the schema root, e.g. `"user.ssn"`. Empty for the root itself. */
+  path: string;
+  dataClass: DataClass;
+}
+
+/**
+ * Walk an object schema and collect every classified field as a `{ path, dataClass }` (over the
+ * `secret`/`sensitive`/`internal` taxonomy). Thin wrapper over {@link collectMarkedPaths}.
+ */
+export function collectClassifiedPaths(schema: z.ZodTypeAny, prefix = ""): ClassifiedPath[] {
+  return collectMarkedPaths(schema, (node) => classOf(node), prefix).map((m) => ({
+    path: m.path,
+    dataClass: m.mark,
+  }));
+}
+
+/** The subset of {@link collectClassifiedPaths} matching one class (e.g. only `"sensitive"`). */
+export function pathsOfClass(schema: z.ZodTypeAny, dataClass: DataClass): string[] {
+  return collectClassifiedPaths(schema)
+    .filter((c) => c.dataClass === dataClass)
+    .map((c) => c.path);
+}
+
+/** Strictest of two classes (secret > sensitive > internal); `undefined` is weakest. */
+export function strictest(
+  a: DataClass | undefined,
+  b: DataClass | undefined
+): DataClass | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return RANK[a] >= RANK[b] ? a : b;
+}

package/src/expand.ts

@@ -0,0 +1,97 @@
+// ── Wildcard path expansion (#260 option 2) ───────────────────────────────────
+//
+// The dot-path sinks — telemetry masking, field-level encryption, content externalization —
+// address scalar paths and originally could not descend into array elements, so a mark
+// placed inside one did nothing at all. `[]` is the array-crossing segment that fixes it:
+// `people[].ssn` means "the `ssn` of every element of `people`".
+//
+// Rather than teach three near-identical spine-walkers about arrays, expansion happens ONCE
+// against the concrete value and yields ordinary indexed paths (`people.0.ssn`,
+// `people.1.ssn`) that every existing applier already handles — `array["0"]` is a normal
+// property access, and each applier's spine copy already preserves arrays. So the walkers
+// stay as they were, and there is one place where array semantics live.
+//
+// A path with no `[]` passes through untouched, so every pre-existing path behaves exactly
+// as before (G2).
+
+/** Split a segment into its key and how many array crossings follow it (`rows[][]` ⇒ 2). */
+function parseSegment(segment: string): { key: string; depth: number } {
+  let depth = 0;
+  let key = segment;
+  while (key.endsWith("[]")) {
+    key = key.slice(0, -2);
+    depth++;
+  }
+  return { key, depth };
+}
+
+/**
+ * Expand `paths` against `root`, replacing every `[]` with the concrete indices present in
+ * the value.
+ *
+ * - `"a.b"` (no wildcard) → `["a.b"]`, unchanged and unchecked; the appliers already skip
+ *   absent paths, and pre-existing behaviour must not shift.
+ * - `"people[].ssn"` over two people → `["people.0.ssn", "people.1.ssn"]`.
+ * - `"tags[]"` (a marked array ELEMENT type) → one path per element.
+ * - A wildcard that does not resolve — absent, or `[]` over a non-array — expands to
+ *   nothing, so nothing is masked/encrypted for it. Resolving against the value is the whole
+ *   point of expanding late.
+ */
+export function expandPaths(root: unknown, paths: readonly string[]): string[] {
+  const out: string[] = [];
+  for (const path of paths) {
+    if (!path.includes("[]")) {
+      out.push(path);
+      continue;
+    }
+    expandInto(root, path.split("."), 0, [], out);
+  }
+  return out;
+}
+
+/** True if any path uses a wildcard — lets callers skip expansion entirely (G2 fast path). */
+export function hasWildcard(paths: readonly string[]): boolean {
+  for (const p of paths) if (p.includes("[]")) return true;
+  return false;
+}
+
+function expandInto(
+  value: unknown,
+  segments: readonly string[],
+  index: number,
+  acc: readonly string[],
+  out: string[]
+): void {
+  if (index >= segments.length) {
+    out.push(acc.join("."));
+    return;
+  }
+  if (typeof value !== "object" || value === null) return;
+  const { key, depth } = parseSegment(segments[index] as string);
+  if (!Object.hasOwn(value, key)) return;
+  const child = (value as Record<string, unknown>)[key];
+  descend(child, depth, [...acc, key], segments, index, out);
+}
+
+/** Walk `depth` array levels, emitting an index per level, then continue with the next segment. */
+function descend(
+  value: unknown,
+  depth: number,
+  acc: readonly string[],
+  segments: readonly string[],
+  index: number,
+  out: string[]
+): void {
+  if (depth === 0) {
+    // Reached the value this segment names. If it is the last segment it IS the target;
+    // otherwise keep walking.
+    if (index === segments.length - 1) out.push(acc.join("."));
+    else expandInto(value, segments, index + 1, acc, out);
+    return;
+  }
+  // A `[]` over a non-array resolves to nothing — the mark does not apply to this value.
+  if (!Array.isArray(value)) return;
+  for (const [i, element] of value.entries()) {
+    descend(element, depth - 1, [...acc, String(i)], segments, index, out);
+  }
+}

package/src/external.ts

@@ -0,0 +1,40 @@
+import type { z } from "zod";
+import { collectMarkedPaths } from "./classify";
+
+// ── ADR 0046 — the `externalized()` marker ────────────────────────────────────
+//
+// Orthogonal to the secret/sensitive/internal taxonomy: that axis says HOW sensitive a field
+// is; this one says WHERE its value is stored — externalized to a content store, with the log
+// keeping only a reference. A field can be both (a large AND sensitive document: externalize
+// the bytes, and encrypt them in the content store). Because it is a separate axis, it has its
+// own registry rather than a fourth DataClass.
+//
+// A non-invasive WeakMap keeps the marker from mutating the Zod schema (same instance returned,
+// validation untouched), exactly like the classification registry.
+
+const externalRegistry = new WeakMap<object, true>();
+
+/**
+ * Mark a field `externalized` — its value is moved to a content store on append and the log
+ * keeps a content-addressed reference (ADR 0046). Returns the SAME schema (validation
+ * unchanged). Marking an object externalizes its whole subtree as one blob.
+ */
+export function externalized<T extends z.ZodTypeAny>(schema: T): T {
+  externalRegistry.set(schema, true);
+  return schema;
+}
+
+/** Whether a schema was marked {@link externalized} (through transparent wrappers is handled by the walker). */
+export function isExternalized(schema: unknown): boolean {
+  return typeof schema === "object" && schema !== null && externalRegistry.get(schema) === true;
+}
+
+/**
+ * The dot-paths of every `externalized()`-marked field in a schema (declaration order,
+ * deterministic). A marked object is reported at its own path as a unit.
+ */
+export function externalizedPaths(schema: z.ZodTypeAny): string[] {
+  return collectMarkedPaths(schema, (node) =>
+    externalRegistry.get(node) === true ? true : undefined
+  ).map((m) => m.path);
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export {
+  classify,
+  classOf,
+  collectClassifiedPaths,
+  collectMarkedPaths,
+  internal,
+  pathsOfClass,
+  secret,
+  sensitive,
+  strictest,
+} from "./classify";
+export type { ClassifiedPath, DataClass } from "./classify";
+export { externalized, externalizedPaths, isExternalized } from "./external";
+export {
+  TAINT_SCAN_EXCEEDED_ORIGIN,
+  TAINT_SCAN_MAX_DEPTH,
+  TAINT_SCAN_MAX_NODES,
+  isTainted,
+  nestedTaintOrigin,
+  taintOriginLabel,
+  TAINT_ORIGIN_LABEL_MAX,
+  scanTaint,
+  tainted,
+  taintOf,
+  unwrapTainted,
+} from "./taint";
+export type { Taint, TaintScan, TaintScanOptions, TaintedValue } from "./taint";
+export { REDACTED, maskPaths } from "./redact";
+export { expandPaths, hasWildcard } from "./expand";
+export { collectUnreachableMarks } from "./unreachable";
+export type { UnreachableMark } from "./unreachable";

package/src/redact.ts

@@ -0,0 +1,59 @@
+import { expandPaths, hasWildcard } from "./expand";
+// ── K10-R6 — the shared egress-masking primitive ──────────────────────────────
+//
+// One structural path-masker, used by every egress surface (telemetry adapters, agent-surface
+// surfaces, the CLI). It replaces the value at each dot-path with a mask, copying only the
+// spine it touches (structural sharing elsewhere) and never mutating the caller's object.
+// Absent paths are skipped, so masking a payload that doesn't carry a marked field is a
+// no-op on that field. Lives here in `@loomwork/classify` — the neutral home the classification
+// consumers already depend on — so no surface package depends on another.
+
+/** The value an egress-masked field is replaced by (structure kept, value gone). */
+export const REDACTED = "[redacted]" as const;
+
+/**
+ * Return a copy of `root` with each dot-path's value replaced by `mask`. A dot-path always
+ * roots at an object (an array/primitive root has nothing to address), so those are returned
+ * as-is. Paths are applied independently; a shared prefix is copied once.
+ */
+/** Copy one spine node, preserving arrays. */
+function shallowCopy(value: object): Record<string, unknown> {
+  return Array.isArray(value)
+    ? ([...value] as unknown as Record<string, unknown>)
+    : { ...(value as Record<string, unknown>) };
+}
+
+export function maskPaths(
+  root: unknown,
+  paths: readonly string[],
+  mask: unknown = REDACTED
+): unknown {
+  if (typeof root !== "object" || root === null || Array.isArray(root)) return root;
+  const out: Record<string, unknown> = { ...(root as Record<string, unknown>) };
+  // `[]` segments are resolved against the concrete value first (#260); a path without one
+  // passes through untouched, so pre-existing behaviour is unchanged.
+  for (const path of hasWildcard(paths) ? expandPaths(root, paths) : paths) {
+    const segs = path.split(".");
+    let src = root as Record<string, unknown>;
+    let dst = out;
+    let reachable = true;
+    for (let i = 0; i < segs.length - 1; i++) {
+      const seg = segs[i] as string;
+      const child = src[seg];
+      if (typeof child !== "object" || child === null) {
+        reachable = false;
+        break;
+      }
+      // Copy this spine node once (first path to reach it); later paths sharing the prefix
+      // descend into the already-copied node.
+      // Copy arrays AS arrays. `{ ...array }` would yield an object with numeric keys —
+      // harmless while paths never crossed arrays, corrupting now that they do.
+      if (dst[seg] === child) dst[seg] = shallowCopy(child as object);
+      src = child as Record<string, unknown>;
+      dst = dst[seg] as Record<string, unknown>;
+    }
+    const leaf = segs[segs.length - 1] as string;
+    if (reachable && Object.hasOwn(src, leaf)) dst[leaf] = mask;
+  }
+  return out;
+}

package/src/taint.ts

@@ -0,0 +1,189 @@
+// ── The integrity axis — provenance for content the system did not author ────
+//
+// The existing markers are a CONFIDENTIALITY axis (`secret`/`sensitive`/
+// `internal` — what may LEAVE) plus a where-stored axis (`externalized`). This
+// is the third and opposite direction: what may ENTER an instruction position.
+// A third-party MCP tool result, an A2A peer's response, a fetched document —
+// all arrive as ordinary strings, and an ordinary string interpolated into a
+// system prompt is indistinguishable from an instruction the operator wrote.
+//
+// WHY A VALUE WRAPPER AND NOT A SCHEMA MARKER. Confidentiality is a property of
+// a FIELD: `ssn` is sensitive in every execution, forever, so declaring it once
+// at the schema is exactly right. Integrity is a property of a VALUE: the same
+// `summary: string` field is trustworthy when this flow computed it and
+// untrusted when a third-party server returned it, and which one it is cannot be
+// known until runtime. A schema marker would have to guess, and a marker that
+// guesses is worse than none — it reads as coverage. So taint is attached where
+// it is acquired, to the value, by the code that acquired it.
+//
+// The wrapper is plain JSON (`{ __loomTainted, value }`), the same structural
+// shape K10.3's `secretRef` uses, so it survives the log verbatim and a replay
+// hands the effect back a value that is still tainted. The corollary is the
+// honest limit on retrofitting: taint applies to content ingested AFTER a
+// producer starts applying it. An existing log replays exactly as it did, with
+// no taint, because the fact was never recorded — the same argument ADR 0063 D3
+// made about principals.
+
+/** Where a tainted value came from — an origin label, e.g. `mcp:acme/chart`. */
+export interface Taint {
+  /**
+   * Human-meaningful provenance, chosen by the producer. It is rendered into
+   * the fence around the content, so treat it as untrusted display text: it
+   * frequently contains a third-party-controlled fragment (a tool name, a peer
+   * id) and is escaped at the point of use, never trusted as markup.
+   */
+  origin: string;
+}
+
+/** A value carrying its own provenance. Plain JSON — survives the log unchanged. */
+export interface TaintedValue<T = unknown> {
+  __loomTainted: Taint;
+  value: T;
+}
+
+/**
+ * Wrap a value as untrusted, recording where it came from.
+ *
+ * Apply this at INGRESS — the moment content crosses into the system from a
+ * party that is not the operator. Tainting later is guesswork, and tainting
+ * never is how third-party text ends up in a system prompt.
+ *
+ * Re-tainting an already-tainted value keeps the ORIGINAL origin: provenance
+ * records where content entered, and a re-wrap would let a later, more
+ * flattering label overwrite the true one.
+ */
+export function tainted<T>(value: T, origin: string): TaintedValue<T> {
+  if (isTainted(value)) return value as TaintedValue<T>;
+  return { __loomTainted: { origin }, value };
+}
+
+/** Whether a value carries taint. Structural, so it survives a JSON round-trip. */
+export function isTainted(value: unknown): value is TaintedValue {
+  if (typeof value !== "object" || value === null) return false;
+  const mark = (value as { __loomTainted?: unknown }).__loomTainted;
+  return (
+    typeof mark === "object" &&
+    mark !== null &&
+    typeof (mark as { origin?: unknown }).origin === "string" &&
+    "value" in value
+  );
+}
+
+/** The provenance on a value, or `undefined` when it carries none. */
+export function taintOf(value: unknown): Taint | undefined {
+  return isTainted(value) ? value.__loomTainted : undefined;
+}
+
+/**
+ * The inner value, discarding provenance. Non-tainted values pass through.
+ *
+ * Deliberately loud. Unwrapping is legitimate and often necessary — parsing a
+ * tainted JSON payload, indexing a tainted record — but every call is a place
+ * where provenance stops travelling. Unwrap to COMPUTE with content; never
+ * unwrap on the way to a prompt, which is the one path the taint exists to
+ * govern. Nothing can stop you; the point is that the call site is visible.
+ */
+export function unwrapTainted<T>(value: TaintedValue<T> | T): T {
+  return isTainted(value) ? (value.value as T) : (value as T);
+}
+
+// ── Nested taint - a marker anywhere inside a value ──────────────────────────
+//
+// `isTainted` looks at the TOP of a value only. A producer that taints part of what it returns (an A2A
+// reply taints `content` and leaves `raw` for control flow, ADR 0085) hands back a plain object with a
+// wrapper buried inside, and every top-level check reads it as clean. `scanTaint` is the one walk the
+// agent loop and the claim-check middleware share to answer "is ANY of this untrusted".
+
+/** Bounds of a {@link scanTaint} walk. */
+export interface TaintScanOptions {
+  /** Deepest nesting visited (the root is depth 0). Default {@link TAINT_SCAN_MAX_DEPTH}. */
+  maxDepth?: number;
+  /** Most object/array nodes visited. Default {@link TAINT_SCAN_MAX_NODES}. */
+  maxNodes?: number;
+}
+
+/** Default nesting bound of {@link scanTaint}. */
+export const TAINT_SCAN_MAX_DEPTH = 64;
+/** Default node bound of {@link scanTaint}. */
+export const TAINT_SCAN_MAX_NODES = 100_000;
+/** The origin reported when a scan hit its bound and could not prove the value clean. */
+export const TAINT_SCAN_EXCEEDED_ORIGIN = "unknown:taint-scan-bound-exceeded";
+
+/** What {@link scanTaint} found. */
+export interface TaintScan {
+  /** Distinct origins of every wrapper found, in discovery order. */
+  readonly origins: readonly string[];
+  /** The walk hit a bound before it finished: the value is NOT proven clean. */
+  readonly exceeded: boolean;
+  /** `origins` is non-empty or `exceeded` - the value must be treated as untrusted. */
+  readonly tainted: boolean;
+}
+
+/**
+ * Walk `value` for taint wrappers at ANY depth. Iterative (no recursion, so a 100k-deep JSON cannot
+ * blow the stack), cycle-safe, and bounded by depth and node count. FAILS CLOSED: when a bound is hit
+ * the result is `exceeded: true` and `tainted: true`, because "too big to look at" is not "clean".
+ * Binary views are skipped (they cannot hold a wrapper). Pure: the value is never modified.
+ */
+export function scanTaint(value: unknown, options: TaintScanOptions = {}): TaintScan {
+  const maxDepth = options.maxDepth ?? TAINT_SCAN_MAX_DEPTH;
+  const maxNodes = options.maxNodes ?? TAINT_SCAN_MAX_NODES;
+  const origins: string[] = [];
+  const found = new Set<string>();
+  let exceeded = false;
+  let nodes = 0;
+  const seen = new WeakSet<object>();
+  const stack: Array<{ v: unknown; d: number }> = [{ v: value, d: 0 }];
+  while (stack.length > 0) {
+    const { v, d } = stack.pop() as { v: unknown; d: number };
+    if (typeof v !== "object" || v === null || seen.has(v) || ArrayBuffer.isView(v)) continue;
+    seen.add(v);
+    if (++nodes > maxNodes || d > maxDepth) {
+      exceeded = true;
+      break;
+    }
+    if (isTainted(v)) {
+      const origin = v.__loomTainted.origin;
+      if (!found.has(origin)) {
+        found.add(origin);
+        origins.push(origin);
+      }
+    }
+    for (const child of Array.isArray(v) ? v : Object.values(v)) {
+      if (typeof child === "object" && child !== null) stack.push({ v: child, d: d + 1 });
+    }
+  }
+  return { origins, exceeded, tainted: exceeded || origins.length > 0 };
+}
+
+/** Most distinct origins named in a joined label; the rest are counted (`+N more`). */
+export const TAINT_ORIGIN_LABEL_MAX = 8;
+/** Longest single origin kept in a joined label (a forged wrapper can carry a megabyte origin). */
+const TAINT_ORIGIN_MAX_CHARS = 200;
+
+/**
+ * The label for a {@link TaintScan}, or `undefined` when it is clean. The first
+ * {@link TAINT_ORIGIN_LABEL_MAX} distinct origins are joined (`a, b`) and the rest counted
+ * (`+N more`), so a value stuffed with forged wrappers cannot make a megabyte label that is then
+ * journaled and fenced. A bound hit adds {@link TAINT_SCAN_EXCEEDED_ORIGIN}.
+ */
+export function taintOriginLabel(scan: TaintScan): string | undefined {
+  if (!scan.tainted) return undefined;
+  const shown = scan.origins
+    .slice(0, TAINT_ORIGIN_LABEL_MAX)
+    .map((o) =>
+      o.length > TAINT_ORIGIN_MAX_CHARS ? `${o.slice(0, TAINT_ORIGIN_MAX_CHARS)}...` : o
+    );
+  const more = scan.origins.length - shown.length;
+  if (more > 0) shown.push(`+${more} more`);
+  if (scan.exceeded) shown.push(TAINT_SCAN_EXCEEDED_ORIGIN);
+  return shown.join(", ");
+}
+
+/**
+ * The origin label for a value that may hold nested taint, or `undefined` when it is provably clean
+ * (see {@link taintOriginLabel}).
+ */
+export function nestedTaintOrigin(value: unknown, options?: TaintScanOptions): string | undefined {
+  return taintOriginLabel(scanTaint(value, options));
+}