@loomwork/plugin-content 0.0.0-stage → 0.1.1

package/dist/ContentResolvingEventStore.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentResolvingEventStore = void 0;
+const event_runtime_1 = require("@loomwork/event-runtime");
+const content_1 = require("./content");
+const errors_1 = require("./errors");
+const touchAround_1 = require("./touchAround");
+/**
+ * ADR 0046 — wraps any {@link EventStore} so marked payload fields are stored in a
+ * {@link ContentStore} (as content-addressed refs) instead of inline in the log. Reads resolve
+ * refs back transparently, so the fold, resume, and every consumer above the store layer see
+ * plain values — the authoritative log holds only references + structure.
+ *
+ * Mirrors `EncryptingEventStore`: a store decorator, optional capabilities forwarded so it
+ * composes with fork/fencing. `copyPrefix` copies refs verbatim — because refs are
+ * content-addressed, a fork *shares* the parent's blobs for free (natural dedup), with no
+ * re-wrap needed. A read of an execution whose externalized bytes were erased throws
+ * {@link ContentMissingError} — replay fails loudly, never silently diverges (G1).
+ *
+ * **Composing with `@loomwork/plugin-audit-chain`:** wrap this store INSIDE the hash chain —
+ * `hashChainedEventStore(new ContentResolvingEventStore(...))`. Chained the other way round
+ * the chain hashes only the ref string, so a rewritten blob verifies clean. See
+ * `hashChainedEventStore`'s note and `contentOrdering.test.ts`.
+ *
+ * **Claim-check envelopes are left alone.** An ADR 0054 envelope (`__loomClaimCheck`) is read
+ * back verbatim — its `ref` is resolved only by the claim-check plugin, it may be reclaimed on a
+ * TTL (ADR 0055 D4), and its bytes need not be JSON. A bare ref beside it still resolves.
+ *
+ * **Reclamation:** `deleteExecution`/`truncatePrefix` remove the log's events but do NOT
+ * delete the referenced blobs — forks share content, so a blob outlives any one log. Blobs are
+ * reclaimed by the separate mark-and-sweep `sweepUnpinnedContent` (ADR 0055, which closed the
+ * ADR 0046 "refcounted blob GC" follow-up); erase one explicitly via `contentStore.delete(ref)`.
+ */
+/**
+ * Own-key lookup for a caller-controlled event type. Plain indexing would resolve
+ * `"__proto__"`/`"constructor"` up the prototype chain to a truthy non-config value, which then
+ * flows into code expecting an array (or a function). An unrecognised event type must be a
+ * no-op whatever it is named.
+ */
+function pathsFor(map, eventType) {
+    return Object.hasOwn(map, eventType) ? map[eventType] : undefined;
+}
+class ContentResolvingEventStore {
+    inner;
+    content;
+    externalize;
+    onTouchError;
+    appendBatch;
+    head;
+    readRange;
+    acquireFence;
+    acquireFenceIf;
+    appendIfUnchanged;
+    storeNow;
+    sealingCapability;
+    readAtRest;
+    copyPrefix;
+    deleteExecution;
+    deleteThrough;
+    truncatePrefix;
+    truncatePrefixKeeping;
+    listExecutions;
+    listExecutionsPage;
+    constructor(inner, content, options) {
+        this.inner = inner;
+        this.content = content;
+        // ADR 0143: a sealing store needs the owning execution on every put/get, and ADR 0046 externalization
+        // resolves a read BATCH across executions without carrying it. Refuse rather than seal under a guess
+        // (the claim-check path, which has the execution, is the one that works over a sealing store).
+        if (content.sealsContent === true) {
+            throw new TypeError("ContentResolvingEventStore: this content store seals per subject (sealsContent: true), which ADR 0046 externalization cannot drive (it does not carry the owning execution into put/get). Use a plain store here, or offload through execution.claimCheck.");
+        }
+        this.externalize = options.externalize;
+        this.onTouchError = options.onTouchError;
+        // Every optional method decided over the whole union (ADR 0074 Amendment), each
+        // installed only when the inner store has it.
+        const plan = {
+            // Externalize every envelope concurrently, then ONE round-trip. Puts are
+            // content-addressed and idempotent, so a blob orphaned by a failed batch is exactly
+            // what a failed `append` orphans today (and the sweep reclaims it). `Promise.all`
+            // keeps array order, the SPI's per-execution order.
+            appendBatch: async (envelopes) => this.touching(envelopes.map((e) => e.payload), { operation: "appendBatch", executionId: envelopes[0]?.executionId }, async () => inner.appendBatch(await Promise.all(envelopes.map((e) => this.externalizeEnvelope(e))))),
+            // A tip is a sequence number — no payload to resolve, so it forwards unchanged.
+            head: "forward",
+            readRange: (executionId, from, to) => inner.readRange(executionId, from, to).then((evs) => this.resolveAll(executionId, evs)),
+            acquireFence: "forward",
+            acquireFenceIf: "forward",
+            // The blob is written BEFORE the store can say no, and a content-addressed blob may be
+            // shared with other events (so deleting it on a refusal could break them). So the
+            // externalisation happens only after a lock-free observation says the condition still
+            // holds: a late write that already lost (the common case) stores no blob at all. What is
+            // left is the window between the observation and the write, whose orphan is reclaimed by
+            // `sweepUnpinnedContent` exactly like a plain `append` that failed after its `put`.
+            appendIfUnchanged: async (executionId, event, expect) => {
+                if (event === null)
+                    return inner.appendIfUnchanged(executionId, null, expect);
+                const paths = pathsFor(this.externalize, event.eventType);
+                if (paths !== undefined && paths.length > 0 && expect !== undefined) {
+                    const now = await inner.appendIfUnchanged(executionId, null);
+                    if (!now.appended &&
+                        (now.reason === "gone" ||
+                            now.head !== expect.head ||
+                            now.fence !== expect.fence ||
+                            now.anchor !== expect.anchor ||
+                            event.sequence !== expect.head + 1)) {
+                        return now.reason === "gone"
+                            ? now
+                            : {
+                                appended: false,
+                                reason: "moved",
+                                head: now.head,
+                                fence: now.fence,
+                                anchor: now.anchor,
+                            };
+                    }
+                }
+                return this.touching([event.payload], { operation: "appendIfUnchanged", executionId }, async () => inner.appendIfUnchanged(executionId, await this.externalizeEnvelope(event), expect));
+            },
+            storeNow: "forward", // a clock reading: no envelope to externalise
+            sealingCapability: "forward", // externalising refs seals nothing
+            readAtRest: "forward",
+            // Refs are content-addressed: copying them verbatim makes the fork share the parent's
+            // blobs (dedup for free) — no decrypt/re-wrap step (contrast the crypto plugin's keys).
+            // But a verbatim copy is a citation with NO `put`, invisible to the orphan sweep's
+            // conditional delete, so over a store with SPI 1.4.0 `touch` the copied range's refs are
+            // touched around the copy (ADR 0055 D6 amendment 2). The range is read raw (unresolved).
+            copyPrefix: content.touch === undefined
+                ? "forward"
+                : async (fromExecutionId, toExecutionId, throughSequence, metadata) => {
+                    const copied = await (0, event_runtime_1.readRangeOf)(inner, fromExecutionId, 0, throughSequence);
+                    return this.touching(copied.map((e) => e.payload), { operation: "copyPrefix", executionId: toExecutionId }, () => inner.copyPrefix(fromExecutionId, toExecutionId, throughSequence, metadata));
+                },
+            // Forwarded so a content-wrapped store keeps its retention/compaction capabilities.
+            // These reclaim EVENTS only; blob reclamation is separate (see the class note).
+            deleteExecution: "forward",
+            deleteThrough: "forward",
+            truncatePrefix: "forward",
+            truncatePrefixKeeping: "forward",
+            // Enumeration is over executionIds only — no payload, so no resolution needed.
+            listExecutions: "forward",
+            listExecutionsPage: "forward",
+        };
+        (0, event_runtime_1.installOptional)(this, inner, plan);
+    }
+    async externalizeEnvelope(envelope) {
+        const paths = pathsFor(this.externalize, envelope.eventType);
+        if (paths === undefined || paths.length === 0)
+            return envelope; // unmarked → verbatim (G2)
+        const payload = await (0, content_1.mapPathsAsync)(envelope.payload, paths, (v) => this.externalizeValue(v));
+        return { ...envelope, payload };
+    }
+    async append(envelope) {
+        return this.touching([envelope.payload], { operation: "append", executionId: envelope.executionId }, async () => this.inner.append(await this.externalizeEnvelope(envelope)));
+    }
+    /**
+     * SPI 1.4.0 (ADR 0055 D6 amendment 2) — a ref that reaches a log WITHOUT a `put` (one an
+     * incoming payload already carries: a recalled memory value, a `scriptRef`, a ref handed
+     * between steps) is a citation the orphan sweep's conditional delete cannot see. So, when the
+     * content store can `touch`, the payloads' cited addresses are touched BEFORE the write (a
+     * failure aborts it, nothing landed) and again AFTER it (best-effort and reported through
+     * `onTouchError`: the write is durable, so its outcome must not be turned into a failure).
+     * The guarantee is D5's: the BEFORE touch protects a write whose touch-to-commit window is
+     * shorter than the sweep's margin (`touchClock() - cutoff`, which an erasing orphan pass
+     * requires to be at least 60 s); the AFTER touch only extends that for a slower write. See
+     * {@link touchAround}. Refs externalized by THIS write are not in the INPUT payloads (their
+     * `put` is the touch). Cost: with no `touch` on the store, nothing (the closure is the
+     * write); otherwise one iterative cycle-safe walk of the input payload (no recursion; the same
+     * walker the sweep's mark phase uses), and a round trip only when a ref was found.
+     */
+    touching(payloads, ctx, write) {
+        return (0, touchAround_1.touchAround)(this.content, payloads, ctx, this.onTouchError, write);
+    }
+    async externalizeValue(value) {
+        const ref = await this.content.put((0, content_1.encodeValue)(value));
+        return { ...ref, codec: "json" };
+    }
+    async read(executionId) {
+        return this.resolveAll(executionId, await this.inner.read(executionId));
+    }
+    async readFrom(executionId, fromSequence) {
+        return this.resolveAll(executionId, await this.inner.readFrom(executionId, fromSequence));
+    }
+    // ADR 0062 — batch-scoped two-phase resolution. Phase 1 collects DISTINCT refs
+    // across the WHOLE read batch (one walk, dedupe by content address); the fetch
+    // is ONE `getMany` round-trip when the store supports it (coalesced parallel
+    // `get`s otherwise — still strictly better than the old per-ref sequential
+    // awaits); phase 2 is a pure synchronous substitute pass. O(payload nodes) +
+    // one round-trip replaces O(refs) serialized round-trips. Fast path: no event
+    // carries a ref → verbatim, no allocation.
+    async resolveAll(executionId, events) {
+        const distinct = new Map();
+        const refBearing = events.map((e) => (0, content_1.collectContentRefs)(e.payload, distinct));
+        if (distinct.size === 0)
+            return events;
+        const bytesByAddress = await this.fetchBytes(distinct, executionId);
+        return events.map((e, i) => refBearing[i] ? { ...e, payload: (0, content_1.substituteContentRefs)(e.payload, bytesByAddress) } : e);
+    }
+    /** Fetch all distinct refs; loudness contract unchanged (missing ⇒ ContentMissingError, G1). */
+    async fetchBytes(distinct, executionId) {
+        // Single pass over the map (audit nit): addresses and refs stay index-aligned.
+        const addresses = new Array(distinct.size);
+        const refs = new Array(distinct.size);
+        let n = 0;
+        for (const [address, ref] of distinct) {
+            addresses[n] = address;
+            refs[n] = ref;
+            n++;
+        }
+        const fetched = this.content.getMany !== undefined
+            ? await this.content.getMany(refs)
+            : await Promise.all(refs.map((r) => this.content.get(r)));
+        const out = new Map();
+        for (let i = 0; i < addresses.length; i++) {
+            const bytes = fetched[i];
+            if (bytes === null || bytes === undefined) {
+                throw new errors_1.ContentMissingError(addresses[i], executionId);
+            }
+            out.set(addresses[i], bytes);
+        }
+        return out;
+    }
+    async subscribe(executionId, handler) {
+        // Live subscribers get resolved events too (best-effort: if resolution fails — e.g. a race
+        // with erasure — the raw ref-bearing event is delivered rather than dropping it).
+        // Audit PERF-A1 — the ref-free common case (heartbeats, STEP_STARTED, decisions)
+        // pays the zero-allocation `hasContentRef` walk only; the Map is allocated
+        // exclusively for ref-bearing events.
+        return this.inner.subscribe(executionId, (event) => {
+            if (!(0, content_1.hasContentRef)(event.payload)) {
+                handler(event);
+                return;
+            }
+            const distinct = new Map();
+            (0, content_1.collectContentRefs)(event.payload, distinct);
+            void this.fetchBytes(distinct, executionId)
+                .then((bytes) => handler({ ...event, payload: (0, content_1.substituteContentRefs)(event.payload, bytes) }))
+                .catch(() => handler(event));
+        });
+    }
+    async close() {
+        return this.inner.close();
+    }
+}
+exports.ContentResolvingEventStore = ContentResolvingEventStore;
+//# sourceMappingURL=ContentResolvingEventStore.js.map

package/dist/ContentResolvingEventStore.js.map

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

package/dist/ContentStore.d.ts

@@ -0,0 +1,186 @@
+import { type ContentRef } from "./content";
+/**
+ * ContentStore SPI version (introduced retroactively by ADR 0062 — the SPI had
+ * shipped two revisions without a version anchor for conformance to pin).
+ *  - 1.0.0: `put`/`get`/`delete` (ADR 0046).
+ *  - 1.1.0: optional `putStream` (ST-1, ADR 0059).
+ *  - 1.2.0: optional `getMany` (TS-10, ADR 0062 — batched interactive reads).
+ *  - 1.3.0: optional `deleteIfUntouchedSince` + `listPage` + `touchClock`, implemented all
+ *    three or none, and a per-blob touch time that every `put`/`putStream` bumps,
+ *    monotonically (ADR 0055 D5/D6 — the race-safe, orphan-reclaiming sweep).
+ *  - 1.4.0: optional `touch` — bump touch times WITHOUT a put, so a citation that enters a log
+ *    without one (a fork's `copyPrefix`, a ref an `append` carries) is visible to the
+ *    conditional delete; `reclaimOrphans` requires it (ADR 0055 D6 amendment 2).
+ *  - 1.5.0: an optional {@link ContentAccess} argument on `put`/`putStream`/`get`/`getMany` (the execution a
+ *    blob belongs to) and the optional `sealsContent` marker, so a store can seal each blob under its
+ *    owner's subject key (ADR 0143). A plain store ignores the argument; nothing else changes.
+ */
+export declare const CONTENT_STORE_SPI_VERSION = "1.5.0";
+/**
+ * ADR 0143 - WHO a content operation is for: the execution that offloads (`put`) or reads (`get`) the blob.
+ * It is the same pair every event-store `subjectOf` takes, so a sealing store maps it to the erasure subject
+ * with the mapping the log already uses. A plain store ignores it. A store that seals
+ * ({@link ContentStore.sealsContent}) REFUSES a call without it (fail closed).
+ */
+export interface ContentAccess {
+    readonly executionId: string;
+    readonly workflowId: string;
+}
+/** One blob as {@link ContentStore.listPage} reports it (SPI 1.3.0). */
+export interface ContentPageEntry {
+    address: string;
+    /** Epoch ms of the blob's last `put`/`putStream`, by the STORE's clock. */
+    touchedAt: number;
+}
+/** Options for {@link ContentStore.listPage} (SPI 1.3.0). */
+export interface ContentListPageOptions {
+    /** Resume after this address: the previous page's `nextCursor`. Absent = from the start. */
+    cursor?: string;
+    /**
+     * Page size. MUST be a positive integer (anything else rejects with a `RangeError`, never
+     * "no limit"); a store MAY return fewer. Default {@link CONTENT_LIST_PAGE_DEFAULT_LIMIT},
+     * clamped to {@link CONTENT_LIST_PAGE_MAX_LIMIT}.
+     */
+    limit?: number;
+    /** Only blobs whose touch time is strictly before this (epoch ms). */
+    touchedBefore?: number;
+}
+/** One page of {@link ContentStore.listPage}. `nextCursor` absent = the scan is complete. */
+export interface ContentListPage {
+    entries: ContentPageEntry[];
+    nextCursor?: string;
+}
+export declare const CONTENT_LIST_PAGE_DEFAULT_LIMIT = 500;
+export declare const CONTENT_LIST_PAGE_MAX_LIMIT = 10000;
+/**
+ * Validate and clamp a `listPage` limit (shared by the reference stores so a 3P backend has
+ * one rule to copy). Rejects rather than defaulting: SQLite reads `LIMIT -1` as NO limit.
+ */
+export declare function contentListPageLimit(limit: number | undefined): number;
+export interface ContentStore {
+    /**
+     * ADR 0143 - `true` for a store that SEALS each blob under its owning subject's key (so a crypto-shred of
+     * the subject makes every blob it holds unreadable). `defineConfig` accepts `execution.claimCheck` with
+     * `security.crypto` only for such a store, and erasure treats the shred as erasing its blobs. Absent/false:
+     * a plain store whose bytes sit in the clear.
+     */
+    readonly sealsContent?: boolean;
+    /**
+     * OPTIONAL, for a store that {@link sealsContent} (SPI 1.5.0, ADR 0143 D5) - the OWNERSHIP PROOF: does the
+     * blob at `ref` authenticate under `access`'s subject key (decrypt and discard)? A citation in a log is not
+     * ownership; erasure and export ask before they delete or open a cited blob. `false` for an absent blob or
+     * one that does not open under this subject; REJECTS when it cannot decide (the key is destroyed or not on
+     * this node). A store that seals and lacks it makes erasure REFUSE a subject that cites blobs.
+     */
+    ownedBy?(ref: ContentRef, access: ContentAccess): Promise<boolean>;
+    /**
+     * Store bytes, returning their content-addressed ref. Idempotent by hash (stored once).
+     * `access` (SPI 1.5.0, ADR 0143) names the owning execution; a plain store ignores it.
+     */
+    put(bytes: Uint8Array, access?: ContentAccess): Promise<ContentRef>;
+    /**
+     * OPTIONAL (ST-1, ADR 0059) — store a byte STREAM without materializing it in
+     * the caller's memory. Contract: the returned ref MUST be the content address
+     * of the full streamed sequence, idempotent by that address, exactly as if
+     * `put(concat(chunks))` had been called. HOW the backend achieves it is its
+     * business — the reference approach hashes while spooling; an object-store
+     * backend that cannot address before completion may hash-while-upload and
+     * verify (or re-key) on finalize (resolves requirements §6.3). Node
+     * `Readable` streams satisfy `AsyncIterable<Uint8Array>` directly.
+     */
+    putStream?(stream: AsyncIterable<Uint8Array>, access?: ContentAccess): Promise<ContentRef>;
+    /** Resolve a ref to its bytes, or `null` if erased/absent — MUST NOT throw on absence. */
+    get(ref: ContentRef, access?: ContentAccess): Promise<Uint8Array | null>;
+    /**
+     * OPTIONAL (TS-10, ADR 0062) — batched get for interactive read paths (e.g.
+     * frozen-snapshot serving: many refs, one human waiting). Result is
+     * positionally aligned with `refs`; `null` per absent entry; MUST NOT throw
+     * on absence. Duplicate refs are legal and resolve identically. Semantics are
+     * exactly element-wise `get` — only the round-trip count may differ.
+     */
+    getMany?(refs: readonly ContentRef[], access?: ContentAccess): Promise<(Uint8Array | null)[]>;
+    /** Physically erase the bytes. Idempotent; referential integrity is the caller's concern. */
+    delete(ref: ContentRef): Promise<void>;
+    /**
+     * OPTIONAL (SPI 1.3.0, ADR 0055 D5) — erase the blob only if its touch time is strictly
+     * before `cutoffMs`, as ONE atomic operation (a single conditional `DELETE`, never a read
+     * followed by a delete). Resolves `true` iff it deleted; `false` for a touched or absent
+     * blob, never a throw.
+     *
+     * A store that implements this MUST bump the blob's touch time on EVERY `put`/`putStream`,
+     * including a put of bytes it already holds (`ON CONFLICT … DO UPDATE`, not
+     * `INSERT OR IGNORE`). A dedup'd put is a re-citation the log has not recorded yet; the
+     * touch is how the sweep learns of it.
+     */
+    deleteIfUntouchedSince?(ref: ContentRef, cutoffMs: number): Promise<boolean>;
+    /**
+     * OPTIONAL (SPI 1.3.0, ADR 0055 D6) — enumerate blobs, keyset-paged ascending by address,
+     * so a scan uses bounded memory and deleting entries mid-scan never skips a survivor.
+     * Every blob present for the whole scan is returned exactly once. Implement together
+     * with {@link deleteIfUntouchedSince}: the orphan pass requires both.
+     */
+    listPage?(opts: ContentListPageOptions): Promise<ContentListPage>;
+    /**
+     * OPTIONAL (SPI 1.3.0, ADR 0055 D5) — the current time on the clock this store stamps touch
+     * times with (a database server's `now()`, the process clock of an embedded store). The
+     * sweep derives its guard cutoff from it, so the guard never compares a log-time instant
+     * with a store-time touch.
+     *
+     * The three 1.3.0 methods come as a set: a store implements all of `deleteIfUntouchedSince`,
+     * `listPage` and `touchClock`, or none of them (the conformance kit fails a partial set).
+     * The touch time never moves backwards: a put under a clock that stepped back keeps the
+     * later time. `0` means UNKNOWN (a pre-1.3.0 writer's column default) and is never
+     * orphan-eligible.
+     */
+    touchClock?(): Promise<number>;
+    /**
+     * OPTIONAL (SPI 1.4.0, ADR 0055 D6 amendment 2) — bump the touch time of every listed blob
+     * to the store clock, as one batch, WITHOUT a `put`. It is how a citation that enters a log
+     * with no `put` (a fork copying refs verbatim, an `append` carrying a ref already in its
+     * payload) tells the conditional delete "this was re-cited now".
+     *
+     * Same semantics as a `put` of bytes the store holds: the time never moves backwards (max).
+     * An address the store does not hold is a NO-OP, never a throw and never an insert; the
+     * promise resolves with those missing addresses (empty when all were present) so a caller
+     * can notice a dangling ref early. Duplicates are legal. An empty list does nothing.
+     *
+     * Implement it with the 1.3.0 set; `sweepUnpinnedContent({ reclaimOrphans })` refuses to
+     * erase through a store that lacks it (the race it closes would otherwise be open).
+     */
+    touch?(addresses: readonly string[]): Promise<string[]>;
+}
+/** Options for {@link InMemoryContentStore}. */
+export interface InMemoryContentStoreOptions {
+    /** Clock for touch times (epoch ms). Default `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Reference in-memory {@link ContentStore} (tests / ephemeral apps). Content-addressed, so a
+ * repeated `put` of identical bytes stores one blob — dedup is visible via {@link size} — and
+ * bumps that blob's touch time (SPI 1.3.0).
+ */
+export declare class InMemoryContentStore implements ContentStore {
+    private readonly blobs;
+    /**
+     * Addresses in ascending order for `listPage`'s keyset scan, rebuilt lazily: only a NEW
+     * address invalidates it (O(1) per put), a delete leaves a stale entry the scan skips, so a
+     * sweep deleting while it pages sorts once — O(n log n) per scan, O(log n + limit) per page.
+     */
+    private sorted;
+    private sortedStale;
+    private readonly now;
+    constructor(options?: InMemoryContentStoreOptions);
+    put(bytes: Uint8Array): Promise<ContentRef>;
+    putStream(stream: AsyncIterable<Uint8Array>): Promise<ContentRef>;
+    get(ref: ContentRef): Promise<Uint8Array | null>;
+    getMany(refs: readonly ContentRef[]): Promise<(Uint8Array | null)[]>;
+    delete(ref: ContentRef): Promise<void>;
+    deleteIfUntouchedSince(ref: ContentRef, cutoffMs: number): Promise<boolean>;
+    touchClock(): Promise<number>;
+    touch(addresses: readonly string[]): Promise<string[]>;
+    listPage(opts?: ContentListPageOptions): Promise<ContentListPage>;
+    /** Number of distinct blobs stored — makes content-addressed dedup observable in tests. */
+    get size(): number;
+    private store;
+}
+//# sourceMappingURL=ContentStore.d.ts.map

package/dist/ContentStore.d.ts.map

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

package/dist/ContentStore.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryContentStore = exports.CONTENT_LIST_PAGE_MAX_LIMIT = exports.CONTENT_LIST_PAGE_DEFAULT_LIMIT = exports.CONTENT_STORE_SPI_VERSION = void 0;
+exports.contentListPageLimit = contentListPageLimit;
+const node_crypto_1 = require("node:crypto");
+const content_1 = require("./content");
+// ── ADR 0046 — the ContentStore SPI ───────────────────────────────────────────
+//
+// A key→blob store for externalized payload bytes, addressed by content hash. Back it with
+// object storage / a filesystem / an encrypted blob store in production (as separate
+// `@loomwork/plugin-content-*` backends); the reference implementation here is in-memory.
+/**
+ * ContentStore SPI version (introduced retroactively by ADR 0062 — the SPI had
+ * shipped two revisions without a version anchor for conformance to pin).
+ *  - 1.0.0: `put`/`get`/`delete` (ADR 0046).
+ *  - 1.1.0: optional `putStream` (ST-1, ADR 0059).
+ *  - 1.2.0: optional `getMany` (TS-10, ADR 0062 — batched interactive reads).
+ *  - 1.3.0: optional `deleteIfUntouchedSince` + `listPage` + `touchClock`, implemented all
+ *    three or none, and a per-blob touch time that every `put`/`putStream` bumps,
+ *    monotonically (ADR 0055 D5/D6 — the race-safe, orphan-reclaiming sweep).
+ *  - 1.4.0: optional `touch` — bump touch times WITHOUT a put, so a citation that enters a log
+ *    without one (a fork's `copyPrefix`, a ref an `append` carries) is visible to the
+ *    conditional delete; `reclaimOrphans` requires it (ADR 0055 D6 amendment 2).
+ *  - 1.5.0: an optional {@link ContentAccess} argument on `put`/`putStream`/`get`/`getMany` (the execution a
+ *    blob belongs to) and the optional `sealsContent` marker, so a store can seal each blob under its
+ *    owner's subject key (ADR 0143). A plain store ignores the argument; nothing else changes.
+ */
+exports.CONTENT_STORE_SPI_VERSION = "1.5.0";
+exports.CONTENT_LIST_PAGE_DEFAULT_LIMIT = 500;
+exports.CONTENT_LIST_PAGE_MAX_LIMIT = 10_000;
+/**
+ * Validate and clamp a `listPage` limit (shared by the reference stores so a 3P backend has
+ * one rule to copy). Rejects rather than defaulting: SQLite reads `LIMIT -1` as NO limit.
+ */
+function contentListPageLimit(limit) {
+    if (limit === undefined)
+        return exports.CONTENT_LIST_PAGE_DEFAULT_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new RangeError(`listPage: limit must be a positive integer, got ${limit}`);
+    }
+    return Math.min(limit, exports.CONTENT_LIST_PAGE_MAX_LIMIT);
+}
+/**
+ * Reference in-memory {@link ContentStore} (tests / ephemeral apps). Content-addressed, so a
+ * repeated `put` of identical bytes stores one blob — dedup is visible via {@link size} — and
+ * bumps that blob's touch time (SPI 1.3.0).
+ */
+class InMemoryContentStore {
+    blobs = new Map();
+    /**
+     * Addresses in ascending order for `listPage`'s keyset scan, rebuilt lazily: only a NEW
+     * address invalidates it (O(1) per put), a delete leaves a stale entry the scan skips, so a
+     * sweep deleting while it pages sorts once — O(n log n) per scan, O(log n + limit) per page.
+     */
+    sorted = [];
+    sortedStale = false;
+    now;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+    }
+    async put(bytes) {
+        const address = (0, content_1.contentAddress)(bytes);
+        this.store(address, bytes);
+        return { __loomContent: address, size: bytes.length };
+    }
+    async putStream(stream) {
+        // Hash incrementally while spooling (an in-memory store holds the bytes
+        // anyway — durable backends spool to their medium instead of an array).
+        const hash = (0, node_crypto_1.createHash)("sha256");
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of stream) {
+            hash.update(chunk);
+            chunks.push(chunk);
+            size += chunk.byteLength;
+        }
+        const address = `sha256:${hash.digest("hex")}`;
+        const existing = this.blobs.get(address);
+        if (existing !== undefined) {
+            existing.touchedAt = Math.max(existing.touchedAt, this.now()); // monotonic
+        }
+        else {
+            const bytes = new Uint8Array(size);
+            let offset = 0;
+            for (const chunk of chunks) {
+                bytes.set(chunk, offset);
+                offset += chunk.byteLength;
+            }
+            this.store(address, bytes);
+        }
+        return { __loomContent: address, size };
+    }
+    async get(ref) {
+        return this.blobs.get(ref.__loomContent)?.bytes ?? null;
+    }
+    async getMany(refs) {
+        return refs.map((ref) => this.blobs.get(ref.__loomContent)?.bytes ?? null);
+    }
+    async delete(ref) {
+        this.blobs.delete(ref.__loomContent);
+    }
+    async deleteIfUntouchedSince(ref, cutoffMs) {
+        // No await between the check and the delete: atomic on the event loop.
+        const blob = this.blobs.get(ref.__loomContent);
+        if (blob === undefined || !(blob.touchedAt < cutoffMs))
+            return false;
+        return this.blobs.delete(ref.__loomContent);
+    }
+    async touchClock() {
+        return this.now();
+    }
+    async touch(addresses) {
+        const touchedAt = this.now();
+        const missing = [];
+        for (const address of addresses) {
+            const blob = this.blobs.get(address);
+            if (blob === undefined)
+                missing.push(address);
+            else
+                blob.touchedAt = Math.max(blob.touchedAt, touchedAt); // monotonic, like put
+        }
+        return missing;
+    }
+    async listPage(opts = {}) {
+        const limit = contentListPageLimit(opts.limit);
+        if (this.sortedStale || this.sorted.length > 2 * this.blobs.size + 64) {
+            this.sorted = [...this.blobs.keys()].sort();
+            this.sortedStale = false;
+        }
+        let i = opts.cursor === undefined ? 0 : upperBound(this.sorted, opts.cursor);
+        const entries = [];
+        let last;
+        for (; i < this.sorted.length && entries.length < limit; i++) {
+            const address = this.sorted[i];
+            last = address;
+            const blob = this.blobs.get(address);
+            if (blob === undefined)
+                continue; // deleted since the last rebuild
+            if (opts.touchedBefore !== undefined && !(blob.touchedAt < opts.touchedBefore))
+                continue;
+            entries.push({ address, touchedAt: blob.touchedAt });
+        }
+        return i < this.sorted.length && last !== undefined
+            ? { entries, nextCursor: last }
+            : { entries };
+    }
+    /** Number of distinct blobs stored — makes content-addressed dedup observable in tests. */
+    get size() {
+        return this.blobs.size;
+    }
+    store(address, bytes) {
+        const touchedAt = this.now();
+        const existing = this.blobs.get(address);
+        if (existing !== undefined) {
+            // A re-citation: bump (never backwards), keep the stored bytes.
+            existing.touchedAt = Math.max(existing.touchedAt, touchedAt);
+            return;
+        }
+        this.blobs.set(address, { bytes, touchedAt });
+        this.sortedStale = true;
+    }
+}
+exports.InMemoryContentStore = InMemoryContentStore;
+/** First index whose element is strictly greater than `key` (binary search). */
+function upperBound(sorted, key) {
+    let lo = 0;
+    let hi = sorted.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (sorted[mid] <= key)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+//# sourceMappingURL=ContentStore.js.map

package/dist/ContentStore.js.map

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