@loomwork/ui-lineage 0.0.0-stage → 0.1.1

package/src/conformance.ts

@@ -0,0 +1,148 @@
+import type { Finding } from "@loomwork/ui-core";
+import type { LineageStore } from "./store";
+
+// ── The LineageStore conformance kit ──────────────────────────────────────────
+// Returns findings (a test asserts the list is empty), never throws: a store that throws on a case
+// is reported as a finding, like `checkPlannerConformance`. Each case uses a fresh line id, so one
+// `make()` store serves them all — but a backend that cannot isolate lines is exactly what the
+// "lines are independent" case catches.
+
+const rec = (n: number) => ({
+  type: "EXPERIENCE_COMPOSED",
+  payload: { n },
+  at: "2026-10-06T00:00:00.000Z",
+});
+
+export async function checkLineageStoreConformance(
+  make: () => LineageStore | Promise<LineageStore>
+): Promise<Finding[]> {
+  const findings: Finding[] = [];
+  const fail = (code: string, message: string) =>
+    findings.push({ code, severity: "error", message });
+  const store = await make();
+  const cases: Array<[string, () => Promise<void>]> = [
+    [
+      "an unknown line reads empty",
+      async () => {
+        const r = await store.read("c-empty");
+        if (r.length !== 0) fail("read-unknown", `an unknown line read ${r.length} records`);
+      },
+    ],
+    [
+      "append at tip 0 wins sequence 1; the sequence is dense",
+      async () => {
+        const a = await store.append("c-seq", 0, rec(1));
+        const b = await store.append("c-seq", 1, rec(2));
+        if (!a.ok || a.sequence !== 1 || !b.ok || b.sequence !== 2)
+          fail("append-sequence", `sequential appends returned ${JSON.stringify([a, b])}`);
+        const r = await store.read("c-seq");
+        if (r.map((x) => x.sequence).join() !== "1,2")
+          fail("read-order", `read returned sequences ${r.map((x) => x.sequence).join()}`);
+      },
+    ],
+    [
+      "a stale expectedSequence is refused with the real tip and writes nothing",
+      async () => {
+        await store.append("c-stale", 0, rec(1));
+        const s = await store.append("c-stale", 0, rec(2));
+        if (s.ok || s.tip !== 1)
+          fail("stale-append", `a stale append returned ${JSON.stringify(s)}`);
+        const ahead = await store.append("c-stale", 5, rec(3));
+        if (ahead.ok || ahead.tip !== 1)
+          fail("gap-append", `an append past the tip (a gap) returned ${JSON.stringify(ahead)}`);
+        const r = await store.read("c-stale");
+        if (r.length !== 1) fail("refused-wrote", `a refused append left ${r.length} records`);
+      },
+    ],
+    [
+      "of N concurrent appends at one tip exactly one wins",
+      async () => {
+        const outs = await Promise.all(
+          Array.from({ length: 8 }, (_, i) => store.append("c-race", 0, rec(i)))
+        );
+        const wins = outs.filter((o) => o.ok).length;
+        if (wins !== 1) fail("race", `${wins} of 8 concurrent appends at the same tip won`);
+        const r = await store.read("c-race");
+        if (r.length !== 1) fail("race-log", `the raced line holds ${r.length} records`);
+      },
+    ],
+    [
+      "lines are independent",
+      async () => {
+        await store.append("c-iso-a", 0, rec(1));
+        const b = await store.append("c-iso-b", 0, rec(2));
+        if (!b.ok)
+          fail("isolation", "an append to a second line was refused by the first line's tip");
+        if ((await store.read("c-iso-a")).length !== 1)
+          fail("isolation", "a line holds another's record");
+      },
+    ],
+    [
+      "payloads round-trip and neither side aliases the log",
+      async () => {
+        const payload = { nested: { list: [1, 2, { k: "v" }] } };
+        await store.append("c-copy", 0, {
+          type: "EXPERIENCE_COMPOSED",
+          payload,
+          at: "2026-10-06T00:00:00.000Z",
+        });
+        payload.nested.list.push(3);
+        const first = await store.read("c-copy");
+        if (
+          JSON.stringify(first[0]?.payload) !==
+          JSON.stringify({ nested: { list: [1, 2, { k: "v" }] } })
+        )
+          fail("copy-in", "mutating a payload after append changed the stored record");
+        (
+          first as unknown as Array<{ payload: { nested: { list: unknown[] } } }>
+        )[0]?.payload.nested.list.push(9);
+        const second = await store.read("c-copy");
+        if (JSON.stringify(second[0]?.payload).includes("9"))
+          fail("copy-out", "mutating a read result changed the stored record");
+        if (
+          second[0]?.type !== "EXPERIENCE_COMPOSED" ||
+          second[0]?.at !== "2026-10-06T00:00:00.000Z"
+        )
+          fail("fields", "type or at did not round-trip");
+      },
+    ],
+    [
+      "optional readTail / readAfter / listStreams agree with read (when implemented)",
+      async () => {
+        for (let i = 0; i < 5; i++) await store.append("c-opt", i, rec(i));
+        const all = await store.read("c-opt");
+        const seqs = (r: readonly { sequence: number }[]) => r.map((x) => x.sequence).join();
+        if (store.readTail !== undefined) {
+          if (seqs(await store.readTail("c-opt", 2)) !== "4,5")
+            fail("read-tail", "readTail(2) did not return the newest two records in order");
+          if (seqs(await store.readTail("c-opt", 99)) !== seqs(all))
+            fail("read-tail", "readTail past the length did not return the whole line");
+          if ((await store.readTail("c-opt-none", 3)).length !== 0)
+            fail("read-tail", "readTail of an unknown line was not empty");
+        }
+        if (store.readAfter !== undefined) {
+          if (seqs(await store.readAfter("c-opt", 3)) !== "4,5")
+            fail("read-after", "readAfter(3) did not return the records past sequence 3");
+          if (seqs(await store.readAfter("c-opt", 0, 2)) !== "1,2")
+            fail("read-after", "readAfter(0, 2) did not honour the limit");
+          if ((await store.readAfter("c-opt", 5)).length !== 0)
+            fail("read-after", "readAfter at the tip was not empty");
+        }
+        if (store.listStreams !== undefined) {
+          const ids: string[] = [];
+          for await (const id of store.listStreams()) ids.push(id);
+          if (!ids.includes("c-opt") || new Set(ids).size !== ids.length)
+            fail("list-streams", "listStreams missed a line or listed one twice");
+        }
+      },
+    ],
+  ];
+  for (const [name, run] of cases) {
+    try {
+      await run();
+    } catch (err) {
+      fail("store-threw", `${name}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return findings;
+}

package/src/derive.ts

@@ -0,0 +1,57 @@
+import { type Experience, type Provenance, carryClasses } from "@loomwork/ui-core";
+
+// ── Versions that are not "ops on a parent" ───────────────────────────────────
+// A revert and a branch adopt an OLDER artifact's content, so they are not expressible as ops
+// from the head. They are deterministic functions of two artifacts instead, which is what makes
+// them verifiable: `Lineage.verify` recomputes them from the log and compares the content address.
+//
+// THE CLASS RULE (fail-closed): the artifact adopted is older than the line. Everything the line
+// ever learned about how confidential a handle, tool or projection is lives in the sticky class
+// maps of its LATEST version, and the adopted artifact predates some of it. Both functions
+// therefore fold the classes of the artifact the line had reached (`head` for a revert, the source
+// head at the fork for a branch) into the adopted one with `carryClasses` — `strictest`, never
+// lower — INCLUDING classes only that artifact's live nodes carried (they would vanish with the
+// nodes). A restored version can be stricter than it was when first written; it can never be laxer
+// than what the line knew. The one op that lowers a class, a trusted `declassify*`, is a normal
+// composed version: reverting past it re-raises the class (the old artifact still holds it), which
+// is the safe direction; declassifying again is how an operator lowers it for good.
+
+export interface Authored {
+  readonly by: Provenance;
+  readonly at: string;
+}
+
+/** The unsealed artifact a revert to `target` produces on top of `head`. Same line, same id. */
+export function revertArtifact(head: Experience, target: Experience, a: Authored): Experience {
+  const adopted: Experience = {
+    ...target,
+    experienceId: head.experienceId,
+    versionHash: "",
+    parents: [head.versionHash],
+    meta: { author: authorOf(a.by), createdAt: a.at, sourceKind: "revert" },
+  };
+  return carryClasses(head, adopted);
+}
+
+/**
+ * The unsealed first artifact of the line `experienceId`, forked from `source` with the classes of
+ * `carriedFrom` (the source line's head at the fork) carried in. Its parent is `source` — a version
+ * of ANOTHER line, which is how a branch is told from a genesis.
+ */
+export function branchArtifact(
+  source: Experience,
+  carriedFrom: Experience,
+  experienceId: string,
+  a: Authored
+): Experience {
+  const adopted: Experience = {
+    ...source,
+    experienceId,
+    versionHash: "",
+    parents: [source.versionHash],
+    meta: { author: authorOf(a.by), createdAt: a.at, sourceKind: "branch" },
+  };
+  return carryClasses(carriedFrom, adopted);
+}
+
+export const authorOf = (by: Provenance): string => by.agentId ?? by.ref ?? by.source;

package/src/events.ts

@@ -0,0 +1,125 @@
+import { Operation, Provenance, Sensitivity } from "@loomwork/ui-core";
+import { z } from "zod";
+
+// ── The lineage event protocol ────────────────────────────────────────────────
+// A lineage is the append-only log of ONE experience's versions. Every entry is an event whose
+// type names what happened and whose payload carries the content address (`ref`) of the stored
+// artifact plus enough to VERIFY it without trusting the blob:
+//
+//   EXPERIENCE_COMPOSED  a version produced by ops folded onto its parent (or the genesis, ops [])
+//   EXPERIENCE_REVERTED  a version that restores an older artifact's content as a NEW version
+//   EXPERIENCE_BRANCHED  the first version of a NEW lineage forked from a version of another
+//   EXPERIENCE_PROMOTED  the app chose to SHOW a version (head is "latest", promoted is "shown")
+//
+// `EXPERIENCE_COMPOSED` is the same name and `{ ref, parents, ops }` core's `log.ts` declared as a
+// userspace convention; here it gains a producer, a consumer and a validator. The extra fields
+// (`experienceId`, `versionHash`, `by`) are additive. `EXPERIENCE_PROMOTED` is redeclared (not
+// imported) because importing it from `@loomwork/ui-planner` would put the planner's whole graph —
+// hydration, the sandbox — into a server-side store package; `lineage.test.ts` asserts the two
+// spellings never drift.
+
+export const EXPERIENCE_COMPOSED = "EXPERIENCE_COMPOSED";
+export const EXPERIENCE_REVERTED = "EXPERIENCE_REVERTED";
+export const EXPERIENCE_BRANCHED = "EXPERIENCE_BRANCHED";
+export const EXPERIENCE_PROMOTED = "EXPERIENCE_PROMOTED";
+
+export type LineageEventType =
+  | typeof EXPERIENCE_COMPOSED
+  | typeof EXPERIENCE_REVERTED
+  | typeof EXPERIENCE_BRANCHED
+  | typeof EXPERIENCE_PROMOTED;
+
+const ContentRefSchema = z.object({ __loomContent: z.string().min(1) });
+const Hash = z.string().min(1);
+
+const RecordedOperationSchema = z.object({
+  op: Operation,
+  baseVersion: z.string().optional(),
+  by: Provenance,
+  at: z.string(),
+});
+
+const Common = {
+  experienceId: z.string().min(1),
+  versionHash: Hash,
+  ref: ContentRefSchema,
+  parents: z.array(Hash),
+  by: Provenance,
+};
+
+export const ComposedPayload = z.object({
+  ...Common,
+  ops: z.array(RecordedOperationSchema),
+  /**
+   * What the author said about the change (U7): UNTRUSTED text (a planner's model text), bounded
+   * and stripped by `boundSummary` on the way in AND on the way out of the fold, since the log is
+   * untrusted input. Optional, so every version written before it replays unchanged; it is not in
+   * the content address (nothing here is).
+   */
+  summary: z.string().optional(),
+  /**
+   * The strictest class of everything the author READ to write `summary` (the experience, tool
+   * samples, caller context), stamped by the host at compose. A summary is judged against it (and
+   * against the version's own class floor) before a viewer is shown it. Recorded on the event, not
+   * in the content address. Absent = unknown, and the floor alone gates the summary.
+   */
+  summaryClass: Sensitivity.optional(),
+});
+export const RevertedPayload = z.object({ ...Common, revertedTo: Hash });
+export const BranchedPayload = z.object({
+  ...Common,
+  from: z.object({ experienceId: z.string().min(1), versionHash: Hash }),
+  /** The version of the SOURCE line whose sticky classes were carried in (its head at the fork). */
+  carriedFrom: Hash,
+});
+export const PromotedPayload = z.object({
+  ref: ContentRefSchema,
+  experienceId: z.string().min(1),
+  versionHash: Hash,
+  by: Provenance,
+});
+
+export type ComposedPayload = z.infer<typeof ComposedPayload>;
+export type SummaryClass = NonNullable<ComposedPayload["summaryClass"]>;
+export type RevertedPayload = z.infer<typeof RevertedPayload>;
+export type BranchedPayload = z.infer<typeof BranchedPayload>;
+export type PromotedPayload = z.infer<typeof PromotedPayload>;
+
+export const PAYLOAD_SCHEMAS = {
+  [EXPERIENCE_COMPOSED]: ComposedPayload,
+  [EXPERIENCE_REVERTED]: RevertedPayload,
+  [EXPERIENCE_BRANCHED]: BranchedPayload,
+  [EXPERIENCE_PROMOTED]: PromotedPayload,
+} as const;
+
+export const isLineageEventType = (t: string): t is LineageEventType =>
+  Object.hasOwn(PAYLOAD_SCHEMAS, t);
+
+/**
+ * The payload paths that carry host or model TEXT, per event type: the op props and labels, the
+ * author's `summary` and the `by` provenance (a user's own words and ids). These are what a host
+ * seals under its owner's key so erasing the owner makes the line unreadable
+ * (`registerLineageSensitivePaths`). Everything else on an event is an identifier (`experienceId`,
+ * `versionHash`, `ref`, `parents`, `from`, `carriedFrom`, `revertedTo`) or a class
+ * (`summaryClass`), and stays plain so the log's structure survives the key.
+ *
+ * `ops` is one path: it covers every nested op's `by`, props, labels and prompt text.
+ */
+export const LINEAGE_SENSITIVE_PATHS: Readonly<Record<LineageEventType, readonly string[]>> = {
+  [EXPERIENCE_COMPOSED]: ["ops", "summary", "by"],
+  [EXPERIENCE_REVERTED]: ["by"],
+  [EXPERIENCE_BRANCHED]: ["by"],
+  [EXPERIENCE_PROMOTED]: ["by"],
+};
+
+/**
+ * Register {@link LINEAGE_SENSITIVE_PATHS} on a crypto event store (`EncryptingEventStore`'s
+ * `registerSensitive`). Call it once at composition, before the first lineage write: what was
+ * written before stays plaintext.
+ */
+export function registerLineageSensitivePaths(store: {
+  registerSensitive(eventType: string, paths: readonly string[]): void;
+}): void {
+  for (const [type, paths] of Object.entries(LINEAGE_SENSITIVE_PATHS))
+    store.registerSensitive(type, paths);
+}

package/src/index.ts

@@ -0,0 +1,79 @@
+export { LineErasedError, LineUnreadableError, Lineage, classifyLineFailure } from "./lineage";
+export type { LineBlockedError, PinsExtra } from "./lineage";
+export type {
+  Committed,
+  HeadMoved,
+  LineageOptions,
+  LineageResult,
+  PromotedMoved,
+  Refusal,
+  Refused,
+} from "./lineage";
+export { branchArtifact, revertArtifact } from "./derive";
+export type { Authored } from "./derive";
+export {
+  BranchedPayload,
+  ComposedPayload,
+  EXPERIENCE_BRANCHED,
+  EXPERIENCE_COMPOSED,
+  EXPERIENCE_PROMOTED,
+  EXPERIENCE_REVERTED,
+  LINEAGE_SENSITIVE_PATHS,
+  PromotedPayload,
+  RevertedPayload,
+  registerLineageSensitivePaths,
+} from "./events";
+export type { LineageEventType, SummaryClass } from "./events";
+export { foldLineage } from "./state";
+export type { Fold, LineageState, VersionKind, VersionRecord } from "./state";
+export {
+  InMemoryLineageStore,
+  LINEAGE_STREAM_PREFIX,
+  LINEAGE_WORKFLOW_ID,
+  LOOM_UI_STREAM_NAMESPACE,
+  eventStoreLineageStore,
+} from "./store";
+export type {
+  AppendOutcome,
+  LineageRecord,
+  LineageStore,
+  PrefixedLineageStore,
+  StoredLineageRecord,
+} from "./store";
+export { checkLineageStoreConformance } from "./conformance";
+export {
+  DEFAULT_MAX_SEEN_VIEWS,
+  DEFAULT_MAX_SKEW_MS,
+  MAX_SEEN_READ,
+  SEEN_STREAM_PREFIX,
+  SEEN_WORKFLOW_ID,
+  SeenLog,
+  VIEWER_ERASED,
+  VIEWS_RETAINED,
+  VIEW_RECORDED,
+  ViewRecordPayload,
+  seenStoreOptions,
+  seenStreamKey,
+} from "./seen";
+export type {
+  SeenLogOptions,
+  SeenRefusal,
+  SeenResult,
+  SeenRetention,
+  SeenUnreadable,
+  SeenView,
+} from "./seen";
+export {
+  InMemorySeenKeyStore,
+  SEALED_REF_BLOCK,
+  checkSeenKeyStoreConformance,
+  seenKeySubject,
+} from "./seenCrypto";
+export type { SeenKeyStore } from "./seenCrypto";
+export { collectSeenGarbage, collectSeenRoots } from "./seenGc";
+export type { SeenGcOptions, SeenGcReport, SeenGcResult } from "./seenGc";
+
+export { DEFAULT_KEEP_LAST, retainedVersions, validateRetentionPolicy } from "./retention";
+export type { Retained, RetentionPolicy } from "./retention";
+export { rootsFor } from "./rootsFor";
+export type { RootsForOptions } from "./rootsFor";