@fabric-harness/sdk 1.14.0 → 2.0.1

package/dist/conversation-projection.d.ts

@@ -0,0 +1,52 @@
+import type { ConversationStreamStore } from './conversation-stream.js';
+import type { SessionData, SessionEntry, SessionStore } from './types.js';
+/**
+ * Wrap a {@link SessionStore} so active-path appends are mirrored into an
+ * append-only {@link ConversationStreamStore} projection (v2 A4).
+ *
+ * The SessionEntry DAG stays the single source of truth; the stream gives
+ * clients offset-based catch-up + live tail. Two rules keep them coherent:
+ *
+ * 1. **Idempotent by entryId** — a crash between the DAG write and the
+ *    stream write is repaired on the next append: the projector diffs the
+ *    stream tail against the active path and re-emits anything missing.
+ * 2. **Truncation is explicit** — the DAG can branch (fork/replay/
+ *    checkpoint-restore rewrite `leafId`); the stream cannot. When `save()`
+ *    rewinds the active path, the projector appends a `truncated` record
+ *    and re-acquires the producer (epoch bump), so tailing clients see the
+ *    branch switch instead of silently reading a stale path.
+ *
+ * Projection failures are logged and swallowed — the conversation stream is
+ * an observability surface and must never fail the session write itself;
+ * the diff-repair on the next append restores consistency.
+ */
+export declare function withConversationProjection(store: SessionStore, streams: ConversationStreamStore, options?: {
+    producerId?: string;
+    onError?: (error: unknown) => void;
+}): SessionStore;
+export declare class ConversationProjector {
+    private readonly streams;
+    private readonly producerId;
+    private readonly onError;
+    private readonly producers;
+    constructor(streams: ConversationStreamStore, options?: {
+        producerId?: string;
+        onError?: (error: unknown) => void;
+    });
+    /** Mirror one appended entry, repairing any missed backlog first. */
+    projectAppend(store: SessionStore, sessionId: string, entry: SessionEntry): Promise<void>;
+    /** Handle whole-document saves (fork/replay/truncation rewrite the path). */
+    projectSave(data: SessionData): Promise<void>;
+    deleteStream(sessionId: string): Promise<void>;
+    private ensureProducer;
+    /** Fold the stream into the currently-projected entry ids (truncations rewind). */
+    private readProjectedEntryIds;
+    /**
+     * Diff the projected tail against the current active path. A pure
+     * extension appends the missing suffix; a divergence appends a
+     * `truncated` record (with a fresh producer epoch) then the new suffix.
+     */
+    private reproject;
+    private appendRecords;
+}
+//# sourceMappingURL=conversation-projection.d.ts.map

package/dist/conversation-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-projection.d.ts","sourceRoot":"","sources":["../src/conversation-projection.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,uBAAuB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,uBAAuB,EAChC,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAAO,GACxE,YAAY,CAyBd;AAUD,qBAAa,qBAAqB;IAM9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;gBAG3C,OAAO,EAAE,uBAAuB,EACjD,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;KAAO;IAQ3E,qEAAqE;IAC/D,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB/F,6EAA6E;IACvE,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7C,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAStC,cAAc;IAmB5B,mFAAmF;YACrE,qBAAqB;IAoBnC;;;;OAIG;YACW,SAAS;YAgCT,aAAa;CA6B5B"}

package/dist/conversation-projection.js

@@ -0,0 +1,207 @@
+import { ConversationStreamStoreError, conversationStreamPath, } from './conversation-stream.js';
+/**
+ * Wrap a {@link SessionStore} so active-path appends are mirrored into an
+ * append-only {@link ConversationStreamStore} projection (v2 A4).
+ *
+ * The SessionEntry DAG stays the single source of truth; the stream gives
+ * clients offset-based catch-up + live tail. Two rules keep them coherent:
+ *
+ * 1. **Idempotent by entryId** — a crash between the DAG write and the
+ *    stream write is repaired on the next append: the projector diffs the
+ *    stream tail against the active path and re-emits anything missing.
+ * 2. **Truncation is explicit** — the DAG can branch (fork/replay/
+ *    checkpoint-restore rewrite `leafId`); the stream cannot. When `save()`
+ *    rewinds the active path, the projector appends a `truncated` record
+ *    and re-acquires the producer (epoch bump), so tailing clients see the
+ *    branch switch instead of silently reading a stale path.
+ *
+ * Projection failures are logged and swallowed — the conversation stream is
+ * an observability surface and must never fail the session write itself;
+ * the diff-repair on the next append restores consistency.
+ */
+export function withConversationProjection(store, streams, options = {}) {
+    const projector = new ConversationProjector(streams, options);
+    const wrapped = {
+        ...store,
+        load: (id) => store.load(id),
+        save: async (data) => {
+            await store.save(data);
+            await projector.projectSave(data);
+        },
+    };
+    if (store.appendEntry) {
+        wrapped.appendEntry = async (sessionId, entry) => {
+            await store.appendEntry?.(sessionId, entry);
+            await projector.projectAppend(store, sessionId, entry);
+        };
+    }
+    if (store.delete) {
+        wrapped.delete = async (sessionId) => {
+            await store.delete?.(sessionId);
+            await projector.deleteStream(sessionId);
+        };
+    }
+    return wrapped;
+}
+export class ConversationProjector {
+    streams;
+    producerId;
+    onError;
+    producers = new Map();
+    constructor(streams, options = {}) {
+        this.streams = streams;
+        this.producerId = options.producerId ?? `projector-${Math.random().toString(16).slice(2)}`;
+        this.onError = options.onError ?? ((error) => {
+            console.error('[fabric-harness:conversation-projection] projection failed:', error);
+        });
+    }
+    /** Mirror one appended entry, repairing any missed backlog first. */
+    async projectAppend(store, sessionId, entry) {
+        try {
+            const producer = await this.ensureProducer(sessionId);
+            // Fast path: this entry directly extends the projected tail.
+            const last = producer.projectedEntryIds[producer.projectedEntryIds.length - 1];
+            if (entry.parentId && entry.parentId === last) {
+                await this.appendRecords(sessionId, producer, [{ kind: 'entry', entry }], [entry.id]);
+                return;
+            }
+            // Slow path: reproject from the session's current active path (covers
+            // missed appends, first projection of an existing session, and forks).
+            const data = await store.load(sessionId);
+            if (!data)
+                return;
+            await this.reproject(sessionId, producer, data);
+        }
+        catch (error) {
+            this.onError(error);
+        }
+    }
+    /** Handle whole-document saves (fork/replay/truncation rewrite the path). */
+    async projectSave(data) {
+        try {
+            const producer = await this.ensureProducer(data.id);
+            await this.reproject(data.id, producer, data);
+        }
+        catch (error) {
+            this.onError(error);
+        }
+    }
+    async deleteStream(sessionId) {
+        try {
+            await this.streams.delete(conversationStreamPath(sessionId));
+            this.producers.delete(sessionId);
+        }
+        catch (error) {
+            this.onError(error);
+        }
+    }
+    async ensureProducer(sessionId) {
+        const existing = this.producers.get(sessionId);
+        if (existing)
+            return existing;
+        const path = conversationStreamPath(sessionId);
+        await this.streams.createStream(path, { storeSessionId: sessionId });
+        const claim = await this.streams.acquireProducer(path, this.producerId);
+        const state = {
+            producerId: claim.producerId,
+            producerEpoch: claim.producerEpoch,
+            nextProducerSequence: claim.nextProducerSequence,
+            // Durable stream stores outlive this process: rebuild what has already
+            // been projected from the stream itself, otherwise the first
+            // post-restart diff would re-emit the entire path as duplicates.
+            projectedEntryIds: await this.readProjectedEntryIds(path),
+        };
+        this.producers.set(sessionId, state);
+        return state;
+    }
+    /** Fold the stream into the currently-projected entry ids (truncations rewind). */
+    async readProjectedEntryIds(path) {
+        const projected = [];
+        let offset;
+        for (;;) {
+            const result = await this.streams.read(path, { ...(offset !== undefined ? { offset } : {}), limit: 1000 });
+            for (const batch of result.batches) {
+                for (const record of batch.records) {
+                    if (record.kind === 'entry') {
+                        projected.push(record.entry.id);
+                    }
+                    else {
+                        const keep = record.rewoundTo ? projected.indexOf(record.rewoundTo) + 1 : 0;
+                        projected.length = keep;
+                    }
+                }
+            }
+            if (result.upToDate)
+                return projected;
+            offset = result.nextOffset;
+        }
+    }
+    /**
+     * Diff the projected tail against the current active path. A pure
+     * extension appends the missing suffix; a divergence appends a
+     * `truncated` record (with a fresh producer epoch) then the new suffix.
+     */
+    async reproject(sessionId, producer, data) {
+        const path = activePath(data);
+        const pathIds = path.map((entry) => entry.id);
+        const projected = producer.projectedEntryIds;
+        let common = 0;
+        while (common < projected.length && common < pathIds.length && projected[common] === pathIds[common]) {
+            common += 1;
+        }
+        const records = [];
+        if (common < projected.length) {
+            // The active path diverged from what we already emitted — branch switch.
+            const newLeaf = pathIds[pathIds.length - 1] ?? '';
+            const rewoundTo = common > 0 ? projected[common - 1] ?? '' : '';
+            records.push({ kind: 'truncated', rewoundTo, newLeafId: newLeaf, reason: 'active-path-rewound' });
+            const claim = await this.streams.acquireProducer(conversationStreamPath(sessionId), this.producerId);
+            producer.producerEpoch = claim.producerEpoch;
+            producer.nextProducerSequence = claim.nextProducerSequence;
+        }
+        for (const entry of path.slice(common)) {
+            records.push({ kind: 'entry', entry });
+        }
+        if (records.length === 0)
+            return;
+        await this.appendRecords(sessionId, producer, records, pathIds);
+    }
+    async appendRecords(sessionId, producer, records, projectedIds) {
+        try {
+            await this.streams.append({
+                path: conversationStreamPath(sessionId),
+                producerId: producer.producerId,
+                producerEpoch: producer.producerEpoch,
+                producerSequence: producer.nextProducerSequence,
+                records,
+            });
+            producer.nextProducerSequence += 1;
+            producer.projectedEntryIds =
+                records.length === 1 && records[0]?.kind === 'entry'
+                    ? [...producer.projectedEntryIds, ...projectedIds.slice(-1)]
+                    : projectedIds;
+        }
+        catch (error) {
+            if (error instanceof ConversationStreamStoreError && error.code === 'PRODUCER_FENCED') {
+                // Another projector took over (multi-writer window). Drop local
+                // state; the next append re-acquires and diff-repairs.
+                this.producers.delete(sessionId);
+                return;
+            }
+            throw error;
+        }
+    }
+}
+/** Compute the active (leaf-rooted) path of a SessionData snapshot. */
+function activePath(data) {
+    const entries = data.entries ?? [];
+    const byId = new Map(entries.map((entry) => [entry.id, entry]));
+    const path = [];
+    let current = data.leafId ? byId.get(data.leafId) : entries[entries.length - 1];
+    while (current) {
+        path.push(current);
+        current = current.parentId ? byId.get(current.parentId) : undefined;
+    }
+    return path.reverse();
+}
+//# sourceMappingURL=conversation-projection.js.map

package/dist/conversation-projection.js.map

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

package/dist/conversation-stream-contract.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared contract tests for {@link ConversationStreamStore} implementations.
+ *
+ * Store packages call {@link defineConversationStreamStoreContractTests} with
+ * a factory that creates their backend. The tests exercise every method on
+ * `ConversationStreamStore` with identical behavioral assertions regardless of
+ * the underlying storage engine — batch atomicity, producer fencing via
+ * epochs, idempotent redelivery, and offset catch-up reads.
+ *
+ * `subscribe` is a process-local notification seam: the suite only asserts
+ * that appends made through the same store instance notify local listeners
+ * and that unsubscribing stops further notifications. Cross-process fan-out
+ * is deliberately out of contract — backends may no-op it.
+ *
+ * @example
+ * ```ts
+ * import { defineConversationStreamStoreContractTests } from '@fabric-harness/sdk/testing/contracts';
+ *
+ * defineConversationStreamStoreContractTests('My backend', async () => ({
+ *   store: await createMyStreamStore(),
+ *   close: async () => myBackend.close(),
+ * }));
+ * ```
+ */
+import type { ConversationStreamStore } from './conversation-stream.js';
+export interface ConversationStreamStoreContractHandle {
+    /** The fresh store under test. */
+    store: ConversationStreamStore;
+    /** Optional cleanup after the test (close connections, delete temp files). */
+    close?: () => Promise<void>;
+}
+/**
+ * Register the standard {@link ConversationStreamStore} contract tests under
+ * the given describe label. Each test gets a fresh store from `factory()`.
+ */
+export declare function defineConversationStreamStoreContractTests(name: string, factory: () => Promise<ConversationStreamStoreContractHandle>): void;
+//# sourceMappingURL=conversation-stream-contract.d.ts.map

package/dist/conversation-stream-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-stream-contract.d.ts","sourceRoot":"","sources":["../src/conversation-stream-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAEV,uBAAuB,EAExB,MAAM,0BAA0B,CAAC;AAoClC,MAAM,WAAW,qCAAqC;IACpD,kCAAkC;IAClC,KAAK,EAAE,uBAAuB,CAAC;IAC/B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,0CAA0C,CACxD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,OAAO,CAAC,qCAAqC,CAAC,GAC5D,IAAI,CAmdN"}