@loomwork/classify 0.0.0-stage → 0.1.0

package/dist/esm/expand.js

@@ -0,0 +1,87 @@
+// ── 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) {
+    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, paths) {
+    const out = [];
+    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) {
+    for (const p of paths)
+        if (p.includes("[]"))
+            return true;
+    return false;
+}
+function expandInto(value, segments, index, acc, out) {
+    if (index >= segments.length) {
+        out.push(acc.join("."));
+        return;
+    }
+    if (typeof value !== "object" || value === null)
+        return;
+    const { key, depth } = parseSegment(segments[index]);
+    if (!Object.hasOwn(value, key))
+        return;
+    const child = value[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, depth, acc, segments, index, out) {
+    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);
+    }
+}
+//# sourceMappingURL=expand.js.map

package/dist/esm/expand.js.map

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

package/dist/esm/external.js

@@ -0,0 +1,33 @@
+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();
+/**
+ * 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(schema) {
+    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) {
+    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) {
+    return collectMarkedPaths(schema, (node) => externalRegistry.get(node) === true ? true : undefined).map((m) => m.path);
+}
+//# sourceMappingURL=external.js.map

package/dist/esm/external.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.js","sourceRoot":"","sources":["../../src/external.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,iFAAiF;AACjF,EAAE;AACF,6FAA6F;AAC7F,8FAA8F;AAC9F,6FAA6F;AAC7F,+FAA+F;AAC/F,+CAA+C;AAC/C,EAAE;AACF,gGAAgG;AAChG,mEAAmE;AAEnE,MAAM,gBAAgB,GAAG,IAAI,OAAO,EAAgB,CAAC;AAErD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAyB,MAAS;IAC5D,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,cAAc,CAAC,MAAe;IAC5C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;AAChG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAoB;IACpD,OAAO,kBAAkB,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CACzC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CACvD,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+export { classify, classOf, collectClassifiedPaths, collectMarkedPaths, internal, pathsOfClass, secret, sensitive, strictest, } 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 { REDACTED, maskPaths } from "./redact";
+export { expandPaths, hasWildcard } from "./expand";
+export { collectUnreachableMarks } from "./unreachable";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,OAAO,EACP,sBAAsB,EACtB,kBAAkB,EAClB,QAAQ,EACR,YAAY,EACZ,MAAM,EACN,SAAS,EACT,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,OAAO,EACP,OAAO,EACP,aAAa,GACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC"}

package/dist/esm/redact.js

@@ -0,0 +1,56 @@
+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]";
+/**
+ * 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) {
+    return Array.isArray(value)
+        ? [...value]
+        : { ...value };
+}
+export function maskPaths(root, paths, mask = REDACTED) {
+    if (typeof root !== "object" || root === null || Array.isArray(root))
+        return root;
+    const out = { ...root };
+    // `[]` 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;
+        let dst = out;
+        let reachable = true;
+        for (let i = 0; i < segs.length - 1; i++) {
+            const seg = segs[i];
+            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);
+            src = child;
+            dst = dst[seg];
+        }
+        const leaf = segs[segs.length - 1];
+        if (reachable && Object.hasOwn(src, leaf))
+            dst[leaf] = mask;
+    }
+    return out;
+}
+//# sourceMappingURL=redact.js.map

package/dist/esm/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/redact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACpD,iFAAiF;AACjF,EAAE;AACF,8FAA8F;AAC9F,2FAA2F;AAC3F,0FAA0F;AAC1F,wFAAwF;AACxF,gGAAgG;AAChG,0EAA0E;AAE1E,oFAAoF;AACpF,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAqB,CAAC;AAE9C;;;;GAIG;AACH,8CAA8C;AAC9C,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzB,CAAC,CAAE,CAAC,GAAG,KAAK,CAAwC;QACpD,CAAC,CAAC,EAAE,GAAI,KAAiC,EAAE,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,IAAa,EACb,KAAwB,EACxB,OAAgB,QAAQ;IAExB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClF,MAAM,GAAG,GAA4B,EAAE,GAAI,IAAgC,EAAE,CAAC;IAC9E,yFAAyF;IACzF,oEAAoE;IACpE,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;QACzE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,GAAG,GAAG,IAA+B,CAAC;QAC1C,IAAI,GAAG,GAAG,GAAG,CAAC;QACd,IAAI,SAAS,GAAG,IAAI,CAAC;QACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAW,CAAC;YAC9B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACvB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBAChD,SAAS,GAAG,KAAK,CAAC;gBAClB,MAAM;YACR,CAAC;YACD,qFAAqF;YACrF,wCAAwC;YACxC,kFAAkF;YAClF,0EAA0E;YAC1E,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,KAAe,CAAC,CAAC;YAChE,GAAG,GAAG,KAAgC,CAAC;YACvC,GAAG,GAAG,GAAG,CAAC,GAAG,CAA4B,CAAC;QAC5C,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAW,CAAC;QAC7C,IAAI,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/esm/taint.js

@@ -0,0 +1,142 @@
+// ── 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.
+/**
+ * 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(value, origin) {
+    if (isTainted(value))
+        return value;
+    return { __loomTainted: { origin }, value };
+}
+/** Whether a value carries taint. Structural, so it survives a JSON round-trip. */
+export function isTainted(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const mark = value.__loomTainted;
+    return (typeof mark === "object" &&
+        mark !== null &&
+        typeof mark.origin === "string" &&
+        "value" in value);
+}
+/** The provenance on a value, or `undefined` when it carries none. */
+export function taintOf(value) {
+    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(value) {
+    return isTainted(value) ? value.value : value;
+}
+/** 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";
+/**
+ * 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, options = {}) {
+    const maxDepth = options.maxDepth ?? TAINT_SCAN_MAX_DEPTH;
+    const maxNodes = options.maxNodes ?? TAINT_SCAN_MAX_NODES;
+    const origins = [];
+    const found = new Set();
+    let exceeded = false;
+    let nodes = 0;
+    const seen = new WeakSet();
+    const stack = [{ v: value, d: 0 }];
+    while (stack.length > 0) {
+        const { v, d } = stack.pop();
+        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) {
+    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, options) {
+    return taintOriginLabel(scanTaint(value, options));
+}
+//# sourceMappingURL=taint.js.map

package/dist/esm/taint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"taint.js","sourceRoot":"","sources":["../../src/taint.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,EAAE;AACF,yEAAyE;AACzE,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,wEAAwE;AACxE,iFAAiF;AACjF,8EAA8E;AAC9E,gFAAgF;AAChF,8DAA8D;AAC9D,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,4EAA4E;AAC5E,0EAA0E;AAC1E,+EAA+E;AAC/E,gFAAgF;AAChF,yBAAyB;AAmBzB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,OAAO,CAAI,KAAQ,EAAE,MAAc;IACjD,IAAI,SAAS,CAAC,KAAK,CAAC;QAAE,OAAO,KAAwB,CAAC;IACtD,OAAO,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC;AAC9C,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,IAAI,GAAI,KAAqC,CAAC,aAAa,CAAC;IAClE,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,OAAQ,IAA6B,CAAC,MAAM,KAAK,QAAQ;QACzD,OAAO,IAAI,KAAK,CACjB,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAI,KAA0B;IACzD,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAK,CAAC,KAAW,CAAC,CAAC,CAAE,KAAW,CAAC;AAC9D,CAAC;AAiBD,kDAAkD;AAClD,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,+CAA+C;AAC/C,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAC5C,yFAAyF;AACzF,MAAM,CAAC,MAAM,0BAA0B,GAAG,mCAAmC,CAAC;AAY9E;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc,EAAE,UAA4B,EAAE;IACtE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,oBAAoB,CAAC;IAC1D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,oBAAoB,CAAC;IAC1D,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,IAAI,GAAG,IAAI,OAAO,EAAU,CAAC;IACnC,MAAM,KAAK,GAAqC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACrE,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC,GAAG,EAA+B,CAAC;QAC1D,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;YAAE,SAAS;QAC1F,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACZ,IAAI,EAAE,KAAK,GAAG,QAAQ,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC;YACvC,QAAQ,GAAG,IAAI,CAAC;YAChB,MAAM;QACR,CAAC;QACD,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;YACjB,MAAM,MAAM,GAAG,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC;YACtC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvB,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBAClB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;AACxE,CAAC;AAED,uFAAuF;AACvF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AACxC,mGAAmG;AACnG,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAe;IAC9C,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO;SACvB,KAAK,CAAC,CAAC,EAAE,sBAAsB,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACT,CAAC,CAAC,MAAM,GAAG,sBAAsB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CACnF,CAAC;IACJ,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAChD,IAAI,IAAI,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,CAAC;IAC1C,IAAI,IAAI,CAAC,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAC1D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,OAA0B;IAC1E,OAAO,gBAAgB,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AACrD,CAAC"}

package/dist/esm/unreachable.js

@@ -0,0 +1,126 @@
+import { classOf } from "./classify";
+/** Unwrap optional/nullable/default/effects, as the classification walker does. */
+function chain(schema) {
+    const nodes = [];
+    let cur = schema;
+    for (let i = 0; i < 100; i++) {
+        nodes.push(cur);
+        const def = cur._def;
+        const typeName = def?.typeName;
+        let next;
+        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;
+    }
+    return { nodes, inner: cur };
+}
+function typeNameOf(node) {
+    return node._def?.typeName;
+}
+function objectShape(node) {
+    const def = node._def;
+    if (def?.typeName !== "ZodObject" || typeof def.shape !== "function")
+        return undefined;
+    return def.shape();
+}
+function arrayElement(node) {
+    const def = node._def;
+    if (def?.typeName !== "ZodArray")
+        return undefined;
+    return def.type;
+}
+/**
+ * Schemas that hold inner schemas the classification walker never descends into. Returns the
+ * children to search for stranded marks, plus the label for the location string.
+ *
+ * `lazy` is deliberately absent: descending a recursive schema to hunt for marks risks
+ * non-termination, and the payoff is small.
+ */
+function opaqueChildren(node) {
+    const def = node._def;
+    const typeName = typeNameOf(node);
+    switch (typeName) {
+        case "ZodRecord":
+        case "ZodMap":
+        case "ZodSet":
+            return {
+                label: typeName.slice(3).toLowerCase(),
+                children: [def?.valueType].filter(Boolean),
+            };
+        case "ZodUnion":
+        case "ZodDiscriminatedUnion": {
+            const options = def?.options;
+            const list = Array.isArray(options)
+                ? options
+                : [...(options?.values?.() ?? [])];
+            return { label: "union", children: list };
+        }
+        case "ZodTuple":
+            return { label: "tuple", children: def?.items ?? [] };
+        case "ZodIntersection":
+            return {
+                label: "intersection",
+                children: [def?.left, def?.right].filter(Boolean),
+            };
+        default:
+            return undefined;
+    }
+}
+function effectiveClass(schema) {
+    for (const node of chain(schema).nodes) {
+        const mark = classOf(node);
+        if (mark !== undefined)
+            return mark;
+    }
+    return undefined;
+}
+/**
+ * Every classification mark stranded under a container the dot-path sinks cannot address.
+ *
+ * Returns `[]` for marks on objects and arrays — both are traversable, so those marks work.
+ */
+export function collectUnreachableMarks(schema, prefix = "") {
+    return walk(schema, prefix, undefined);
+}
+function walk(schema, path, blockedBy) {
+    const mark = effectiveClass(schema);
+    if (mark !== undefined && path !== "") {
+        // A mark terminates the walk exactly as it does in `collectMarkedPaths` — a marked object
+        // is a unit — so a mark nested inside a marked one is not double-reported.
+        return blockedBy === undefined ? [] : [{ path, dataClass: mark, container: blockedBy }];
+    }
+    const inner = chain(schema).inner;
+    const element = arrayElement(inner);
+    if (element !== undefined)
+        return walk(element, `${path}[]`, blockedBy);
+    const shape = objectShape(inner);
+    if (shape !== undefined) {
+        const out = [];
+        for (const [key, child] of Object.entries(shape)) {
+            out.push(...walk(child, path === "" ? key : `${path}.${key}`, blockedBy));
+        }
+        return out;
+    }
+    const opaque = opaqueChildren(inner);
+    if (opaque !== undefined) {
+        const out = [];
+        // Everything below here is unreachable — but keep the OUTERMOST blocker, since that is
+        // the one the developer has to restructure.
+        const blocker = blockedBy ?? opaque.label;
+        for (const child of opaque.children) {
+            out.push(...walk(child, `${path}.<${opaque.label}>`, blocker));
+        }
+        return out;
+    }
+    return [];
+}
+//# sourceMappingURL=unreachable.js.map

package/dist/esm/unreachable.js.map

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

package/dist/expand.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function expandPaths(root: unknown, paths: readonly string[]): string[];
+/** True if any path uses a wildcard — lets callers skip expansion entirely (G2 fast path). */
+export declare function hasWildcard(paths: readonly string[]): boolean;
+//# sourceMappingURL=expand.d.ts.map

package/dist/expand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand.d.ts","sourceRoot":"","sources":["../src/expand.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAU7E;AAED,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAG7D"}

package/dist/expand.js

@@ -0,0 +1,91 @@
+"use strict";
+// ── 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).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expandPaths = expandPaths;
+exports.hasWildcard = hasWildcard;
+/** Split a segment into its key and how many array crossings follow it (`rows[][]` ⇒ 2). */
+function parseSegment(segment) {
+    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.
+ */
+function expandPaths(root, paths) {
+    const out = [];
+    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). */
+function hasWildcard(paths) {
+    for (const p of paths)
+        if (p.includes("[]"))
+            return true;
+    return false;
+}
+function expandInto(value, segments, index, acc, out) {
+    if (index >= segments.length) {
+        out.push(acc.join("."));
+        return;
+    }
+    if (typeof value !== "object" || value === null)
+        return;
+    const { key, depth } = parseSegment(segments[index]);
+    if (!Object.hasOwn(value, key))
+        return;
+    const child = value[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, depth, acc, segments, index, out) {
+    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);
+    }
+}
+//# sourceMappingURL=expand.js.map

package/dist/expand.js.map

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

package/dist/external.d.ts

@@ -0,0 +1,15 @@
+import type { z } from "zod";
+/**
+ * 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 declare function externalized<T extends z.ZodTypeAny>(schema: T): T;
+/** Whether a schema was marked {@link externalized} (through transparent wrappers is handled by the walker). */
+export declare function isExternalized(schema: unknown): boolean;
+/**
+ * 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 declare function externalizedPaths(schema: z.ZodTypeAny): string[];
+//# sourceMappingURL=external.d.ts.map

package/dist/external.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../src/external.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgB7B;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAGjE;AAED,gHAAgH;AAChH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAEvD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,MAAM,EAAE,CAIhE"}