@loomwork/ui-lineage 0.0.0-stage → 0.1.0

package/dist/state.d.ts

@@ -0,0 +1,66 @@
+import { type Finding, type Provenance, type RecordedOperation } from "@loomwork/ui-core";
+import { type SummaryClass } from "./events";
+import type { StoredLineageRecord } from "./store";
+export type VersionKind = "composed" | "reverted" | "branched";
+export interface VersionRecord {
+    readonly experienceId: string;
+    readonly versionHash: string;
+    readonly ref: {
+        readonly __loomContent: string;
+    };
+    readonly parents: readonly string[];
+    readonly kind: VersionKind;
+    /** Position in the line's event log. */
+    readonly sequence: number;
+    readonly at: string;
+    readonly by: Provenance;
+    /** The ops folded onto the parent (`composed` only; `[]` otherwise and for a genesis). */
+    readonly ops: readonly RecordedOperation[];
+    /** `composed`: what the author said about the change; untrusted text, already bounded. */
+    readonly summary?: string;
+    /** `composed`: the class of what the summary was written from (host-stamped); see `ComposedPayload`. */
+    readonly summaryClass?: SummaryClass;
+    /** `reverted`: the version whose content this restores. */
+    readonly revertedTo?: string;
+    /** `branched`: the version of another line this forked, and the source head classes came from. */
+    readonly from?: {
+        readonly experienceId: string;
+        readonly versionHash: string;
+    };
+    readonly carriedFrom?: string;
+}
+export interface LineageState {
+    readonly experienceId: string;
+    /** The event log's tip (0 = empty): the compare-and-set token of the STORE. */
+    readonly sequence: number;
+    readonly versions: ReadonlyMap<string, VersionRecord>;
+    /** Version hashes in append order. */
+    readonly order: readonly string[];
+    /** The latest version (the CAS token of `advance`); null = the line has no version yet. */
+    readonly head: string | null;
+    /** The version the app chose to show; null = none promoted. */
+    readonly promoted: string | null;
+}
+/** Most ops one version may record. A longer array is a finding before the schema ever walks it. */
+export declare const MAX_OPS_PER_VERSION = 10000;
+/** How deep `prompt` ops may nest their `materialized` ops while being checked. */
+export declare const MAX_OP_NESTING = 16;
+/**
+ * The WRITE-SIDE twin of the fold's payload check: why `payload` would make the line unreadable
+ * (`lineage-event-invalid` on every later read), or undefined when it folds. A write that fails this
+ * must be refused BEFORE the append — the fold stays strict, the log has no delete, and one bad event
+ * would brick the line for everyone. `by` marks a provenance problem (the caller gives it its own code).
+ */
+export declare function payloadRefusal(type: string, payload: unknown): {
+    readonly code: "provenance-invalid" | "event-payload-invalid";
+    readonly message: string;
+} | undefined;
+export type Fold = {
+    ok: true;
+    state: LineageState;
+} | {
+    ok: false;
+    finding: Finding;
+};
+export declare function foldLineage(experienceId: string, records: readonly StoredLineageRecord[]): Fold;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,UAAU,EACf,KAAK,iBAAiB,EAGvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EASL,KAAK,YAAY,EAElB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAQnD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC3C,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,wGAAwG;IACxG,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAChF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACtD,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,oGAAoG;AACpG,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,mFAAmF;AACnF,eAAO,MAAM,cAAc,KAAK,CAAC;AAmCjC;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,GAEd;IAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,uBAAuB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3F,SAAS,CAiBZ;AAED,MAAM,MAAM,IAAI,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAOvF,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,mBAAmB,EAAE,GAAG,IAAI,CAQ/F"}

package/dist/state.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_OP_NESTING = exports.MAX_OPS_PER_VERSION = void 0;
+exports.payloadRefusal = payloadRefusal;
+exports.foldLineage = foldLineage;
+const ui_core_1 = require("@loomwork/ui-core");
+const events_1 = require("./events");
+/** Most ops one version may record. A longer array is a finding before the schema ever walks it. */
+exports.MAX_OPS_PER_VERSION = 10_000;
+/** How deep `prompt` ops may nest their `materialized` ops while being checked. */
+exports.MAX_OP_NESTING = 16;
+/**
+ * Why a stored ops array must not reach the (recursive) zod `Operation` schema, or undefined when
+ * it may. The schema recurses through `insertNode.node` and `prompt.materialized`, so a payload
+ * nested past the caps would blow the stack inside `safeParse` instead of returning an issue;
+ * a log is untrusted input (anyone with append access to the stream wrote it).
+ */
+function opsRefusal(ops) {
+    if (!Array.isArray(ops))
+        return undefined; // the schema reports the wrong shape
+    if (ops.length > exports.MAX_OPS_PER_VERSION)
+        return `records ${ops.length} ops, over the ${exports.MAX_OPS_PER_VERSION} limit`;
+    const stack = [];
+    for (const r of ops)
+        stack.push({ op: r?.op, nest: 1 });
+    let seen = 0;
+    for (let top = stack.pop(); top !== undefined; top = stack.pop()) {
+        const { op, nest } = top;
+        if (typeof op !== "object" || op === null)
+            continue;
+        if (++seen > exports.MAX_OPS_PER_VERSION * 2)
+            return "nests too many ops";
+        const node = op.node;
+        if (node !== undefined) {
+            const depth = (0, ui_core_1.treeDepth)(node);
+            if (depth > ui_core_1.MAX_TREE_DEPTH)
+                return `an op's node nests ${depth} levels, over the ${ui_core_1.MAX_TREE_DEPTH} limit`;
+        }
+        const inner = op.materialized;
+        if (Array.isArray(inner)) {
+            if (nest >= exports.MAX_OP_NESTING)
+                return `prompt ops nest over ${exports.MAX_OP_NESTING} levels`;
+            if (inner.length > exports.MAX_OPS_PER_VERSION)
+                return "a prompt op materializes too many ops";
+            for (const i of inner)
+                stack.push({ op: i, nest: nest + 1 });
+        }
+    }
+    return undefined;
+}
+/**
+ * The WRITE-SIDE twin of the fold's payload check: why `payload` would make the line unreadable
+ * (`lineage-event-invalid` on every later read), or undefined when it folds. A write that fails this
+ * must be refused BEFORE the append — the fold stays strict, the log has no delete, and one bad event
+ * would brick the line for everyone. `by` marks a provenance problem (the caller gives it its own code).
+ */
+function payloadRefusal(type, payload) {
+    if (!(0, events_1.isLineageEventType)(type))
+        return { code: "event-payload-invalid", message: `unknown event type ${String(type)}` };
+    try {
+        const tooBig = opsRefusal(payload?.ops);
+        if (tooBig !== undefined)
+            return { code: "event-payload-invalid", message: tooBig };
+        const parsed = events_1.PAYLOAD_SCHEMAS[type].safeParse(payload);
+        if (parsed.success)
+            return undefined;
+        const issue = parsed.error.issues[0];
+        const inBy = parsed.error.issues.some((i) => i.path.includes("by"));
+        return {
+            code: inBy ? "provenance-invalid" : "event-payload-invalid",
+            message: `${inBy ? "a provenance (`by`) is invalid" : "the event payload is malformed"}: ${issue?.message ?? "invalid"}${issue ? ` at ${issue.path.join(".")}` : ""}`,
+        };
+    }
+    catch (err) {
+        return { code: "event-payload-invalid", message: errMessage(err) };
+    }
+}
+const bad = (code, message) => ({
+    ok: false,
+    finding: { code, severity: "error", message },
+});
+function foldLineage(experienceId, records) {
+    try {
+        return foldChecked(experienceId, records);
+    }
+    catch (err) {
+        // Total by construction: whatever a hostile record does (a throwing getter, a shape the
+        // checks above did not anticipate) is a finding, never an exception out of every read.
+        return bad("lineage-event-invalid", `lineage "${experienceId}": ${errMessage(err)}`);
+    }
+}
+const errMessage = (err) => {
+    try {
+        return err instanceof Error ? err.message : String(err);
+    }
+    catch {
+        return "unreadable record";
+    }
+};
+function foldChecked(experienceId, records) {
+    const versions = new Map();
+    const order = [];
+    let head = null;
+    let promoted = null;
+    let expectedSequence = 0;
+    for (const rec of records) {
+        expectedSequence += 1;
+        if (typeof rec !== "object" || rec === null)
+            return bad("lineage-event-invalid", `lineage "${experienceId}" event #${expectedSequence}: the record is not an object`);
+        const where = `lineage "${experienceId}" event #${rec.sequence} (${rec.type})`;
+        if (rec.sequence !== expectedSequence)
+            return bad("lineage-sequence-gap", `${where}: expected sequence ${expectedSequence} — the log has a hole or a reorder`);
+        if (!(0, events_1.isLineageEventType)(rec.type))
+            return bad("lineage-event-unknown", `${where}: unknown type`);
+        const tooBig = opsRefusal(rec.payload?.ops);
+        if (tooBig !== undefined)
+            return bad("lineage-event-invalid", `${where}: ${tooBig}`);
+        const parsed = events_1.PAYLOAD_SCHEMAS[rec.type].safeParse(rec.payload);
+        if (!parsed.success)
+            return bad("lineage-event-invalid", `${where}: ${parsed.error.issues[0]?.message ?? "payload is malformed"}`);
+        const p = parsed.data;
+        if (p.experienceId !== experienceId)
+            return bad("lineage-event-foreign", `${where}: names experience "${p.experienceId}"`);
+        if (rec.type === events_1.EXPERIENCE_PROMOTED) {
+            if (!versions.has(p.versionHash))
+                return bad("lineage-promote-unknown", `${where}: promotes unknown version ${p.versionHash}`);
+            promoted = p.versionHash;
+            continue;
+        }
+        const v = p;
+        if (versions.has(v.versionHash))
+            return bad("lineage-version-duplicate", `${where}: version ${v.versionHash} already exists`);
+        if (rec.type === events_1.EXPERIENCE_BRANCHED) {
+            if (head !== null)
+                return bad("lineage-branch-midline", `${where}: only a line's first event`);
+        }
+        else if (head === null) {
+            if (rec.type !== events_1.EXPERIENCE_COMPOSED || v.parents.length !== 0)
+                return bad("lineage-genesis-invalid", `${where}: a line starts with a parentless composition`);
+        }
+        else if (v.parents.length !== 1 || v.parents[0] !== head) {
+            return bad("lineage-parent-mismatch", `${where}: parents ${JSON.stringify(v.parents)} are not the head ${head} it was appended on`);
+        }
+        const base = {
+            experienceId,
+            versionHash: v.versionHash,
+            ref: v.ref,
+            parents: v.parents,
+            sequence: rec.sequence,
+            at: rec.at,
+            by: v.by,
+        };
+        const record = rec.type === events_1.EXPERIENCE_COMPOSED
+            ? {
+                ...base,
+                kind: "composed",
+                ops: v.ops,
+                ...summaryOf(v.summary),
+                ...(v.summaryClass !== undefined && {
+                    summaryClass: v.summaryClass,
+                }),
+            }
+            : rec.type === events_1.EXPERIENCE_REVERTED
+                ? {
+                    ...base,
+                    kind: "reverted",
+                    ops: [],
+                    revertedTo: v.revertedTo,
+                }
+                : {
+                    ...base,
+                    kind: "branched",
+                    ops: [],
+                    from: v.from,
+                    carriedFrom: v.carriedFrom,
+                };
+        versions.set(v.versionHash, record);
+        order.push(v.versionHash);
+        head = v.versionHash;
+    }
+    return {
+        ok: true,
+        state: { experienceId, sequence: expectedSequence, versions, order, head, promoted },
+    };
+}
+const summaryOf = (raw) => {
+    const summary = (0, ui_core_1.boundSummary)(raw);
+    return summary === undefined ? {} : { summary };
+};
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,93 @@
+import { type EventStore } from "@loomwork/event-runtime";
+export interface LineageRecord {
+    readonly type: string;
+    readonly payload: unknown;
+    /** ISO-8601 time the event was recorded. */
+    readonly at: string;
+}
+export interface StoredLineageRecord extends LineageRecord {
+    /** 1-based position in this line. Dense: 1..n with no gaps. */
+    readonly sequence: number;
+}
+export type AppendOutcome = {
+    readonly ok: true;
+    readonly sequence: number;
+}
+/** The tip was not `expectedSequence`; `tip` is what it is now. Nothing was written. */
+ | {
+    readonly ok: false;
+    readonly tip: number;
+};
+export interface LineageStore {
+    /**
+     * Append `record` as sequence `expectedSequence + 1` iff the line's tip is EXACTLY
+     * `expectedSequence` (0 = the line is empty). Atomic: of N concurrent appends at the same
+     * `expectedSequence` exactly one wins and the rest get `{ ok: false }`. NEVER overwrites,
+     * never skips a sequence, and a refusal is a returned outcome, not a throw (a throw is an
+     * infrastructure failure and leaves the line untouched).
+     */
+    append(experienceId: string, expectedSequence: number, record: LineageRecord): Promise<AppendOutcome>;
+    /** Every record of the line in sequence order; `[]` for an unknown line. The caller owns the result. */
+    read(experienceId: string): Promise<readonly StoredLineageRecord[]>;
+    /**
+     * OPTIONAL — the newest `limit` records of the line, in sequence order (`[]` for an unknown line).
+     * Lets a long-lived per-viewer log answer "what is the tip?" without reading its whole history.
+     * Implement it together with {@link readAfter}; absent, callers fall back to `read` (O(log length)).
+     */
+    readTail?(experienceId: string, limit: number): Promise<readonly StoredLineageRecord[]>;
+    /**
+     * OPTIONAL — the records with `sequence > afterSequence`, in sequence order, at most `limit` of
+     * them (default: all). The retention window of a per-viewer log is read this way, so a read costs
+     * the size of the window, not the age of the log.
+     */
+    readAfter?(experienceId: string, afterSequence: number, limit?: number): Promise<readonly StoredLineageRecord[]>;
+    /**
+     * OPTIONAL — enumerate the ids of every line this store holds, in bounded pages. A collector
+     * (`SeenLog.collectGarbage`) needs it to find every root; a store that omits it cannot be
+     * garbage-collected (the collector refuses rather than guess a root set). Ids are exactly what
+     * `read` takes. Concurrent creation during a scan may be missed (a maintenance pass, not a snapshot).
+     */
+    listStreams?(): AsyncIterable<string>;
+}
+/** Reference in-memory store. Copies on the way in and out, so no caller can mutate the log. */
+export declare class InMemoryLineageStore implements LineageStore {
+    private readonly lines;
+    append(experienceId: string, expectedSequence: number, record: LineageRecord): Promise<AppendOutcome>;
+    read(experienceId: string): Promise<readonly StoredLineageRecord[]>;
+    readTail(experienceId: string, limit: number): Promise<readonly StoredLineageRecord[]>;
+    readAfter(experienceId: string, afterSequence: number, limit?: number): Promise<readonly StoredLineageRecord[]>;
+    listStreams(): AsyncGenerator<string, void, void>;
+}
+/** The reserved-stream namespace a lineage's events live under in an `EventStore`. */
+export declare const LINEAGE_STREAM_PREFIX = "__loom_ui_lineage__:";
+/** The `workflowId` a lineage event is written under unless `eventStoreLineageStore` is given another. */
+export declare const LINEAGE_WORKFLOW_ID = "loom-ui.lineage";
+/** Every stream prefix this package may write under; the kernel's own reserved prefixes are not ours. */
+export declare const LOOM_UI_STREAM_NAMESPACE = "__loom_ui_";
+/** A `LineageStore` that knows which stream prefix it writes under (see {@link eventStoreLineageStore}). */
+export interface PrefixedLineageStore extends LineageStore {
+    readonly streamPrefix: string;
+    /**
+     * The `workflowId` its events are written under. A `Lineage` passes it, with the stream id, as the
+     * `ContentAccess` of every artifact blob, so one host `subjectOf` covers events and blobs alike.
+     */
+    readonly workflowId?: string;
+}
+/**
+ * A `LineageStore` over loom's `EventStore`. One stream per experience
+ * (`__loom_ui_lineage__:<experienceId>`, a RESERVED stream so enumerators of real executions skip
+ * it; see the README for what a reserved stream costs); the lineage sequence IS the envelope sequence, so the CAS is the log's own
+ * `(executionId, sequence)` uniqueness. The adapter checks the tip first (a store enforces a
+ * taken slot, not a skipped one) and treats a `DuplicateSequenceError` from a racing writer as a
+ * lost CAS. Fencing, tenancy and sharding decorators wrap `store` as usual.
+ *
+ * `streamPrefix` must start with `__loom_ui_` (and say more): it is the namespace this package owns
+ * inside loom's reserved `__loom_` space, so a configuration can never write into the kernel's own
+ * control streams (`__loom_lifecycle__`, `__loom_erasure__`) or an execution's id space. `workflowId`
+ * is a short identifier. A bad value THROWS at construction (a misconfiguration, found at startup).
+ */
+export declare function eventStoreLineageStore(store: EventStore, opts?: {
+    readonly streamPrefix?: string;
+    readonly workflowId?: string;
+}): PrefixedLineageStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,UAAU,EAEhB,MAAM,yBAAyB,CAAC;AASjC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAoB,SAAQ,aAAa;IACxD,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AAClD,wFAAwF;GACtF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,MAAM,CACJ,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B,wGAAwG;IACxG,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;IACpE;;;;OAIG;IACH,QAAQ,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;IACxF;;;;OAIG;IACH,SAAS,CAAC,CACR,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,WAAW,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;CACvC;AAgBD,gGAAgG;AAChG,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4C;IAE5D,MAAM,CACV,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,aAAa,CAAC;IASnB,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC;IAInE,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC;IAKtF,SAAS,CACb,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,KAAK,SAA2B,GAC/B,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC;IAOnC,WAAW,IAAI,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC;CAGzD;AAED,sFAAsF;AACtF,eAAO,MAAM,qBAAqB,yBAAyB,CAAC;AAC5D,0GAA0G;AAC1G,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAGrD,yGAAyG;AACzG,eAAO,MAAM,wBAAwB,eAAe,CAAC;AAGrD,4GAA4G;AAC5G,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1E,oBAAoB,CAuFtB"}

package/dist/store.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOOM_UI_STREAM_NAMESPACE = exports.LINEAGE_WORKFLOW_ID = exports.LINEAGE_STREAM_PREFIX = exports.InMemoryLineageStore = void 0;
+exports.eventStoreLineageStore = eventStoreLineageStore;
+const event_runtime_1 = require("@loomwork/event-runtime");
+/**
+ * A lost slot, by class OR name (a store decorator or a second copy of the package throws an error
+ * that is not `instanceof` ours); mirrors the kernel's `isWriteConflict`.
+ */
+function isWriteConflict(err) {
+    if (err instanceof event_runtime_1.DuplicateSequenceError || err instanceof event_runtime_1.DuplicateEnvelopeIdError)
+        return true;
+    const name = err?.name;
+    return name === "DuplicateSequenceError" || name === "DuplicateEnvelopeIdError";
+}
+const clone = (v) => structuredClone(v);
+/** Reference in-memory store. Copies on the way in and out, so no caller can mutate the log. */
+class InMemoryLineageStore {
+    lines = new Map();
+    async append(experienceId, expectedSequence, record) {
+        const line = this.lines.get(experienceId) ?? [];
+        if (line.length !== expectedSequence)
+            return { ok: false, tip: line.length };
+        const sequence = line.length + 1;
+        line.push(clone({ ...record, sequence }));
+        this.lines.set(experienceId, line);
+        return { ok: true, sequence };
+    }
+    async read(experienceId) {
+        return clone(this.lines.get(experienceId) ?? []);
+    }
+    async readTail(experienceId, limit) {
+        const line = this.lines.get(experienceId) ?? [];
+        return clone(limit >= line.length ? line : line.slice(line.length - Math.max(0, limit)));
+    }
+    async readAfter(experienceId, afterSequence, limit = Number.POSITIVE_INFINITY) {
+        // dense 1..n: the records after `a` start at index `a`
+        const line = this.lines.get(experienceId) ?? [];
+        const from = Math.max(0, afterSequence);
+        return clone(line.slice(from, Number.isFinite(limit) ? from + Math.max(0, limit) : undefined));
+    }
+    async *listStreams() {
+        for (const id of [...this.lines.keys()])
+            yield id;
+    }
+}
+exports.InMemoryLineageStore = InMemoryLineageStore;
+/** The reserved-stream namespace a lineage's events live under in an `EventStore`. */
+exports.LINEAGE_STREAM_PREFIX = "__loom_ui_lineage__:";
+/** The `workflowId` a lineage event is written under unless `eventStoreLineageStore` is given another. */
+exports.LINEAGE_WORKFLOW_ID = "loom-ui.lineage";
+const WORKFLOW_ID = exports.LINEAGE_WORKFLOW_ID;
+/** Every stream prefix this package may write under; the kernel's own reserved prefixes are not ours. */
+exports.LOOM_UI_STREAM_NAMESPACE = "__loom_ui_";
+const WORKFLOW_ID_SHAPE = /^[A-Za-z0-9._:-]{1,128}$/;
+/**
+ * A `LineageStore` over loom's `EventStore`. One stream per experience
+ * (`__loom_ui_lineage__:<experienceId>`, a RESERVED stream so enumerators of real executions skip
+ * it; see the README for what a reserved stream costs); the lineage sequence IS the envelope sequence, so the CAS is the log's own
+ * `(executionId, sequence)` uniqueness. The adapter checks the tip first (a store enforces a
+ * taken slot, not a skipped one) and treats a `DuplicateSequenceError` from a racing writer as a
+ * lost CAS. Fencing, tenancy and sharding decorators wrap `store` as usual.
+ *
+ * `streamPrefix` must start with `__loom_ui_` (and say more): it is the namespace this package owns
+ * inside loom's reserved `__loom_` space, so a configuration can never write into the kernel's own
+ * control streams (`__loom_lifecycle__`, `__loom_erasure__`) or an execution's id space. `workflowId`
+ * is a short identifier. A bad value THROWS at construction (a misconfiguration, found at startup).
+ */
+function eventStoreLineageStore(store, opts = {}) {
+    const prefix = opts.streamPrefix ?? exports.LINEAGE_STREAM_PREFIX;
+    const workflowId = opts.workflowId ?? WORKFLOW_ID;
+    if (typeof prefix !== "string" ||
+        !prefix.startsWith(exports.LOOM_UI_STREAM_NAMESPACE) ||
+        prefix.length <= exports.LOOM_UI_STREAM_NAMESPACE.length ||
+        prefix.length > 128)
+        throw new Error(`streamPrefix must start with "${exports.LOOM_UI_STREAM_NAMESPACE}" and name its stream (got ${JSON.stringify(String(prefix).slice(0, 40))})`);
+    if (typeof workflowId !== "string" || !WORKFLOW_ID_SHAPE.test(workflowId))
+        throw new Error("workflowId must be 1-128 characters of [A-Za-z0-9._:-]");
+    const streamOf = (experienceId) => `${prefix}${experienceId}`;
+    return {
+        streamPrefix: prefix,
+        workflowId,
+        async append(experienceId, expectedSequence, record) {
+            const executionId = streamOf(experienceId);
+            const tip = (await (0, event_runtime_1.headOf)(store, executionId)) ?? 0;
+            if (tip !== expectedSequence)
+                return { ok: false, tip };
+            const sequence = expectedSequence + 1;
+            try {
+                await store.append({
+                    id: `${executionId}#${sequence}`,
+                    workflowId,
+                    executionId,
+                    eventType: record.type,
+                    sequence,
+                    timestamp: Date.parse(record.at) || 0,
+                    payload: clone(record.payload),
+                    metadata: { at: record.at },
+                });
+            }
+            catch (err) {
+                if (isWriteConflict(err))
+                    return { ok: false, tip: (await (0, event_runtime_1.headOf)(store, executionId)) ?? sequence };
+                throw err;
+            }
+            return { ok: true, sequence };
+        },
+        async read(experienceId) {
+            return toRecords(await store.read(streamOf(experienceId)));
+        },
+        async readTail(experienceId, limit) {
+            const id = streamOf(experienceId);
+            const tip = (await (0, event_runtime_1.headOf)(store, id)) ?? 0;
+            if (tip === 0 || limit <= 0)
+                return [];
+            return toRecords(await readWindow(store, id, Math.max(1, tip - limit + 1), tip));
+        },
+        async readAfter(experienceId, afterSequence, limit = Number.POSITIVE_INFINITY) {
+            const id = streamOf(experienceId);
+            const tip = (await (0, event_runtime_1.headOf)(store, id)) ?? 0;
+            const from = Math.max(1, afterSequence + 1);
+            const to = Number.isFinite(limit) ? Math.min(tip, from + Math.max(0, limit) - 1) : tip;
+            if (to < from)
+                return [];
+            return toRecords(await readWindow(store, id, from, to));
+        },
+        ...(store.listExecutionsPage !== undefined || store.listExecutions !== undefined
+            ? {
+                async *listStreams() {
+                    // Reserved streams ARE surfaced by the SPI's enumeration (`__loom_*`), so ours are found
+                    // by prefix. Pages are keyset-ordered by code point, so with pages the scan starts just
+                    // before our prefix and stops once past it; the unpaged fallback filters the full list.
+                    if (store.listExecutionsPage === undefined) {
+                        for (const id of (await store.listExecutions?.()) ?? [])
+                            if (id.startsWith(prefix))
+                                yield id.slice(prefix.length);
+                        return;
+                    }
+                    let cursor = prefix.slice(0, -1);
+                    for (;;) {
+                        const page = await store.listExecutionsPage({
+                            ...(cursor !== undefined && { cursor }),
+                            limit: 500,
+                        });
+                        for (const id of page.executionIds) {
+                            if (id.startsWith(prefix))
+                                yield id.slice(prefix.length);
+                            else if (id > prefix)
+                                return;
+                        }
+                        if (page.nextCursor === undefined || page.nextCursor === cursor)
+                            return;
+                        cursor = page.nextCursor;
+                    }
+                },
+            }
+            : {}),
+    };
+}
+function toRecords(events) {
+    return events
+        .slice()
+        .sort((a, b) => a.sequence - b.sequence)
+        .map((e) => ({
+        sequence: e.sequence,
+        type: e.eventType,
+        payload: clone(e.payload),
+        at: typeof e.metadata?.at === "string" ? e.metadata.at : new Date(e.timestamp).toISOString(),
+    }));
+}
+/** Sequences `from..to` (inclusive) of a stream: the store's `readRange`, else `readFrom`/`read` filtered. */
+async function readWindow(store, id, from, to) {
+    if (store.readRange !== undefined)
+        return store.readRange(id, from, to);
+    return (await store.read(id)).filter((e) => e.sequence >= from && e.sequence <= to);
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@loomwork/ui-lineage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Experience lineage runtime for loom-ui: a head pointer per experience with compare-and-set advance, version walk, branch and revert as new versions, and the EXPERIENCE_COMPOSED/PROMOTED protocol with replay verification, over loom's ContentStore and an EventStore-shaped seam",
+  "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/event-runtime": "^0.1.0",
+    "@loomwork/plugin-content": "^0.1.0",
+    "zod": "^3.23.8",
+    "@loomwork/ui-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@loomwork/plugin-crypto": "^0.1.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8",
+    "@loomwork/ui-planner": "^0.1.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chhetrisushil/loom-ui.git",
+    "directory": "packages/lineage"
+  },
+  "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"
+  }
 }