@loomwork/plugin-content 0.0.0-stage → 0.1.1

package/dist/ContentTouchingSnapshotStore.d.ts

@@ -0,0 +1,56 @@
+import type { Snapshot, SnapshotStore } from "@loomwork/snapshot-runtime";
+import type { ContentStore } from "./ContentStore";
+import { type TouchErrorHook } from "./touchAround";
+/**
+ * The brand a {@link ContentTouchingSnapshotStore} carries (a registered symbol, so a second copy of
+ * this package still recognises it). Read it through {@link isContentTouchingSnapshotStore}.
+ */
+export declare const CONTENT_TOUCHING_SNAPSHOT_STORE: unique symbol;
+/**
+ * True when `store` is a {@link ContentTouchingSnapshotStore}. Evidence about THIS object only: a
+ * `false` does not prove the runtime wrote unwrapped (a sweep or the CLI reads a raw store over the
+ * same tables a wrapped one wrote), and a `true` does not prove every OTHER store the runtime saves
+ * to is wrapped. `sweepUnpinnedContent` therefore uses it only to warn, never to relax or refuse.
+ */
+export declare function isContentTouchingSnapshotStore(store: unknown): boolean;
+export interface ContentTouchingSnapshotStoreOptions {
+    /** See {@link TouchErrorHook}: the touch after a durable save, and a cited blob found missing. */
+    onTouchError?: TouchErrorHook;
+}
+/**
+ * ADR 0055 D6 amendment 2 — the SECOND citation path. `copyPrefix` copies only the post-gap events
+ * of a compacted parent; the refs its truncated prefix cited live in the child's SEED SNAPSHOT
+ * (the runtime's `fork` saves it), where an R5 media source or a claim-check envelope stays
+ * verbatim and nothing `put`s it again. `ContentResolvingEventStore` cannot see it, so this
+ * decorator touches the citations of every snapshot it SAVES, before and after, exactly as that
+ * store does for events (same walker, same guarantee: D5's margin, see {@link touchAround}).
+ *
+ * Chosen over a hook in the runtime because the runtime holds no content store (and must not
+ * depend on the content plugin), and over touching at fork start because a decorator also covers
+ * compaction checkpoints and every other save with no extra seam. Cost: one iterative walk of the
+ * saved state and a round trip only when it cites a blob; with a content store that has no `touch`
+ * nothing at all.
+ *
+ * Wrap it OUTSIDE an `EncryptingSnapshotStore` (it must see the plaintext state, or refs under a
+ * sensitive path are hidden from the walk), and pass the same content store the event log uses.
+ * The seed is saved after the prefix copy, so a fork racing the DELETION of its own parent is
+ * outside the guarantee (the fork's read of the parent fails then, too).
+ */
+export declare class ContentTouchingSnapshotStore implements SnapshotStore {
+    private readonly inner;
+    private readonly content;
+    readonly deleteExecution?: NonNullable<SnapshotStore["deleteExecution"]>;
+    readonly loadLatestSealed?: NonNullable<SnapshotStore["loadLatestSealed"]>;
+    readonly pruneSnapshots?: NonNullable<SnapshotStore["pruneSnapshots"]>;
+    readonly listSequences?: NonNullable<SnapshotStore["listSequences"]>;
+    /** Brand: see {@link isContentTouchingSnapshotStore}. */
+    readonly [CONTENT_TOUCHING_SNAPSHOT_STORE] = true;
+    private readonly onTouchError;
+    constructor(inner: SnapshotStore, content: Pick<ContentStore, "touch">, options?: ContentTouchingSnapshotStoreOptions);
+    save(snapshot: Snapshot): Promise<void>;
+    loadLatest(executionId: string): Promise<Snapshot | null>;
+    loadAt(executionId: string, sequence: number): Promise<Snapshot | null>;
+    loadLatestBefore(executionId: string, sequence: number): Promise<Snapshot | null>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=ContentTouchingSnapshotStore.d.ts.map

package/dist/ContentTouchingSnapshotStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContentTouchingSnapshotStore.d.ts","sourceRoot":"","sources":["../src/ContentTouchingSnapshotStore.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,QAAQ,EACR,aAAa,EACd,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,KAAK,cAAc,EAAe,MAAM,eAAe,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,+BAA+B,EAAE,OAAO,MAEpD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMtE;AAED,MAAM,WAAW,mCAAmC;IAClD,kGAAkG;IAClG,YAAY,CAAC,EAAE,cAAc,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,4BAA6B,YAAW,aAAa;IAU9D,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B,QAAQ,CAAC,eAAe,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACzE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACvE,QAAQ,CAAC,aAAa,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;IACrE,yDAAyD;IACzD,QAAQ,CAAC,CAAC,+BAA+B,CAAC,QAAQ;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;gBAGvC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,EACrD,OAAO,GAAE,mCAAwC;IAgBnD,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvC,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAIzD,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAIvE,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAIjF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvB"}

package/dist/ContentTouchingSnapshotStore.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentTouchingSnapshotStore = exports.CONTENT_TOUCHING_SNAPSHOT_STORE = void 0;
+exports.isContentTouchingSnapshotStore = isContentTouchingSnapshotStore;
+const event_runtime_1 = require("@loomwork/event-runtime");
+const touchAround_1 = require("./touchAround");
+/**
+ * The brand a {@link ContentTouchingSnapshotStore} carries (a registered symbol, so a second copy of
+ * this package still recognises it). Read it through {@link isContentTouchingSnapshotStore}.
+ */
+exports.CONTENT_TOUCHING_SNAPSHOT_STORE = Symbol.for("loom.plugin-content.ContentTouchingSnapshotStore");
+/**
+ * True when `store` is a {@link ContentTouchingSnapshotStore}. Evidence about THIS object only: a
+ * `false` does not prove the runtime wrote unwrapped (a sweep or the CLI reads a raw store over the
+ * same tables a wrapped one wrote), and a `true` does not prove every OTHER store the runtime saves
+ * to is wrapped. `sweepUnpinnedContent` therefore uses it only to warn, never to relax or refuse.
+ */
+function isContentTouchingSnapshotStore(store) {
+    return (typeof store === "object" &&
+        store !== null &&
+        store[exports.CONTENT_TOUCHING_SNAPSHOT_STORE] === true);
+}
+/**
+ * ADR 0055 D6 amendment 2 — the SECOND citation path. `copyPrefix` copies only the post-gap events
+ * of a compacted parent; the refs its truncated prefix cited live in the child's SEED SNAPSHOT
+ * (the runtime's `fork` saves it), where an R5 media source or a claim-check envelope stays
+ * verbatim and nothing `put`s it again. `ContentResolvingEventStore` cannot see it, so this
+ * decorator touches the citations of every snapshot it SAVES, before and after, exactly as that
+ * store does for events (same walker, same guarantee: D5's margin, see {@link touchAround}).
+ *
+ * Chosen over a hook in the runtime because the runtime holds no content store (and must not
+ * depend on the content plugin), and over touching at fork start because a decorator also covers
+ * compaction checkpoints and every other save with no extra seam. Cost: one iterative walk of the
+ * saved state and a round trip only when it cites a blob; with a content store that has no `touch`
+ * nothing at all.
+ *
+ * Wrap it OUTSIDE an `EncryptingSnapshotStore` (it must see the plaintext state, or refs under a
+ * sensitive path are hidden from the walk), and pass the same content store the event log uses.
+ * The seed is saved after the prefix copy, so a fork racing the DELETION of its own parent is
+ * outside the guarantee (the fork's read of the parent fails then, too).
+ */
+class ContentTouchingSnapshotStore {
+    inner;
+    content;
+    deleteExecution;
+    loadLatestSealed;
+    pruneSnapshots;
+    listSequences;
+    /** Brand: see {@link isContentTouchingSnapshotStore}. */
+    [exports.CONTENT_TOUCHING_SNAPSHOT_STORE] = true;
+    onTouchError;
+    constructor(inner, content, options = {}) {
+        this.inner = inner;
+        this.content = content;
+        this.onTouchError = options.onTouchError;
+        const plan = {
+            deleteExecution: "forward",
+            loadLatestSealed: "forward",
+            // ADR 0134 D6 — a delete cites nothing, so there is nothing to touch. A blob only a pruned
+            // snapshot cited was never pinned by the sweep (it pins the latest and the checkpoint,
+            // both of which pruning keeps), so no sweep decision changes.
+            pruneSnapshots: "forward",
+            // ADR 0134 amendment - a read of sequences cites no content.
+            listSequences: "forward",
+        };
+        (0, event_runtime_1.installOptional)(this, inner, plan);
+    }
+    save(snapshot) {
+        return (0, touchAround_1.touchAround)(this.content, [snapshot.state], { operation: "snapshotSave", executionId: snapshot.executionId }, this.onTouchError, () => this.inner.save(snapshot));
+    }
+    loadLatest(executionId) {
+        return this.inner.loadLatest(executionId);
+    }
+    loadAt(executionId, sequence) {
+        return this.inner.loadAt(executionId, sequence);
+    }
+    loadLatestBefore(executionId, sequence) {
+        return this.inner.loadLatestBefore(executionId, sequence);
+    }
+    close() {
+        return this.inner.close();
+    }
+}
+exports.ContentTouchingSnapshotStore = ContentTouchingSnapshotStore;
+//# sourceMappingURL=ContentTouchingSnapshotStore.js.map

package/dist/ContentTouchingSnapshotStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContentTouchingSnapshotStore.js","sourceRoot":"","sources":["../src/ContentTouchingSnapshotStore.ts"],"names":[],"mappings":";;;AAuBA,wEAMC;AA7BD,2DAA8E;AAO9E,+CAAiE;AAEjE;;;GAGG;AACU,QAAA,+BAA+B,GAAkB,MAAM,CAAC,GAAG,CACtE,kDAAkD,CACnD,CAAC;AAEF;;;;;GAKG;AACH,SAAgB,8BAA8B,CAAC,KAAc;IAC3D,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAiC,CAAC,uCAA+B,CAAC,KAAK,IAAI,CAC7E,CAAC;AACJ,CAAC;AAOD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,4BAA4B;IAUpB;IACA;IAVV,eAAe,CAAiD;IAChE,gBAAgB,CAAkD;IAClE,cAAc,CAAgD;IAC9D,aAAa,CAA+C;IACrE,yDAAyD;IAChD,CAAC,uCAA+B,CAAC,GAAG,IAAI,CAAC;IACjC,YAAY,CAA6B;IAE1D,YACmB,KAAoB,EACpB,OAAoC,EACrD,UAA+C,EAAE;QAFhC,UAAK,GAAL,KAAK,CAAe;QACpB,YAAO,GAAP,OAAO,CAA6B;QAGrD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,MAAM,IAAI,GAAG;YACX,eAAe,EAAE,SAAS;YAC1B,gBAAgB,EAAE,SAAS;YAC3B,2FAA2F;YAC3F,uFAAuF;YACvF,8DAA8D;YAC9D,cAAc,EAAE,SAAS;YACzB,6DAA6D;YAC7D,aAAa,EAAE,SAAS;SAC2C,CAAC;QACtE,IAAA,+BAAe,EAA6C,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACjF,CAAC;IAED,IAAI,CAAC,QAAkB;QACrB,OAAO,IAAA,yBAAW,EAChB,IAAI,CAAC,OAAO,EACZ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAChB,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,EAChE,IAAI,CAAC,YAAY,EACjB,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAChC,CAAC;IACJ,CAAC;IAED,UAAU,CAAC,WAAmB;QAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,CAAC,WAAmB,EAAE,QAAgB;QAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC;IAED,gBAAgB,CAAC,WAAmB,EAAE,QAAgB;QACpD,OAAO,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF;AArDD,oEAqDC"}

package/dist/citations.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Visit every content address an event payload (or snapshot state) cites. Any object carrying a
+ * string `__loomContent` is a ref leaf — this covers bare ADR 0046
+ * `ContentRef`s (e.g. a finding's `evidence` list, an externalized field) AND
+ * the `ref` of an ADR 0054 claim-check envelope. `inEnvelope` is true ONLY for
+ * a RECLAIMABLE envelope's own `ref` — the offloaded value, the one citation whose
+ * erasure is replay-invisible (ADR 0055 D4). An envelope marked `retain: true` (ADR 0140:
+ * the opt-in agent claim-check, whose offloaded bytes are the ONLY copy of a tool output the
+ * log once held) reports its ref as load-bearing (`inEnvelope` false): kept while any live
+ * log, archive segment or snapshot cites it, freed only when that history is deleted. Every other envelope field (`digest` above
+ * all: orchestration branches on it) is recorded, replay-visible data and is
+ * walked in the envelope's own context like any other payload.
+ *
+ * Because the enveloped context never descends (the `ref` is a leaf), one
+ * WeakSet cycle guard suffices: an object aliased at a bare site and as an
+ * envelope's `ref` is still visited bare, since the envelope reports its ref
+ * directly rather than through the guard.
+ *
+ * Iterative with cycle detection: the sweep is a retention job over
+ * app-controlled payloads, so a pathologically deep (or, from an in-memory
+ * store, cyclic) value must not stack-overflow the pass (audit W8).
+ */
+export declare function visitCitedAddresses(value: unknown, visit: (address: string, inEnvelope: boolean) => void, 
+/**
+ * ADR 0140 D11 - when given, a `retain: true` envelope is honoured as load-bearing ONLY if it is in
+ * this set (see {@link retainRootsOf}); any other (a nested, tool-authored lookalike) stays reclaimable.
+ * Absent: every retained envelope is honoured (snapshots and archives, which pin everything anyway).
+ */
+trustedRetain?: ReadonlySet<object>): void;
+/**
+ * ADR 0140 D11 - the objects in an event payload where a retained envelope is TRUSTED: the top-level
+ * `output` of a `STEP_COMPLETED` (through a taint wrapper), exactly where the opt-in preset records its
+ * envelope. A `retain: true` lookalike nested inside a tool's result is tool-authored data: it cannot
+ * pin a blob.
+ */
+export declare function retainRootsOf(event: {
+    eventType: string;
+    payload: unknown;
+}): Set<object>;
+//# sourceMappingURL=citations.d.ts.map

package/dist/citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.d.ts","sourceRoot":"","sources":["../src/citations.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,KAAK,IAAI;AACrD;;;;GAIG;AACH,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAClC,IAAI,CAyCN;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAazF"}

package/dist/citations.js

@@ -0,0 +1,118 @@
+"use strict";
+// The ONE walker for "which blobs does this value cite" — shared by the mark phase of
+// `sweepUnpinnedContent` and by `ContentResolvingEventStore`, which touches what it carries
+// into a log without a `put` (ADR 0055 D6 amendment 2). Iterative + cycle-safe: neither a
+// retention job nor an append may stack-overflow on an app-controlled payload.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.visitCitedAddresses = visitCitedAddresses;
+exports.retainRootsOf = retainRootsOf;
+/**
+ * The structural claim-check test, identical to `isClaimCheck` in `@loomwork/middleware`
+ * (kept structural so this plugin takes no middleware dependency): the flag AND a string
+ * `ref.__loomContent`. An app object that merely carries the flag is app data.
+ */
+function envelopeRef(value) {
+    if (value.__loomClaimCheck !== true)
+        return undefined;
+    const address = value.ref?.__loomContent;
+    return typeof address === "string" ? address : undefined;
+}
+/** The address of an R5 media source `{ kind: "ref", ref: { address: string } }`, if `value` is one. */
+function mediaSourceAddress(value) {
+    if (value.kind !== "ref")
+        return undefined;
+    const address = value.ref?.address;
+    return typeof address === "string" ? address : undefined;
+}
+/**
+ * Visit every content address an event payload (or snapshot state) cites. Any object carrying a
+ * string `__loomContent` is a ref leaf — this covers bare ADR 0046
+ * `ContentRef`s (e.g. a finding's `evidence` list, an externalized field) AND
+ * the `ref` of an ADR 0054 claim-check envelope. `inEnvelope` is true ONLY for
+ * a RECLAIMABLE envelope's own `ref` — the offloaded value, the one citation whose
+ * erasure is replay-invisible (ADR 0055 D4). An envelope marked `retain: true` (ADR 0140:
+ * the opt-in agent claim-check, whose offloaded bytes are the ONLY copy of a tool output the
+ * log once held) reports its ref as load-bearing (`inEnvelope` false): kept while any live
+ * log, archive segment or snapshot cites it, freed only when that history is deleted. Every other envelope field (`digest` above
+ * all: orchestration branches on it) is recorded, replay-visible data and is
+ * walked in the envelope's own context like any other payload.
+ *
+ * Because the enveloped context never descends (the `ref` is a leaf), one
+ * WeakSet cycle guard suffices: an object aliased at a bare site and as an
+ * envelope's `ref` is still visited bare, since the envelope reports its ref
+ * directly rather than through the guard.
+ *
+ * Iterative with cycle detection: the sweep is a retention job over
+ * app-controlled payloads, so a pathologically deep (or, from an in-memory
+ * store, cyclic) value must not stack-overflow the pass (audit W8).
+ */
+function visitCitedAddresses(value, visit, 
+/**
+ * ADR 0140 D11 - when given, a `retain: true` envelope is honoured as load-bearing ONLY if it is in
+ * this set (see {@link retainRootsOf}); any other (a nested, tool-authored lookalike) stays reclaimable.
+ * Absent: every retained envelope is honoured (snapshots and archives, which pin everything anyway).
+ */
+trustedRetain) {
+    const stack = [value];
+    const seen = new WeakSet();
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (typeof current !== "object" || current === null)
+            continue;
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        const address = current.__loomContent;
+        if (typeof address === "string") {
+            visit(address, false);
+            continue;
+        }
+        if (Array.isArray(current)) {
+            for (const item of current)
+                stack.push(item);
+            continue;
+        }
+        // R5 (ADR 0120) — an LLM media source `{ kind: "ref", ref: { address } }` cites a blob by its
+        // address WITHOUT the `__loomContent` marker (deliberately: the resolving store would
+        // JSON-decode that marker). It is as load-bearing as a bare ref — a live model call resolves
+        // it, and erasing it makes the next call fail — so the mark phase must see it, or the sweep
+        // would reclaim media the transcript still cites.
+        const mediaAddress = mediaSourceAddress(current);
+        if (mediaAddress !== undefined) {
+            visit(mediaAddress, false);
+            continue;
+        }
+        const offloaded = envelopeRef(current);
+        // ADR 0140 - a RETAINED envelope's blob is audit evidence, not telemetry: load-bearing.
+        if (offloaded !== undefined) {
+            visit(offloaded, current.retain !== true ||
+                (trustedRetain !== undefined && !trustedRetain.has(current)));
+        }
+        for (const [key, item] of Object.entries(current)) {
+            if (offloaded !== undefined && key === "ref")
+                continue;
+            stack.push(item);
+        }
+    }
+}
+/**
+ * ADR 0140 D11 - the objects in an event payload where a retained envelope is TRUSTED: the top-level
+ * `output` of a `STEP_COMPLETED` (through a taint wrapper), exactly where the opt-in preset records its
+ * envelope. A `retain: true` lookalike nested inside a tool's result is tool-authored data: it cannot
+ * pin a blob.
+ */
+function retainRootsOf(event) {
+    const roots = new Set();
+    if (event.eventType !== "STEP_COMPLETED")
+        return roots;
+    let out = event.payload?.output;
+    if (typeof out === "object" &&
+        out !== null &&
+        out.__loomTainted !== undefined) {
+        out = out.value;
+    }
+    if (typeof out === "object" && out !== null)
+        roots.add(out);
+    return roots;
+}
+//# sourceMappingURL=citations.js.map

package/dist/citations.js.map

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

package/dist/content.bench.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=content.bench.d.ts.map

package/dist/content.bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.bench.d.ts","sourceRoot":"","sources":["../src/content.bench.ts"],"names":[],"mappings":""}

package/dist/content.bench.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const event_runtime_1 = require("@loomwork/event-runtime");
+const vitest_1 = require("vitest");
+const ContentResolvingEventStore_1 = require("./ContentResolvingEventStore");
+const ContentStore_1 = require("./ContentStore");
+// ── ADR 0062 guardrail bench — frozen-snapshot serving (TS-10) ────────────────
+//
+// 50 externalized refs (one dashboard's widgets) read through a backend with
+// ~2ms simulated round-trip latency. Compare: batched getMany (one round-trip)
+// vs the no-getMany fallback (coalesced parallel gets) vs the pre-ADR-0062
+// baseline shape (serialized per-ref awaits). Budget: p95 ≤ 150ms for ≤ 50 refs
+// — the batched path should sit near the single round-trip floor.
+const LATENCY_MS = 2;
+const WIDGETS = 50;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function withLatency(inner, supportsGetMany) {
+    const store = {
+        put: (bytes) => inner.put(bytes),
+        get: async (ref) => {
+            await sleep(LATENCY_MS);
+            return inner.get(ref);
+        },
+        delete: (ref) => inner.delete(ref),
+    };
+    if (supportsGetMany) {
+        store.getMany = async (refs) => {
+            await sleep(LATENCY_MS);
+            return inner.getMany(refs);
+        };
+    }
+    return store;
+}
+function envelope(sequence, payload) {
+    return {
+        id: `e-${sequence}`,
+        executionId: "x-1",
+        workflowId: "w-1",
+        eventType: "STEP_COMPLETED",
+        sequence,
+        timestamp: 1_000 + sequence,
+        payload,
+    };
+}
+async function seeded(supportsGetMany) {
+    const memory = new ContentStore_1.InMemoryContentStore();
+    const content = withLatency(memory, supportsGetMany);
+    const store = new ContentResolvingEventStore_1.ContentResolvingEventStore(new event_runtime_1.InMemoryAsyncEventStore(), content, {
+        externalize: { STEP_COMPLETED: ["output.doc"] },
+    });
+    for (let i = 0; i < WIDGETS; i++) {
+        await store.append(envelope(i, { stepId: `hydrate#${i}`, output: { doc: { widget: i } } }));
+    }
+    return store;
+}
+let batched;
+let fallback;
+(0, vitest_1.describe)(`resolve ${WIDGETS} refs @ ${LATENCY_MS}ms backend latency`, () => {
+    (0, vitest_1.bench)("getMany (one batched round-trip)", async () => {
+        batched ??= await seeded(true);
+        await batched.read("x-1");
+    });
+    (0, vitest_1.bench)("no getMany (coalesced parallel gets)", async () => {
+        fallback ??= await seeded(false);
+        await fallback.read("x-1");
+    });
+    (0, vitest_1.bench)("pre-ADR-0062 shape (serialized per-ref awaits — baseline)", async () => {
+        // The old resolver awaited object fields sequentially; emulate its
+        // round-trip profile directly against the latency store.
+        for (let i = 0; i < WIDGETS; i++) {
+            await sleep(LATENCY_MS);
+        }
+    });
+});
+//# sourceMappingURL=content.bench.js.map

package/dist/content.bench.js.map

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

package/dist/content.d.ts

@@ -0,0 +1,40 @@
+/** A content-addressed reference standing in for an externalized value in the log. */
+export interface ContentRef {
+    /** The content address, e.g. `"sha256:<hex>"`. Uniquely and deterministically names the bytes. */
+    readonly __loomContent: string;
+    /** Byte length of the stored content (informational). */
+    readonly size?: number;
+    /** How the bytes decode back to a value (only `"json"` today). */
+    readonly codec?: string;
+}
+export declare function isContentRef(value: unknown): value is ContentRef;
+/** The content address of some bytes: `sha256:<hex>`. Pure — the same bytes always map here. */
+export declare function contentAddress(bytes: Uint8Array): string;
+/** Encode a value to bytes for the content store (JSON — the only codec today). */
+export declare function encodeValue(value: unknown): Uint8Array;
+/** Decode content-store bytes back to the original value. */
+export declare function decodeValue(bytes: Uint8Array): unknown;
+/** Whether a payload carries any {@link ContentRef} (the read-side fast path). */
+export declare function hasContentRef(value: unknown): boolean;
+/**
+ * ADR 0062 — phase 1 of batched resolution: collect every {@link ContentRef} in
+ * a payload into `into` (keyed by content address — duplicates collapse), and
+ * report whether any was found. One walk replaces the old `hasContentRef`
+ * pre-walk + per-ref fetch recursion.
+ */
+export declare function collectContentRefs(value: unknown, into: Map<string, ContentRef>): boolean;
+/**
+ * ADR 0062 — phase 2 of batched resolution: pure rebuild substituting each
+ * {@link ContentRef} from the fetched bytes. Decoding is deliberately
+ * per-OCCURRENCE (the fetch dedupes by address — the expensive part — but two
+ * payload sites never alias one decoded object). Ref-free subtrees are returned
+ * as-is (structural sharing).
+ */
+export declare function substituteContentRefs(value: unknown, bytesByAddress: ReadonlyMap<string, Uint8Array>): unknown;
+/**
+ * Async structural path-mapper — like the crypto plugin's `mapPaths`, but the transform is
+ * awaited (a content `put` is async). Copies only the spine it touches (structural sharing
+ * elsewhere), never mutates `root`, and skips absent paths.
+ */
+export declare function mapPathsAsync(root: unknown, paths: readonly string[], transform: (value: unknown) => Promise<unknown>): Promise<unknown>;
+//# sourceMappingURL=content.d.ts.map

package/dist/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"AAWA,sFAAsF;AACtF,MAAM,WAAW,UAAU;IACzB,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAMhE;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAExD;AAOD,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAEtD;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAEtD;AAuBD,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQrD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,OAAO,CAmBzF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,GAC9C,OAAO,CA6BT;AAQD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAC9C,OAAO,CAAC,OAAO,CAAC,CA0BlB"}

package/dist/content.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isContentRef = isContentRef;
+exports.contentAddress = contentAddress;
+exports.encodeValue = encodeValue;
+exports.decodeValue = decodeValue;
+exports.hasContentRef = hasContentRef;
+exports.collectContentRefs = collectContentRefs;
+exports.substituteContentRefs = substituteContentRefs;
+exports.mapPathsAsync = mapPathsAsync;
+const node_crypto_1 = require("node:crypto");
+const classify_1 = require("@loomwork/classify");
+function isContentRef(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.__loomContent === "string");
+}
+/** The content address of some bytes: `sha256:<hex>`. Pure — the same bytes always map here. */
+function contentAddress(bytes) {
+    return `sha256:${(0, node_crypto_1.createHash)("sha256").update(bytes).digest("hex")}`;
+}
+// Stateless for whole-input encode/decode — hoisted (audit nit: decodeValue runs
+// per ref occurrence during substitution, incl. the live tail).
+const UTF8_ENCODER = new TextEncoder();
+const UTF8_DECODER = new TextDecoder();
+/** Encode a value to bytes for the content store (JSON — the only codec today). */
+function encodeValue(value) {
+    return UTF8_ENCODER.encode(JSON.stringify(value));
+}
+/** Decode content-store bytes back to the original value. */
+function decodeValue(bytes) {
+    return JSON.parse(UTF8_DECODER.decode(bytes));
+}
+/**
+ * An ADR 0054 claim-check envelope, recognised structurally with the same test as
+ * `@loomwork/middleware`'s `isClaimCheck` (`__loomClaimCheck === true` AND a string
+ * `ref.__loomContent`), so this plugin takes no dependency for it (ADR 0055 D3).
+ *
+ * The read-side walkers below treat one as a LEAF. An envelope is resolved only by the
+ * claim-check plugin (`resolveClaimCheck`): its `ref` is a TTL-reclaimable citation whose
+ * erasure the fold never sees, and its bytes may not be JSON (`codec: "bytes"`). Descending
+ * into it replaced `ref` with the decoded value, threw `ContentMissingError` once the sweep
+ * had reclaimed the blob, and failed outright on a binary one (ADR 0055 D4's known gap).
+ */
+function isClaimCheckEnvelope(value) {
+    const v = value;
+    return (v.__loomClaimCheck === true &&
+        typeof v.ref === "object" &&
+        v.ref !== null &&
+        typeof v.ref.__loomContent === "string");
+}
+/** Whether a payload carries any {@link ContentRef} (the read-side fast path). */
+function hasContentRef(value) {
+    if (isContentRef(value))
+        return true;
+    if (Array.isArray(value))
+        return value.some(hasContentRef);
+    if (typeof value === "object" && value !== null) {
+        if (isClaimCheckEnvelope(value))
+            return false; // the claim-check plugin's to resolve
+        return Object.values(value).some(hasContentRef);
+    }
+    return false;
+}
+/**
+ * ADR 0062 — phase 1 of batched resolution: collect every {@link ContentRef} in
+ * a payload into `into` (keyed by content address — duplicates collapse), and
+ * report whether any was found. One walk replaces the old `hasContentRef`
+ * pre-walk + per-ref fetch recursion.
+ */
+function collectContentRefs(value, into) {
+    if (isContentRef(value)) {
+        if (!into.has(value.__loomContent))
+            into.set(value.__loomContent, value);
+        return true;
+    }
+    if (Array.isArray(value)) {
+        let found = false;
+        for (const v of value)
+            if (collectContentRefs(v, into))
+                found = true;
+        return found;
+    }
+    if (typeof value === "object" && value !== null) {
+        if (isClaimCheckEnvelope(value))
+            return false; // a leaf: see isClaimCheckEnvelope
+        let found = false;
+        for (const v of Object.values(value)) {
+            if (collectContentRefs(v, into))
+                found = true;
+        }
+        return found;
+    }
+    return false;
+}
+/**
+ * ADR 0062 — phase 2 of batched resolution: pure rebuild substituting each
+ * {@link ContentRef} from the fetched bytes. Decoding is deliberately
+ * per-OCCURRENCE (the fetch dedupes by address — the expensive part — but two
+ * payload sites never alias one decoded object). Ref-free subtrees are returned
+ * as-is (structural sharing).
+ */
+function substituteContentRefs(value, bytesByAddress) {
+    if (isContentRef(value)) {
+        const bytes = bytesByAddress.get(value.__loomContent);
+        // Callers guarantee every collected address was fetched; a miss here is a
+        // programming error, surfaced loudly.
+        if (bytes === undefined)
+            throw new Error(`unfetched content ref: ${value.__loomContent}`);
+        return decodeValue(bytes);
+    }
+    if (Array.isArray(value)) {
+        let changed = false;
+        const out = value.map((v) => {
+            const r = substituteContentRefs(v, bytesByAddress);
+            if (r !== v)
+                changed = true;
+            return r;
+        });
+        return changed ? out : value;
+    }
+    if (typeof value === "object" && value !== null) {
+        if (isClaimCheckEnvelope(value))
+            return value; // a leaf: see isClaimCheckEnvelope
+        let changed = false;
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            const r = substituteContentRefs(v, bytesByAddress);
+            out[k] = r;
+            if (r !== v)
+                changed = true;
+        }
+        return changed ? out : value;
+    }
+    return value;
+}
+function shallowCopy(value) {
+    return Array.isArray(value)
+        ? [...value]
+        : { ...value };
+}
+/**
+ * Async structural path-mapper — like the crypto plugin's `mapPaths`, but the transform is
+ * awaited (a content `put` is async). Copies only the spine it touches (structural sharing
+ * elsewhere), never mutates `root`, and skips absent paths.
+ */
+async function mapPathsAsync(root, paths, transform) {
+    if (paths.length === 0 || typeof root !== "object" || root === null)
+        return root;
+    // `[]` segments are resolved against the concrete value first, so a mark inside an array
+    // element reaches every element (#260). Paths without one pass through untouched.
+    const targets = (0, classify_1.hasWildcard)(paths) ? (0, classify_1.expandPaths)(root, paths) : paths;
+    const out = shallowCopy(root);
+    for (const path of targets) {
+        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;
+            }
+            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] = await transform(src[leaf]);
+    }
+    return out;
+}
+//# sourceMappingURL=content.js.map

package/dist/content.js.map

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