@loomwork/ui-lineage 0.0.0-stage → 0.1.1

package/src/retention.ts

@@ -0,0 +1,118 @@
+import type { LineageState, VersionRecord } from "./state";
+
+// ── Version retention: which versions a line must keep (U17) ──────────────────────────────────
+// Every version stores its WHOLE artifact (`putExperience`), so a line grows O(versions x nodes) and,
+// because each version's event cites its artifact by a bare content ref, loom's `sweepUnpinnedContent`
+// pins every one of them for ever while the lineage's streams are scanned. Retention is the policy
+// that says which versions are still wanted; `Lineage.pins` turns it into the root set a collector
+// marks, and everything NOT in it stops being pinned by the lineage.
+//
+// This module is the pure half: a policy over one line's folded state. It never reads a blob.
+
+export interface RetentionPolicy {
+  /**
+   * Keep the newest N versions of each line, counted in append order and including the head.
+   * Default {@link DEFAULT_KEEP_LAST}. The head is ALWAYS kept, whatever this says (`0` keeps only
+   * what the other rules keep). `Infinity` keeps every version. Anything else that is not a
+   * non-negative integer THROWS: this policy decides what gets deleted, so a typo is never read as
+   * "keep nothing".
+   */
+  readonly keepLast?: number;
+  /**
+   * Also keep every version authored at or after this instant: an ISO-8601 date or date-time string
+   * (`2026-10-01`, `2026-10-01T00:00:00Z`), a `Date`, or epoch milliseconds. Anything else THROWS
+   * (lenient parsing would read `"1"` as the year 2001).
+   */
+  readonly keepSince?: string | number | Date;
+  /**
+   * Keep the line's first version (default `true`): the genesis anchors `verify`'s replay and is the
+   * one version every other is derived from.
+   */
+  readonly keepGenesis?: boolean;
+  /** Keep versions the host names (its own audit pins, a customer's "approved" marks). Unknown hashes are ignored. */
+  readonly keep?: (version: VersionRecord) => boolean;
+}
+
+export const DEFAULT_KEEP_LAST = 20;
+
+const ISO_8601 = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+
+/** `keepSince` as epoch milliseconds; NaN when it is not a strict ISO-8601 string, a valid Date or a finite number. */
+function keepSinceMs(v: unknown): number {
+  if (typeof v === "string") return ISO_8601.test(v) ? Date.parse(v) : Number.NaN;
+  if (v instanceof Date) return v.getTime();
+  if (typeof v === "number") return Number.isFinite(v) ? v : Number.NaN;
+  return Number.NaN;
+}
+
+/**
+ * Refuse a policy that does not mean what its author meant. A deletion policy must not coerce: NaN,
+ * a negative or fractional `keepLast`, an unparseable `keepSince` or a non-boolean/-function rule
+ * all throw. `Infinity` is the one non-integer allowed (keep everything).
+ */
+export function validateRetentionPolicy(policy: RetentionPolicy): void {
+  const bad = (m: string): never => {
+    throw new RangeError(`RetentionPolicy: ${m}`);
+  };
+  const { keepLast, keepSince, keepGenesis, keep } = policy;
+  if (keepLast !== undefined) {
+    if (typeof keepLast !== "number") bad(`keepLast must be a number, got ${typeof keepLast}`);
+    else if (
+      keepLast !== Number.POSITIVE_INFINITY &&
+      !(Number.isSafeInteger(keepLast) && keepLast >= 0)
+    )
+      bad(
+        `keepLast must be a non-negative integer or Infinity (keep all), got ${String(keepLast)}`
+      );
+  }
+  if (keepSince !== undefined && Number.isNaN(keepSinceMs(keepSince)))
+    bad(
+      `keepSince must be an ISO-8601 date/time string, a valid Date or epoch milliseconds, got ${String(keepSince)}`
+    );
+  if (keepGenesis !== undefined && typeof keepGenesis !== "boolean")
+    bad("keepGenesis must be a boolean");
+  if (keep !== undefined && typeof keep !== "function") bad("keep must be a function");
+}
+
+export interface Retained {
+  /** Version hashes the policy keeps. */
+  readonly keep: ReadonlySet<string>;
+  /** Every other version of the line, oldest first: nothing the policy wants still needs its artifact. */
+  readonly reclaimable: readonly string[];
+}
+
+/**
+ * What to keep of one line. Always kept, regardless of the policy: the head, the promoted version (it
+ * is what viewers are shown), and every version another line branched from (`branchSources`: a fork is
+ * only as sound as its source, and `verify` rebuilds the source up to the fork point). Total: an empty
+ * line keeps nothing. Throws on a malformed policy ({@link validateRetentionPolicy}).
+ */
+export function retainedVersions(
+  state: LineageState,
+  policy: RetentionPolicy = {},
+  branchSources: ReadonlySet<string> = new Set()
+): Retained {
+  validateRetentionPolicy(policy);
+  const keep = new Set<string>();
+  const order = state.order;
+  if (state.head !== null) keep.add(state.head);
+  if (state.promoted !== null) keep.add(state.promoted);
+  for (const h of branchSources) if (state.versions.has(h)) keep.add(h);
+
+  const last = policy.keepLast ?? DEFAULT_KEEP_LAST;
+  const n = last === Number.POSITIVE_INFINITY ? order.length : last;
+  for (let i = Math.max(0, order.length - n); i < order.length; i++) keep.add(order[i] as string);
+
+  if ((policy.keepGenesis ?? true) && order.length > 0) keep.add(order[0] as string);
+
+  const since = policy.keepSince === undefined ? Number.NaN : keepSinceMs(policy.keepSince);
+  for (const h of order) {
+    const v = state.versions.get(h) as VersionRecord;
+    if (!Number.isNaN(since)) {
+      const at = Date.parse(v.at);
+      if (!Number.isNaN(at) && at >= since) keep.add(h);
+    }
+    if (policy.keep?.(v) === true) keep.add(h);
+  }
+  return { keep, reclaimable: order.filter((h) => !keep.has(h)) };
+}

package/src/rootsFor.ts

@@ -0,0 +1,75 @@
+import type { Lineage, PinsExtra } from "./lineage";
+import { type RetentionPolicy, validateRetentionPolicy } from "./retention";
+import type { SeenLog } from "./seen";
+import { collectSeenRoots } from "./seenGc";
+
+// ── The complete root set for a shared ContentStore (U17) ─────────────────────────────────────
+// Loom's `sweepUnpinnedContent({ roots, completeScan: true })` erases every blob no root names, so
+// `roots` must come from EVERY user of the store. Passing ONE lineage's `pins()` silently loses every
+// other lineage's artifacts; this is the one place that composes them.
+
+export interface RootsForOptions {
+  /** EVERY lineage sharing the content store, each with the retention policy that decides what it keeps. */
+  readonly lineages: ReadonlyArray<{
+    readonly lineage: Lineage;
+    readonly policy?: RetentionPolicy;
+  }>;
+  /**
+   * EVERY seen log sharing the store. Each one's live sealed value blobs are rooted, and the versions
+   * its views still read are kept by the lineage it was built over (`log.lineageOf`), which MUST be
+   * one of `lineages` (THROWS otherwise: its versions would have no policy to be kept under).
+   */
+  readonly seenLogs?: readonly SeenLog[];
+  /** Passed to each `collectSeenRoots`: sweep what an unreadable live window cites instead of refusing. Default: refuse. */
+  readonly allowUnreadable?: boolean;
+  /** Other users of the store (app tables, anything loom's own scan does not see). */
+  readonly extra?: AsyncIterable<string> | Iterable<string>;
+}
+
+type VersionRef = { readonly experienceId: string; readonly versionHash: string };
+
+/**
+ * One async iterable of every address to keep: each lineage's `pins(policy)` (with the versions the
+ * seen logs over THAT lineage still read), each seen log's sealed value blobs, and `extra`; deduplicated.
+ *
+ * FAIL CLOSED: policies and wiring are validated before anything is read, and the whole set is
+ * established BEFORE the first address is yielded, so any source throwing makes the iterator throw
+ * without yielding a partial set (loom consumes roots fully before it erases; this holds for any
+ * consumer). Memory is one string per distinct live address.
+ *
+ *   roots: () => rootsFor({ lineages: [{ lineage: a, policy }, { lineage: b }], seenLogs: [log] })
+ */
+export async function* rootsFor(opts: RootsForOptions): AsyncGenerator<string, void, undefined> {
+  const entries = [...opts.lineages];
+  const seen = new Set<Lineage>();
+  for (const e of entries) {
+    validateRetentionPolicy(e.policy ?? {});
+    if (seen.has(e.lineage))
+      throw new Error("rootsFor: the same Lineage is listed twice (give it one policy)");
+    seen.add(e.lineage);
+  }
+  for (const log of opts.seenLogs ?? [])
+    if (!seen.has(log.lineageOf))
+      throw new Error(
+        "rootsFor: a seen log is built over a Lineage that is not in `lineages`; list it, or its versions have no policy to be kept under"
+      );
+
+  const addresses = new Set<string>();
+  const versionsOf = new Map<Lineage, VersionRef[]>();
+  for (const log of opts.seenLogs ?? []) {
+    const r = await collectSeenRoots(log, {
+      ...(opts.allowUnreadable !== undefined && { allowUnreadable: opts.allowUnreadable }),
+    });
+    for await (const a of r.keepAddresses) addresses.add(a);
+    const list = versionsOf.get(log.lineageOf) ?? [];
+    list.push(...r.keepVersions);
+    versionsOf.set(log.lineageOf, list);
+  }
+  for (const { lineage, policy } of entries) {
+    const extra: PinsExtra = { keepVersions: versionsOf.get(lineage) ?? [] };
+    for await (const a of lineage.pins(policy ?? {}, extra)) addresses.add(a);
+  }
+  if (opts.extra !== undefined) for await (const a of opts.extra) addresses.add(a);
+
+  for (const a of addresses) yield a;
+}