@loomwork/plugin-content 0.0.0-stage → 0.1.1

package/src/ContentTouchingSnapshotStore.ts

@@ -0,0 +1,109 @@
+import { type DecoratorPlan, installOptional } from "@loomwork/event-runtime";
+import type {
+  OptionalSnapshotStoreMethod,
+  Snapshot,
+  SnapshotStore,
+} from "@loomwork/snapshot-runtime";
+import type { ContentStore } from "./ContentStore";
+import { type TouchErrorHook, touchAround } 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 const CONTENT_TOUCHING_SNAPSHOT_STORE: unique symbol = 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.
+ */
+export function isContentTouchingSnapshotStore(store: unknown): boolean {
+  return (
+    typeof store === "object" &&
+    store !== null &&
+    (store as Record<symbol, unknown>)[CONTENT_TOUCHING_SNAPSHOT_STORE] === true
+  );
+}
+
+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 class ContentTouchingSnapshotStore implements SnapshotStore {
+  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: TouchErrorHook | undefined;
+
+  constructor(
+    private readonly inner: SnapshotStore,
+    private readonly content: Pick<ContentStore, "touch">,
+    options: ContentTouchingSnapshotStoreOptions = {}
+  ) {
+    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",
+    } satisfies DecoratorPlan<SnapshotStore, OptionalSnapshotStoreMethod>;
+    installOptional<SnapshotStore, OptionalSnapshotStoreMethod>(this, inner, plan);
+  }
+
+  save(snapshot: Snapshot): Promise<void> {
+    return touchAround(
+      this.content,
+      [snapshot.state],
+      { operation: "snapshotSave", executionId: snapshot.executionId },
+      this.onTouchError,
+      () => this.inner.save(snapshot)
+    );
+  }
+
+  loadLatest(executionId: string): Promise<Snapshot | null> {
+    return this.inner.loadLatest(executionId);
+  }
+
+  loadAt(executionId: string, sequence: number): Promise<Snapshot | null> {
+    return this.inner.loadAt(executionId, sequence);
+  }
+
+  loadLatestBefore(executionId: string, sequence: number): Promise<Snapshot | null> {
+    return this.inner.loadLatestBefore(executionId, sequence);
+  }
+
+  close(): Promise<void> {
+    return this.inner.close();
+  }
+}

package/src/citations.ts

@@ -0,0 +1,117 @@
+// 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.
+
+/**
+ * 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: object): string | undefined {
+  if ((value as { __loomClaimCheck?: unknown }).__loomClaimCheck !== true) return undefined;
+  const address = (value as { ref?: { __loomContent?: unknown } | null }).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: object): string | undefined {
+  if ((value as { kind?: unknown }).kind !== "ref") return undefined;
+  const address = (value as { ref?: { address?: unknown } | null }).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).
+ */
+export 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 {
+  const stack: unknown[] = [value];
+  const seen = new WeakSet<object>();
+  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 as { __loomContent?: unknown }).__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 as { retain?: unknown }).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.
+ */
+export function retainRootsOf(event: { eventType: string; payload: unknown }): Set<object> {
+  const roots = new Set<object>();
+  if (event.eventType !== "STEP_COMPLETED") return roots;
+  let out = (event.payload as { output?: unknown } | null)?.output;
+  if (
+    typeof out === "object" &&
+    out !== null &&
+    (out as { __loomTainted?: unknown }).__loomTainted !== undefined
+  ) {
+    out = (out as { value?: unknown }).value;
+  }
+  if (typeof out === "object" && out !== null) roots.add(out);
+  return roots;
+}

package/src/content.bench.ts

@@ -0,0 +1,84 @@
+import type { EventEnvelope } from "@loomwork/core";
+import { InMemoryAsyncEventStore } from "@loomwork/event-runtime";
+import { bench, describe } from "vitest";
+import { ContentResolvingEventStore } from "./ContentResolvingEventStore";
+import { type ContentStore, InMemoryContentStore } from "./ContentStore";
+import type { ContentRef } from "./content";
+
+// ── 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: number) => new Promise((r) => setTimeout(r, ms));
+
+function withLatency(inner: InMemoryContentStore, supportsGetMany: boolean): ContentStore {
+  const store: ContentStore = {
+    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: readonly ContentRef[]) => {
+      await sleep(LATENCY_MS);
+      return inner.getMany(refs);
+    };
+  }
+  return store;
+}
+
+function envelope(sequence: number, payload: unknown): EventEnvelope {
+  return {
+    id: `e-${sequence}`,
+    executionId: "x-1",
+    workflowId: "w-1",
+    eventType: "STEP_COMPLETED",
+    sequence,
+    timestamp: 1_000 + sequence,
+    payload,
+  };
+}
+
+async function seeded(supportsGetMany: boolean) {
+  const memory = new InMemoryContentStore();
+  const content = withLatency(memory, supportsGetMany);
+  const store = new ContentResolvingEventStore(new 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: ContentResolvingEventStore | undefined;
+let fallback: ContentResolvingEventStore | undefined;
+
+describe(`resolve ${WIDGETS} refs @ ${LATENCY_MS}ms backend latency`, () => {
+  bench("getMany (one batched round-trip)", async () => {
+    batched ??= await seeded(true);
+    await batched.read("x-1");
+  });
+
+  bench("no getMany (coalesced parallel gets)", async () => {
+    fallback ??= await seeded(false);
+    await fallback.read("x-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);
+    }
+  });
+});

package/src/content.ts

@@ -0,0 +1,191 @@
+import { createHash } from "node:crypto";
+import { expandPaths, hasWildcard } from "@loomwork/classify";
+
+// ── ADR 0046 — content-addressed references ───────────────────────────────────
+//
+// A payload field can be *externalized*: its value is stored in a content store and the log
+// keeps only a reference. The reference is content-ADDRESSED — the address is `hash(bytes)`,
+// a pure function of the content — which is what preserves determinism (replay reproduces the
+// same address), gives natural dedup (identical values collapse to one blob), and yields the
+// refcount key for free (forks that copy a prefix share the same address).
+
+/** 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 function isContentRef(value: unknown): value is ContentRef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { __loomContent?: unknown }).__loomContent === "string"
+  );
+}
+
+/** The content address of some bytes: `sha256:<hex>`. Pure — the same bytes always map here. */
+export function contentAddress(bytes: Uint8Array): string {
+  return `sha256:${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). */
+export function encodeValue(value: unknown): Uint8Array {
+  return UTF8_ENCODER.encode(JSON.stringify(value));
+}
+
+/** Decode content-store bytes back to the original value. */
+export function decodeValue(bytes: Uint8Array): unknown {
+  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: object): boolean {
+  const v = value as { __loomClaimCheck?: unknown; ref?: { __loomContent?: unknown } };
+  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). */
+export function hasContentRef(value: unknown): boolean {
+  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 as Record<string, unknown>).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.
+ */
+export function collectContentRefs(value: unknown, into: Map<string, ContentRef>): boolean {
+  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 as Record<string, unknown>)) {
+      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).
+ */
+export function substituteContentRefs(
+  value: unknown,
+  bytesByAddress: ReadonlyMap<string, Uint8Array>
+): unknown {
+  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: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      const r = substituteContentRefs(v, bytesByAddress);
+      out[k] = r;
+      if (r !== v) changed = true;
+    }
+    return changed ? out : value;
+  }
+  return value;
+}
+
+function shallowCopy(value: object): Record<string, unknown> {
+  return Array.isArray(value)
+    ? ([...value] as unknown as Record<string, unknown>)
+    : { ...(value as Record<string, 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 async function mapPathsAsync(
+  root: unknown,
+  paths: readonly string[],
+  transform: (value: unknown) => Promise<unknown>
+): Promise<unknown> {
+  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 = hasWildcard(paths) ? expandPaths(root, paths) : paths;
+  const out = shallowCopy(root);
+  for (const path of targets) {
+    const segs = path.split(".");
+    let src = root as Record<string, unknown>;
+    let dst = out;
+    let reachable = true;
+    for (let i = 0; i < segs.length - 1; i++) {
+      const seg = segs[i] as string;
+      const child = src[seg];
+      if (typeof child !== "object" || child === null) {
+        reachable = false;
+        break;
+      }
+      if (dst[seg] === child) dst[seg] = shallowCopy(child as object);
+      src = child as Record<string, unknown>;
+      dst = dst[seg] as Record<string, unknown>;
+    }
+    const leaf = segs[segs.length - 1] as string;
+    if (reachable && Object.hasOwn(src, leaf)) dst[leaf] = await transform(src[leaf]);
+  }
+  return out;
+}

package/src/derive.ts

@@ -0,0 +1,40 @@
+import { externalizedPaths } from "@loomwork/classify";
+import type { StepDefinition } from "@loomwork/core";
+
+// ── ADR 0046 — derive the externalize map from `externalized()` marks ──────────
+//
+// Mark a field once — `doc: externalized(z.object({...}))` — and derive the
+// ContentResolvingEventStore `externalize` map, instead of hand-authoring
+// `{ STEP_COMPLETED: ["output.doc"] }`. Mirrors `sensitivePathsFromSteps` (crypto): a step's
+// output is stored under `output.*` in STEP_COMPLETED, so an externalized output field
+// contributes `STEP_COMPLETED → "output.<path>"`.
+
+/** The STEP_COMPLETED payload nests a step's output under this key. */
+const OUTPUT_PREFIX = "output";
+
+/**
+ * Build the {@link ContentResolvingEventStore} `externalize` map from step definitions: every
+ * field marked `externalized()` in a step's `outputSchema` becomes a `STEP_COMPLETED` dot-path
+ * `output.<path>`. Paths are unioned + O(n) de-duplicated across steps; an empty map when
+ * nothing is marked (zero-overhead unwired path, G2).
+ */
+export function externalizePathsFromSteps(
+  // Only the output schema is read; Pick drops the invariant handler field so concrete
+  // `StepDefinition<In, Out>` values pass without a cast.
+  steps: readonly Pick<StepDefinition, "outputSchema">[]
+): Record<string, string[]> {
+  const seen = new Set<string>();
+  const stepCompleted: string[] = [];
+  for (const step of steps) {
+    const schema = step.outputSchema;
+    if (schema === undefined) continue;
+    for (const path of externalizedPaths(schema)) {
+      const dotted = `${OUTPUT_PREFIX}.${path}`;
+      if (!seen.has(dotted)) {
+        seen.add(dotted);
+        stepCompleted.push(dotted);
+      }
+    }
+  }
+  return stepCompleted.length > 0 ? { STEP_COMPLETED: stepCompleted } : {};
+}

package/src/errors.ts

@@ -0,0 +1,19 @@
+// ── ADR 0046 — loud on absence (the generalized PAYLOAD_SHREDDED contract) ─────
+//
+// A fold that needs an externalized value whose bytes were erased (or never stored) must fail
+// LOUDLY — never silently substitute a default and diverge (G1). This mirrors the crypto
+// plugin's `PayloadShreddedError`: the value is gone, so replay of it cannot proceed.
+
+export class ContentMissingError extends Error {
+  constructor(
+    readonly contentAddress: string,
+    readonly executionId?: string
+  ) {
+    super(
+      `externalized content "${contentAddress}"${
+        executionId ? ` (execution "${executionId}")` : ""
+      } is missing: the bytes were erased or never stored, so replay cannot restore this value`
+    );
+    this.name = "ContentMissingError";
+  }
+}

package/src/executionEnd.ts

@@ -0,0 +1,64 @@
+import type { EventEnvelope } from "@loomwork/core";
+
+// A terminal timestamp that is not a finite number (NaN, a string from an imported log or a 3P store,
+// +-Infinity, null) is not comparable: treat the execution as not ended so the citation clock applies.
+const finiteOrUndefined = (t: unknown): number | undefined =>
+  typeof t === "number" && Number.isFinite(t) ? t : undefined;
+
+/**
+ * ADR 0146 - when did this execution END, as far as the live log can tell? The `at` of its newest
+ * kernel terminal event, or `undefined` when it has not ended: no terminal event, or it was RE-OPENED
+ * after its newest one (`resumeAs` appends EXECUTION_RESUMED to a terminal execution; a later
+ * EXECUTION_SUSPENDED / EXECUTION_STARTED likewise means live). `undefined` makes the sweep fall back
+ * to the citation clock, so every uncertainty can only age a ref LATER or equal, never earlier.
+ *
+ * The terminal set is the one `@loomwork/workflow-runtime`'s `terminalEndedAt` uses (and the replay VM's
+ * `isKernelWritten` check for EXECUTION_CONTINUED); it is duplicated, not imported, so this package
+ * takes no dependency on workflow-runtime. `gc.endClock.test.ts` (l) pins it against the ReplayVM.
+ * Scans from the tail in sequence order (not timestamp order), usually stopping within a few events.
+ */
+export function terminalEndOf(events: readonly EventEnvelope[]): number | undefined {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const e = events[i] as EventEnvelope;
+    switch (e.eventType) {
+      case "EXECUTION_RESUMED":
+      case "EXECUTION_SUSPENDED":
+      case "EXECUTION_STARTED":
+        return undefined;
+      case "EXECUTION_COMPLETED":
+      case "EXECUTION_FAILED":
+      case "EXECUTION_CANCELLED":
+        return finiteOrUndefined(e.timestamp);
+      case "EXECUTION_CONTINUED":
+        if (e.metadata?.kernel === true) return finiteOrUndefined(e.timestamp);
+    }
+  }
+  return undefined;
+}
+
+/**
+ * ADR 0146 - was this execution RE-OPENED after a terminal event? True iff its tail is live
+ * (`terminalEndOf` returns `undefined` because a RESUMED / SUSPENDED / STARTED follows) AND a terminal
+ * event (the same set as `terminalEndOf`) precedes that live tail. A run that never ended is false.
+ * A terminal event with a non-finite timestamp still counts as an end here (the log shows it ended).
+ */
+export function wasReopened(events: readonly EventEnvelope[]): boolean {
+  let live = false;
+  for (let i = events.length - 1; i >= 0; i--) {
+    const e = events[i] as EventEnvelope;
+    switch (e.eventType) {
+      case "EXECUTION_RESUMED":
+      case "EXECUTION_SUSPENDED":
+      case "EXECUTION_STARTED":
+        live = true;
+        break;
+      case "EXECUTION_COMPLETED":
+      case "EXECUTION_FAILED":
+      case "EXECUTION_CANCELLED":
+        return live;
+      case "EXECUTION_CONTINUED":
+        if (e.metadata?.kernel === true) return live;
+    }
+  }
+  return false;
+}