@loomwork/plugin-content 0.0.0-stage → 0.1.0

package/src/ContentResolvingEventStore.ts

@@ -0,0 +1,325 @@
+import type { EventEnvelope } from "@loomwork/core";
+import {
+  type DecoratorPlan,
+  type EventStore,
+  type OptionalEventStoreMethod,
+  installOptional,
+  readRangeOf,
+} from "@loomwork/event-runtime";
+import type { ContentStore } from "./ContentStore";
+import {
+  type ContentRef,
+  collectContentRefs,
+  encodeValue,
+  hasContentRef,
+  mapPathsAsync,
+  substituteContentRefs,
+} from "./content";
+import { ContentMissingError } from "./errors";
+import { type TouchErrorHook, touchAround } from "./touchAround";
+
+export interface ContentResolvingEventStoreOptions {
+  /**
+   * Payload dot-paths to externalize per event type, e.g. `{ STEP_COMPLETED: ["output.doc"] }`.
+   * On append those fields are moved to the content store and replaced by a {@link ContentRef};
+   * on read they are resolved back. Unmarked events are stored verbatim (zero overhead, G2).
+   */
+  externalize: Record<string, readonly string[]>;
+  /**
+   * Observer for the SPI 1.4.0 `touch` this store makes around ref-carrying writes (ADR 0055 D6
+   * amendment 2): called when the touch AFTER a durable write threw (swallowed otherwise, since the
+   * write already landed), and when either touch reports a cited bare ref MISSING (the write cites
+   * a blob that is already gone). A failure of the touch BEFORE the write still rejects the write.
+   * Wire it to your logger or metrics. See {@link TouchErrorHook}.
+   */
+  onTouchError?: TouchErrorHook;
+}
+
+/**
+ * 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: Record<string, readonly string[]>,
+  eventType: string
+): readonly string[] | undefined {
+  return Object.hasOwn(map, eventType) ? map[eventType] : undefined;
+}
+
+export class ContentResolvingEventStore implements EventStore {
+  private readonly externalize: Record<string, readonly string[]>;
+  private readonly onTouchError: TouchErrorHook | undefined;
+  readonly appendBatch?: NonNullable<EventStore["appendBatch"]>;
+  readonly head?: NonNullable<EventStore["head"]>;
+  readonly readRange?: NonNullable<EventStore["readRange"]>;
+  readonly acquireFence?: NonNullable<EventStore["acquireFence"]>;
+  readonly acquireFenceIf?: NonNullable<EventStore["acquireFenceIf"]>;
+  readonly appendIfUnchanged?: NonNullable<EventStore["appendIfUnchanged"]>;
+  readonly storeNow?: NonNullable<EventStore["storeNow"]>;
+  readonly sealingCapability?: NonNullable<EventStore["sealingCapability"]>;
+  readonly readAtRest?: NonNullable<EventStore["readAtRest"]>;
+  readonly copyPrefix?: NonNullable<EventStore["copyPrefix"]>;
+  readonly deleteExecution?: NonNullable<EventStore["deleteExecution"]>;
+  readonly deleteThrough?: NonNullable<EventStore["deleteThrough"]>;
+  readonly truncatePrefix?: NonNullable<EventStore["truncatePrefix"]>;
+  readonly truncatePrefixKeeping?: NonNullable<EventStore["truncatePrefixKeeping"]>;
+  readonly listExecutions?: NonNullable<EventStore["listExecutions"]>;
+  readonly listExecutionsPage?: NonNullable<EventStore["listExecutionsPage"]>;
+
+  constructor(
+    private readonly inner: EventStore,
+    private readonly content: ContentStore,
+    options: ContentResolvingEventStoreOptions
+  ) {
+    // 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 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",
+    } satisfies DecoratorPlan<EventStore, OptionalEventStoreMethod>;
+    installOptional<EventStore, OptionalEventStoreMethod>(this, inner, plan);
+  }
+
+  private async externalizeEnvelope(envelope: EventEnvelope): Promise<EventEnvelope> {
+    const paths = pathsFor(this.externalize, envelope.eventType);
+    if (paths === undefined || paths.length === 0) return envelope; // unmarked → verbatim (G2)
+    const payload = await mapPathsAsync(envelope.payload, paths, (v) => this.externalizeValue(v));
+    return { ...envelope, payload };
+  }
+
+  async append(envelope: EventEnvelope): Promise<void> {
+    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.
+   */
+  private touching<T>(
+    payloads: readonly unknown[],
+    ctx: Parameters<typeof touchAround>[2],
+    write: () => Promise<T>
+  ): Promise<T> {
+    return touchAround(this.content, payloads, ctx, this.onTouchError, write);
+  }
+
+  private async externalizeValue(value: unknown): Promise<ContentRef> {
+    const ref = await this.content.put(encodeValue(value));
+    return { ...ref, codec: "json" };
+  }
+
+  async read(executionId: string): Promise<EventEnvelope[]> {
+    return this.resolveAll(executionId, await this.inner.read(executionId));
+  }
+
+  async readFrom(executionId: string, fromSequence: number): Promise<EventEnvelope[]> {
+    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.
+  private async resolveAll(executionId: string, events: EventEnvelope[]): Promise<EventEnvelope[]> {
+    const distinct = new Map<string, ContentRef>();
+    const refBearing = events.map((e) => 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: substituteContentRefs(e.payload, bytesByAddress) } : e
+    );
+  }
+
+  /** Fetch all distinct refs; loudness contract unchanged (missing ⇒ ContentMissingError, G1). */
+  private async fetchBytes(
+    distinct: ReadonlyMap<string, ContentRef>,
+    executionId: string
+  ): Promise<Map<string, Uint8Array>> {
+    // Single pass over the map (audit nit): addresses and refs stay index-aligned.
+    const addresses = new Array<string>(distinct.size);
+    const refs = new Array<ContentRef>(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<string, Uint8Array>();
+    for (let i = 0; i < addresses.length; i++) {
+      const bytes = fetched[i];
+      if (bytes === null || bytes === undefined) {
+        throw new ContentMissingError(addresses[i] as string, executionId);
+      }
+      out.set(addresses[i] as string, bytes);
+    }
+    return out;
+  }
+
+  async subscribe(
+    executionId: string,
+    handler: (event: EventEnvelope) => void
+  ): Promise<() => void> {
+    // 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: EventEnvelope) => {
+      if (!hasContentRef(event.payload)) {
+        handler(event);
+        return;
+      }
+      const distinct = new Map<string, ContentRef>();
+      collectContentRefs(event.payload, distinct);
+      void this.fetchBytes(distinct, executionId)
+        .then((bytes) =>
+          handler({ ...event, payload: substituteContentRefs(event.payload, bytes) })
+        )
+        .catch(() => handler(event));
+    });
+  }
+
+  async close(): Promise<void> {
+    return this.inner.close();
+  }
+}

package/src/ContentStore.ts

@@ -0,0 +1,317 @@
+import { createHash } from "node:crypto";
+import { type ContentRef, contentAddress } from "./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.
+ */
+export 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 const CONTENT_LIST_PAGE_DEFAULT_LIMIT = 500;
+export const 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.
+ */
+export function contentListPageLimit(limit: number | undefined): number {
+  if (limit === undefined) return 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, CONTENT_LIST_PAGE_MAX_LIMIT);
+}
+
+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 class InMemoryContentStore implements ContentStore {
+  private readonly blobs = new Map<string, { bytes: Uint8Array; touchedAt: number }>();
+  /**
+   * 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: string[] = [];
+  private sortedStale = false;
+  private readonly now: () => number;
+
+  constructor(options: InMemoryContentStoreOptions = {}) {
+    this.now = options.now ?? Date.now;
+  }
+
+  async put(bytes: Uint8Array): Promise<ContentRef> {
+    const address = contentAddress(bytes);
+    this.store(address, bytes);
+    return { __loomContent: address, size: bytes.length };
+  }
+
+  async putStream(stream: AsyncIterable<Uint8Array>): Promise<ContentRef> {
+    // Hash incrementally while spooling (an in-memory store holds the bytes
+    // anyway — durable backends spool to their medium instead of an array).
+    const hash = createHash("sha256");
+    const chunks: Uint8Array[] = [];
+    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: ContentRef): Promise<Uint8Array | null> {
+    return this.blobs.get(ref.__loomContent)?.bytes ?? null;
+  }
+
+  async getMany(refs: readonly ContentRef[]): Promise<(Uint8Array | null)[]> {
+    return refs.map((ref) => this.blobs.get(ref.__loomContent)?.bytes ?? null);
+  }
+
+  async delete(ref: ContentRef): Promise<void> {
+    this.blobs.delete(ref.__loomContent);
+  }
+
+  async deleteIfUntouchedSince(ref: ContentRef, cutoffMs: number): Promise<boolean> {
+    // 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(): Promise<number> {
+    return this.now();
+  }
+
+  async touch(addresses: readonly string[]): Promise<string[]> {
+    const touchedAt = this.now();
+    const missing: string[] = [];
+    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: ContentListPageOptions = {}): Promise<ContentListPage> {
+    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: ContentPageEntry[] = [];
+    let last: string | undefined;
+    for (; i < this.sorted.length && entries.length < limit; i++) {
+      const address = this.sorted[i] as string;
+      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(): number {
+    return this.blobs.size;
+  }
+
+  private store(address: string, bytes: Uint8Array): void {
+    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;
+  }
+}
+
+/** First index whose element is strictly greater than `key` (binary search). */
+function upperBound(sorted: readonly string[], key: string): number {
+  let lo = 0;
+  let hi = sorted.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if ((sorted[mid] as string) <= key) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}