@loomwork/ui-changes 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@loomwork/ui-changes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Ambient change delivery for loom-ui: a ChangeFeed over lineage events (resume from a cursor, at-least-once, idempotent ids), viewer-safe change descriptions, a per-viewer unread cursor seam, and polling / push head signals",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/esm/index.js",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/index.js",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@loomwork/classify": "^0.1.0",
+    "@loomwork/event-runtime": "^0.1.0",
+    "@loomwork/ui-core": "^0.1.1",
+    "@loomwork/ui-lineage": "^0.1.1"
+  },
+  "devDependencies": {
+    "@loomwork/plugin-content": "^0.1.0",
+    "@loomwork/plugin-crypto": "^0.1.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chhetrisushil/loom-ui.git",
+    "directory": "packages/changes"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-support.ts",
+    "!src/**/__tests__",
+    "!src/**/__fixtures__",
+    "!src/**/__snapshots__",
+    "!src/**/__golden__",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build && rm -rf dist/esm && tsc -p tsconfig.esm.json",
+    "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  }
 }

package/src/conformance.ts

@@ -0,0 +1,248 @@
+import type { Finding } from "@loomwork/ui-core";
+import type { UnreadStore } from "./cursor";
+import type { ChangeEvent, ChangeFeed } from "./feed";
+
+// ── Conformance kits ──────────────────────────────────────────────────────────
+// Findings, never throws (a feed or store that throws on a case is reported as a finding), like
+// `checkLineageStoreConformance`.
+
+export interface FeedHarness {
+  readonly feed: ChangeFeed;
+  /** Append one new version to `experienceId`'s line (the first call starts the line). */
+  compose(experienceId: string): Promise<void>;
+  /**
+   * Force one wake of the feed's signal, for a deterministic harness (a manual-tick signal). Omit
+   * for a real timer/push signal: the kit then waits (up to `waitMs`) for delivery.
+   */
+  tick?(): Promise<void>;
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function until(cond: () => boolean, tick: (() => Promise<void>) | undefined, waitMs: number) {
+  const end = Date.now() + waitMs;
+  for (;;) {
+    if (tick !== undefined) await tick();
+    if (cond()) return true;
+    if (Date.now() > end) return false;
+    await sleep(5);
+  }
+}
+
+export async function checkChangeFeedConformance(
+  make: () => FeedHarness | Promise<FeedHarness>,
+  opts: { waitMs?: number } = {}
+): Promise<Finding[]> {
+  const findings: Finding[] = [];
+  const fail = (code: string, message: string) =>
+    findings.push({ code, severity: "error", message });
+  const waitMs = opts.waitMs ?? 1500;
+  const h = await make();
+  const read = async (id: string, o?: { after?: number; limit?: number }) => {
+    const r = await h.feed.read(id, o);
+    if (!r.ok) throw new Error(`read failed: ${r.finding.message}`);
+    return r;
+  };
+  const cases: Array<[string, () => Promise<void>]> = [
+    [
+      "an unknown line reads empty with tip 0",
+      async () => {
+        const r = await read("f-empty");
+        if (r.events.length !== 0 || r.cursor !== 0 || r.tip !== 0 || r.more)
+          fail("read-empty", `an unknown line read ${JSON.stringify(r)}`);
+      },
+    ],
+    [
+      "events are dense, ordered, with unique ids that are stable across reads",
+      async () => {
+        for (let i = 0; i < 3; i++) await h.compose("f-ids");
+        const a = await read("f-ids");
+        const b = await read("f-ids");
+        if (a.events.map((e) => e.sequence).join() !== "1,2,3")
+          fail("sequence", `sequences ${a.events.map((e) => e.sequence).join()} are not 1,2,3`);
+        if (new Set(a.events.map((e) => e.id)).size !== a.events.length)
+          fail("ids-unique", "two events share an id");
+        if (a.events.map((e) => e.id).join() !== b.events.map((e) => e.id).join())
+          fail("ids-stable", "re-reading the same range changed an id");
+        if (a.cursor !== 3 || a.tip !== 3) fail("cursor", `cursor/tip were ${a.cursor}/${a.tip}`);
+      },
+    ],
+    [
+      "reading after a cursor returns only later events",
+      async () => {
+        for (let i = 0; i < 3; i++) await h.compose("f-resume");
+        const r = await read("f-resume", { after: 1 });
+        if (r.events.map((e) => e.sequence).join() !== "2,3")
+          fail("resume", `after 1 returned ${r.events.map((e) => e.sequence).join()}`);
+        const none = await read("f-resume", { after: 3 });
+        if (none.events.length !== 0 || none.cursor !== 3)
+          fail("resume-end", `after the tip returned ${JSON.stringify(none)}`);
+      },
+    ],
+    [
+      "paging by limit visits every event once, in order",
+      async () => {
+        for (let i = 0; i < 5; i++) await h.compose("f-page");
+        const seen: number[] = [];
+        let cursor = 0;
+        for (let guard = 0; guard < 10; guard++) {
+          const r = await read("f-page", { after: cursor, limit: 2 });
+          if (r.events.length > 2) fail("limit", `limit 2 returned ${r.events.length}`);
+          seen.push(...r.events.map((e) => e.sequence));
+          cursor = r.cursor;
+          if (!r.more) break;
+        }
+        if (seen.join() !== "1,2,3,4,5") fail("paging", `paging saw ${seen.join()}`);
+        const bad = await h.feed.read("f-page", { after: -1 });
+        if (bad.ok) fail("cursor-invalid", "a negative cursor was accepted");
+        const badLimit = await h.feed.read("f-page", { limit: 0 });
+        if (badLimit.ok) fail("limit-invalid", "a zero limit was accepted");
+      },
+    ],
+    [
+      "subscribe catches up from a cursor, then follows live, in order",
+      async () => {
+        await h.compose("f-sub");
+        await h.compose("f-sub");
+        const got: ChangeEvent[] = [];
+        const off = h.feed.subscribe("f-sub", (e) => void got.push(e), { after: 1 });
+        const caught = await until(() => got.length >= 1, h.tick, waitMs);
+        if (!caught || got[0]?.sequence !== 2)
+          fail("sub-catchup", `catch-up from 1 delivered ${got.map((e) => e.sequence).join()}`);
+        await h.compose("f-sub");
+        const live = await until(() => got.length >= 2, h.tick, waitMs);
+        if (!live || got.map((e) => e.sequence).join() !== "2,3")
+          fail("sub-live", `live delivery gave ${got.map((e) => e.sequence).join()}`);
+        off();
+        await h.compose("f-sub");
+        await sleep(40);
+        if (h.tick) await h.tick();
+        await sleep(20);
+        if (got.length !== 2) fail("sub-off", "an event was delivered after unsubscribe");
+      },
+    ],
+    [
+      "resubscribing from an older cursor redelivers the SAME ids (at-least-once, idempotent)",
+      async () => {
+        await h.compose("f-redo");
+        await h.compose("f-redo");
+        const first: string[] = [];
+        const offA = h.feed.subscribe("f-redo", (e) => void first.push(e.id));
+        await until(() => first.length >= 2, h.tick, waitMs);
+        offA();
+        const again: string[] = [];
+        const offB = h.feed.subscribe("f-redo", (e) => void again.push(e.id), { after: 0 });
+        await until(() => again.length >= 2, h.tick, waitMs);
+        offB();
+        if (first.join() !== again.join() || first.length !== 2)
+          fail("redelivery", `first ${first.join()} vs again ${again.join()}`);
+      },
+    ],
+    [
+      "a throwing handler is reported, not advanced past, and the event is delivered again",
+      async () => {
+        await h.compose("f-throw");
+        const errors: unknown[] = [];
+        const ids: string[] = [];
+        let attempts = 0;
+        const off = h.feed.subscribe(
+          "f-throw",
+          (e) => {
+            attempts += 1;
+            if (attempts === 1) throw new Error("handler down");
+            ids.push(e.id);
+          },
+          { onError: (e) => void errors.push(e), retry: { baseMs: 5, maxMs: 20 } }
+        );
+        await until(() => errors.length >= 1, h.tick, waitMs);
+        if (errors.length < 1) fail("handler-error", "a throwing handler was not reported");
+        // NO append and NO signal from here: a quiet line must still redeliver the failed event
+        // (a feed that retries only when the head moves leaves it stuck).
+        await until(() => ids.length >= 1, undefined, waitMs);
+        off();
+        if (ids.join() !== "f-throw#1")
+          fail("handler-retry", `after a throw on a quiet line the handler saw ${ids.join()}`);
+      },
+    ],
+  ];
+  for (const [name, run] of cases) {
+    try {
+      await run();
+    } catch (e) {
+      fail("feed-threw", `${name}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  return findings;
+}
+
+export async function checkUnreadStoreConformance(
+  make: () => UnreadStore | Promise<UnreadStore>
+): Promise<Finding[]> {
+  const findings: Finding[] = [];
+  const fail = (code: string, message: string) =>
+    findings.push({ code, severity: "error", message });
+  const s = await make();
+  const cases: Array<[string, () => Promise<void>]> = [
+    [
+      "an unseen (viewer, line) is 0",
+      async () => {
+        if ((await s.get("u-none", "e")) !== 0) fail("default", "an unseen cursor was not 0");
+      },
+    ],
+    [
+      "advance moves forward, never back, and is idempotent",
+      async () => {
+        const a = await s.advance("u-fwd", "e", 5);
+        const b = await s.advance("u-fwd", "e", 3);
+        const c = await s.advance("u-fwd", "e", 5);
+        if (a !== 5 || b !== 5 || c !== 5 || (await s.get("u-fwd", "e")) !== 5)
+          fail("monotone", `advance returned ${[a, b, c].join()}`);
+      },
+    ],
+    [
+      "invalid positions change nothing",
+      async () => {
+        await s.advance("u-bad", "e", 2);
+        for (const bad of [
+          -1,
+          1.5,
+          Number.NaN,
+          Number.POSITIVE_INFINITY,
+          "9" as unknown as number,
+        ]) {
+          const r = await s.advance("u-bad", "e", bad);
+          if (r !== 2) fail("invalid", `advance(${String(bad)}) returned ${r}`);
+        }
+      },
+    ],
+    [
+      "cursors are per viewer and per line, with no id collisions",
+      async () => {
+        await s.advance("u-a", "e1", 4);
+        await s.advance("u-c", "a:b", 9);
+        if ((await s.get("u-c:a", "b")) !== 0)
+          fail("collision", "ids that join to the same string share a cursor");
+        if ((await s.get("u-a", "e2")) !== 0) fail("per-line", "another line shared a cursor");
+        if ((await s.get("u-b", "e1")) !== 0) fail("per-viewer", "another viewer shared a cursor");
+        if ((await s.get("u-a", "e1")) !== 4)
+          fail("collision", "a joined-looking id disturbed a cursor");
+      },
+    ],
+    [
+      "concurrent advances land on the maximum",
+      async () => {
+        await Promise.all([1, 7, 3, 5, 2].map((n) => s.advance("u-race", "e", n)));
+        if ((await s.get("u-race", "e")) !== 7)
+          fail("race", "concurrent advances did not end at the max");
+      },
+    ],
+  ];
+  for (const [name, run] of cases) {
+    try {
+      await run();
+    } catch (e) {
+      fail("store-threw", `${name}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  return findings;
+}

package/src/cursor.ts

@@ -0,0 +1,89 @@
+import type { Finding } from "@loomwork/ui-core";
+import type { ChangeEvent, ChangeFeed } from "./feed";
+
+// ── Unread: what a viewer has not yet seen ────────────────────────────────────
+// A cursor per (viewer, experience): the last feed `sequence` the viewer has acknowledged. Unread
+// is everything after it. The cursor only moves FORWARD and is clamped to the log's tip, so a
+// replayed acknowledgement is harmless (idempotent) and a viewer cannot pre-read the future.
+//
+// `viewerId` is the caller's claim: this package performs no authentication or authorization (the
+// host resolves who the viewer is, and what they may see, before it calls here).
+
+export interface UnreadStore {
+  /** The viewer's cursor for the line; 0 when none was ever recorded. */
+  get(viewerId: string, experienceId: string): Promise<number>;
+  /**
+   * Move the cursor to `max(current, to)` and return the result. A `to` that is not a non-negative
+   * safe integer changes nothing. Atomic against concurrent advances: the cursor never goes back.
+   */
+  advance(viewerId: string, experienceId: string, to: number): Promise<number>;
+}
+
+export class InMemoryUnreadStore implements UnreadStore {
+  // Nested maps, not a joined key: no separator a viewer or experience id could contain.
+  private readonly cursors = new Map<string, Map<string, number>>();
+
+  async get(viewerId: string, experienceId: string): Promise<number> {
+    return this.cursors.get(viewerId)?.get(experienceId) ?? 0;
+  }
+
+  async advance(viewerId: string, experienceId: string, to: number): Promise<number> {
+    const current = this.cursors.get(viewerId)?.get(experienceId) ?? 0;
+    if (!Number.isSafeInteger(to) || to <= current) return current;
+    let mine = this.cursors.get(viewerId);
+    if (mine === undefined) {
+      mine = new Map();
+      this.cursors.set(viewerId, mine);
+    }
+    mine.set(experienceId, to);
+    return to;
+  }
+}
+
+export type UnreadResult =
+  | {
+      readonly ok: true;
+      readonly events: readonly ChangeEvent[];
+      /** The viewer's cursor when read. */
+      readonly cursor: number;
+      /** More unread events exist past this page. */
+      readonly more: boolean;
+    }
+  | { readonly ok: false; readonly finding: Finding };
+
+/** The events the viewer has not acknowledged, oldest first, one page. */
+export async function unreadChanges(
+  feed: ChangeFeed,
+  store: UnreadStore,
+  viewerId: string,
+  experienceId: string,
+  opts: { limit?: number } = {}
+): Promise<UnreadResult> {
+  const cursor = await store.get(viewerId, experienceId);
+  const r = await feed.read(experienceId, {
+    after: cursor,
+    ...(opts.limit !== undefined && { limit: opts.limit }),
+  });
+  return r.ok ? { ok: true, events: r.events, cursor, more: r.more } : r;
+}
+
+/**
+ * Acknowledge everything through `through` (clamped to the log's tip). Returns the new cursor, or
+ * the finding when the line could not be read (then nothing moves).
+ */
+export async function markRead(
+  feed: ChangeFeed,
+  store: UnreadStore,
+  viewerId: string,
+  experienceId: string,
+  through: number
+): Promise<{ ok: true; cursor: number } | { ok: false; finding: Finding }> {
+  const r = await feed.read(experienceId, { limit: 1, after: Number.MAX_SAFE_INTEGER });
+  if (!r.ok) return r;
+  if (!Number.isSafeInteger(through) || through < 0)
+    return { ok: true, cursor: await store.get(viewerId, experienceId) };
+  return {
+    ok: true,
+    cursor: await store.advance(viewerId, experienceId, Math.min(through, r.tip)),
+  };
+}