@amalgm/live 0.1.0

package/dist/machines/bootstrap.js

@@ -0,0 +1,105 @@
+/**
+ * The bootstrap machine — how a client reaches `live` truthfully.
+ *
+ * Ordered-bootstrap mode (local-live-protocol.md §3): the snapshot is the
+ * first data frame and everything after it is ordered on the same channel,
+ * so the machine simply installs and follows. Legacy mode: the snapshot
+ * travels out-of-band, so the machine holds events while the snapshot body
+ * is in flight and replays only those past its seq — the full-snapshot
+ * barrier (§6).
+ *
+ * Feature detection (§3): a bootstrap request against a legacy engine
+ * yields no `snapshot` frame. The client falls back to the legacy path
+ * when the first data frame is a `state` event, a `ping` arrives, or the
+ * timeout passes — whichever comes first.
+ */
+import { BOOTSTRAP_SNAPSHOT_TIMEOUT_MS } from '../contracts/frames/stream.js';
+/** One instance per bootstrap-mode connection attempt; discard after it resolves. */
+export class BootstrapMachine {
+    #held = [];
+    #resolved = false;
+    timeoutMs = BOOTSTRAP_SNAPSHOT_TIMEOUT_MS;
+    /** Feed each stream frame until a command other than `none` resolves the machine. */
+    accept(frame) {
+        if (this.#resolved)
+            return { command: 'none' };
+        switch (frame.type) {
+            case 'snapshot': {
+                this.#resolved = true;
+                const snapshot = { seq: frame.seq, stable: frame.stable !== false, resources: frame.resources };
+                const replay = this.#held.filter((event) => event.seq > frame.seq);
+                this.#held = [];
+                return { command: 'install', snapshot, replay };
+            }
+            case 'state': {
+                if (this.#held.length === 0) {
+                    // First data frame is an event, not a snapshot: legacy peer.
+                    this.#resolved = true;
+                    return { command: 'fallback-legacy', held: [frame.event], reason: 'state-before-snapshot' };
+                }
+                this.#held.push(frame.event);
+                return { command: 'none' };
+            }
+            case 'ping': {
+                this.#resolved = true;
+                const held = this.#held;
+                this.#held = [];
+                return { command: 'fallback-legacy', held, reason: 'ping-before-snapshot' };
+            }
+            case 'error': {
+                this.#resolved = true;
+                this.#held = [];
+                return frame.status === undefined ? { command: 'fallback-error' } : { command: 'fallback-error', status: frame.status };
+            }
+            case 'reset':
+            case 'presence':
+                return { command: 'none' };
+        }
+    }
+    /** The host's timer fired without a snapshot frame. */
+    expire() {
+        if (this.#resolved)
+            return { command: 'none' };
+        this.#resolved = true;
+        const held = this.#held;
+        this.#held = [];
+        return { command: 'fallback-legacy', held, reason: 'timeout' };
+    }
+}
+/**
+ * The legacy full-snapshot barrier (§6): hold events while a full snapshot
+ * body is in flight; on arrival, replay only those past its seq. Partial
+ * snapshots (resources added on a live connection) never pass through
+ * here — they hold per-resource and never bump the connection seq.
+ */
+export class SnapshotBarrier {
+    #held = [];
+    #inFlight = false;
+    get inFlight() {
+        return this.#inFlight;
+    }
+    begin() {
+        this.#inFlight = true;
+        this.#held = [];
+    }
+    /** Returns true when the event was held (a snapshot body is in flight). */
+    hold(event) {
+        if (!this.#inFlight)
+            return false;
+        this.#held.push(event);
+        return true;
+    }
+    /** The snapshot body landed: install it, then apply the returned events in order. */
+    complete(snapshot) {
+        this.#inFlight = false;
+        const replay = this.#held.filter((event) => event.seq > snapshot.seq).sort((a, b) => a.seq - b.seq);
+        this.#held = [];
+        return replay;
+    }
+    /** The snapshot fetch failed: release nothing; the caller re-syncs. */
+    abandon() {
+        this.#inFlight = false;
+        this.#held = [];
+    }
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/machines/bootstrap.js.map

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

package/dist/machines/chunks.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Chunked response reassembly — the receiving half of §5's
+ * res_start / res_chunk / res_end train.
+ *
+ * Chunks reassemble by concatenating in index order; `res_end.chunks` must
+ * match the count received, else the whole response is treated as a 502
+ * for that request. Control frames interleaving between chunks is the
+ * feature, so the assembler tolerates any arrival interleaving across
+ * requests — but never within one (indexes must arrive 0,1,2,…).
+ */
+import type { ChunkedResponseFrame } from '../contracts/frames/tunnel.js';
+export interface AssembledResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Base64 chunks in index order; the host decodes with its own codec. */
+    readonly bodyChunksB64: readonly string[];
+}
+export type AssemblyResult = {
+    readonly done: false;
+} | {
+    readonly done: true;
+    readonly response: AssembledResponse;
+}
+/** Protocol violation for this req_id — treat as a 502 and drop the accumulator. */
+ | {
+    readonly done: true;
+    readonly error: string;
+};
+/**
+ * One assembler per tunnel connection. The host must call `abandon` when a
+ * request times out — the accumulator is memory, and §5 requires cleanup
+ * on the request timeout (AMALGM_TUNNEL_REQUEST_TIMEOUT_MS).
+ */
+export declare class ChunkAssembler {
+    #private;
+    /** In-flight accumulator count, exposed for diagnostics (§5 getTunnelDebugStats). */
+    get pending(): number;
+    accept(frame: ChunkedResponseFrame): AssemblyResult;
+    /** Drop a timed-out request's accumulator. Returns whether one existed. */
+    abandon(reqId: string): boolean;
+}
+/**
+ * Sender-side chunk plan for a raw body size: how many chunks a v2 peer
+ * will receive. The budget check happens BEFORE materializing any frame
+ * (§5): an over-budget response is dropped as a 503 without ever building
+ * its chunks — hence the plan is sizes only, never buffers.
+ */
+export declare function planChunks(bodyBytes: number, chunkMaxBytes: number): {
+    chunks: number;
+};
+//# sourceMappingURL=chunks.d.ts.map

package/dist/machines/chunks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/machines/chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAE1E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE;AAC/D,oFAAoF;GAClF;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAQpD;;;;GAIG;AACH,qBAAa,cAAc;;IAGzB,qFAAqF;IACrF,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,cAAc;IA4BnD,2EAA2E;IAC3E,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAGhC;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAGvF"}

package/dist/machines/chunks.js

@@ -0,0 +1,67 @@
+/**
+ * Chunked response reassembly — the receiving half of §5's
+ * res_start / res_chunk / res_end train.
+ *
+ * Chunks reassemble by concatenating in index order; `res_end.chunks` must
+ * match the count received, else the whole response is treated as a 502
+ * for that request. Control frames interleaving between chunks is the
+ * feature, so the assembler tolerates any arrival interleaving across
+ * requests — but never within one (indexes must arrive 0,1,2,…).
+ */
+/**
+ * One assembler per tunnel connection. The host must call `abandon` when a
+ * request times out — the accumulator is memory, and §5 requires cleanup
+ * on the request timeout (AMALGM_TUNNEL_REQUEST_TIMEOUT_MS).
+ */
+export class ChunkAssembler {
+    #pending = new Map();
+    /** In-flight accumulator count, exposed for diagnostics (§5 getTunnelDebugStats). */
+    get pending() {
+        return this.#pending.size;
+    }
+    accept(frame) {
+        switch (frame.type) {
+            case 'res_start': {
+                this.#pending.set(frame.req_id, { status: frame.status, headers: frame.headers, chunks: [] });
+                return { done: false };
+            }
+            case 'res_chunk': {
+                const acc = this.#pending.get(frame.req_id);
+                if (!acc)
+                    return { done: true, error: `res_chunk for unknown req_id ${frame.req_id}` };
+                if (frame.index !== acc.chunks.length) {
+                    this.#pending.delete(frame.req_id);
+                    return { done: true, error: `res_chunk index ${frame.index} arrived out of order (expected ${acc.chunks.length})` };
+                }
+                acc.chunks.push(frame.body_b64);
+                return { done: false };
+            }
+            case 'res_end': {
+                const acc = this.#pending.get(frame.req_id);
+                this.#pending.delete(frame.req_id);
+                if (!acc)
+                    return { done: true, error: `res_end for unknown req_id ${frame.req_id}` };
+                if (frame.chunks !== acc.chunks.length) {
+                    return { done: true, error: `res_end declared ${frame.chunks} chunks but ${acc.chunks.length} arrived` };
+                }
+                return { done: true, response: { status: acc.status, headers: acc.headers, bodyChunksB64: acc.chunks } };
+            }
+        }
+    }
+    /** Drop a timed-out request's accumulator. Returns whether one existed. */
+    abandon(reqId) {
+        return this.#pending.delete(reqId);
+    }
+}
+/**
+ * Sender-side chunk plan for a raw body size: how many chunks a v2 peer
+ * will receive. The budget check happens BEFORE materializing any frame
+ * (§5): an over-budget response is dropped as a 503 without ever building
+ * its chunks — hence the plan is sizes only, never buffers.
+ */
+export function planChunks(bodyBytes, chunkMaxBytes) {
+    if (bodyBytes < 0 || !Number.isSafeInteger(bodyBytes))
+        return { chunks: 0 };
+    return { chunks: bodyBytes === 0 ? 1 : Math.ceil(bodyBytes / chunkMaxBytes) };
+}
+//# sourceMappingURL=chunks.js.map

package/dist/machines/chunks.js.map

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

package/dist/machines/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The machines layer: the protocol's behavior as pure, deterministic state
+ * machines. Every machine takes wire shapes in and returns decisions as
+ * data — the host performs the fetches, timers, and writes. Nothing in
+ * here opens a socket, reads a clock, or touches a disk.
+ */
+export * from './ordering.js';
+export * from './bootstrap.js';
+export * from './journal.js';
+export * from './presence.js';
+export * from './arbitration.js';
+export * from './chunks.js';
+export * from './backoff.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/machines/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/machines/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/machines/index.js

@@ -0,0 +1,14 @@
+/**
+ * The machines layer: the protocol's behavior as pure, deterministic state
+ * machines. Every machine takes wire shapes in and returns decisions as
+ * data — the host performs the fetches, timers, and writes. Nothing in
+ * here opens a socket, reads a clock, or touches a disk.
+ */
+export * from './ordering.js';
+export * from './bootstrap.js';
+export * from './journal.js';
+export * from './presence.js';
+export * from './arbitration.js';
+export * from './chunks.js';
+export * from './backoff.js';
+//# sourceMappingURL=index.js.map

package/dist/machines/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/machines/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}

package/dist/machines/journal.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The mutation journal machine — journal first, materialize second.
+ *
+ * The hard rule (cloud-mutation-discipline.md): one SDK commit creates one
+ * durable mutation identity; the journal row is written BEFORE the local
+ * materialization, and that same row is the cloud outbox record. There is
+ * no second outgoing table and no contract-specific retry loop.
+ *
+ * This machine owns the state transitions and their legality. The host
+ * supplies the durable store through the `MutationJournalStore` port and
+ * performs the actual materialization and network submission; the cloud
+ * pump drives `claim → synced/rejected/conflicted`.
+ */
+import { type LiveMutation, type MutationState } from '../contracts/mutation.js';
+export interface JournalRow<Operation = unknown> {
+    readonly mutation: LiveMutation<Operation>;
+    readonly state: MutationState;
+    /** Set once the cloud assigns the official per-resource version. */
+    readonly officialVersion?: number;
+    /** Present on `rejected`/`conflicted`; local work is preserved either way. */
+    readonly reason?: string;
+}
+/** The durable store port. Every method is synchronous from the machine's view; a host may back it with SQLite, IndexedDB, or memory. */
+export interface MutationJournalStore<Operation = unknown> {
+    read(key: string): JournalRow<Operation> | null;
+    write(key: string, row: JournalRow<Operation>): void;
+    /** The outbox is a filtered view of this journal — never a second table. */
+    pendingShared(): readonly JournalRow<Operation>[];
+}
+export type JournalDecision<Operation = unknown> = 
+/** New identity: the row is journaled; the host must now materialize, then call `advance(key, 'saved-local')`. */
+{
+    readonly outcome: 'journaled';
+    readonly row: JournalRow<Operation>;
+}
+/** Same `(resourceId, mutationId)` seen before: return the existing row — a retry never creates a second edit. */
+ | {
+    readonly outcome: 'duplicate';
+    readonly row: JournalRow<Operation>;
+};
+export declare class MutationJournal<Operation = unknown> {
+    private readonly store;
+    constructor(store: MutationJournalStore<Operation>);
+    /** SDK commit: journal the mutation before anything else happens. Idempotent by mutation identity. */
+    commit(mutation: LiveMutation<Operation>): JournalDecision<Operation>;
+    /**
+     * Advance a mutation's state along the discipline's order. An illegal
+     * transition throws — it is a programming error in the host, not a wire
+     * condition, and hiding it would corrupt the journal's meaning.
+     */
+    advance(key: string, to: MutationState, detail?: {
+        officialVersion?: number;
+        reason?: string;
+    }): JournalRow<Operation>;
+    /**
+     * Crash recovery: an unfinished materialization is resumed from the
+     * journal already on disk — rows still `saving-local` need their
+     * materialization re-applied (idempotently), rows `saved-local` and
+     * later resume from the pump.
+     */
+    unfinishedMaterializations(): readonly JournalRow<Operation>[];
+}
+//# sourceMappingURL=journal.d.ts.map

package/dist/machines/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../src/machines/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAe,MAAM,0BAA0B,CAAC;AAE9F,MAAM,WAAW,UAAU,CAAC,SAAS,GAAG,OAAO;IAC7C,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,yIAAyI;AACzI,MAAM,WAAW,oBAAoB,CAAC,SAAS,GAAG,OAAO;IACvD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IACrD,4EAA4E;IAC5E,aAAa,IAAI,SAAS,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;CACnD;AAWD,MAAM,MAAM,eAAe,CAAC,SAAS,GAAG,OAAO;AAC7C,kHAAkH;AAChH;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,SAAS,CAAC,CAAA;CAAE;AACxE,kHAAkH;GAChH;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,SAAS,CAAC,CAAA;CAAE,CAAC;AAE3E,qBAAa,eAAe,CAAC,SAAS,GAAG,OAAO;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,oBAAoB,CAAC,SAAS,CAAC;IAEnE,sGAAsG;IACtG,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,SAAS,CAAC,GAAG,eAAe,CAAC,SAAS,CAAC;IASrE;;;;OAIG;IACH,OAAO,CACL,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,aAAa,EACjB,MAAM,GAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GACzD,UAAU,CAAC,SAAS,CAAC;IAqBxB;;;;;OAKG;IACH,0BAA0B,IAAI,SAAS,UAAU,CAAC,SAAS,CAAC,EAAE;CAG/D"}

package/dist/machines/journal.js

@@ -0,0 +1,71 @@
+/**
+ * The mutation journal machine — journal first, materialize second.
+ *
+ * The hard rule (cloud-mutation-discipline.md): one SDK commit creates one
+ * durable mutation identity; the journal row is written BEFORE the local
+ * materialization, and that same row is the cloud outbox record. There is
+ * no second outgoing table and no contract-specific retry loop.
+ *
+ * This machine owns the state transitions and their legality. The host
+ * supplies the durable store through the `MutationJournalStore` port and
+ * performs the actual materialization and network submission; the cloud
+ * pump drives `claim → synced/rejected/conflicted`.
+ */
+import { mutationKey } from '../contracts/mutation.js';
+const LEGAL = {
+    'saving-local': ['saved-local'],
+    'saved-local': ['syncing'],
+    syncing: ['synced', 'rejected', 'conflicted', 'saved-local'], // saved-local: a lease expired; the pump re-claims
+    synced: [],
+    rejected: [],
+    conflicted: [],
+};
+export class MutationJournal {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /** SDK commit: journal the mutation before anything else happens. Idempotent by mutation identity. */
+    commit(mutation) {
+        const key = mutationKey(mutation);
+        const existing = this.store.read(key);
+        if (existing)
+            return { outcome: 'duplicate', row: existing };
+        const row = { mutation, state: 'saving-local' };
+        this.store.write(key, row);
+        return { outcome: 'journaled', row };
+    }
+    /**
+     * Advance a mutation's state along the discipline's order. An illegal
+     * transition throws — it is a programming error in the host, not a wire
+     * condition, and hiding it would corrupt the journal's meaning.
+     */
+    advance(key, to, detail = {}) {
+        const row = this.store.read(key);
+        if (!row) {
+            throw new Error(`no journal row for "${key}" — commit() the mutation before advancing it`);
+        }
+        if (!LEGAL[row.state].includes(to)) {
+            throw new Error(`illegal journal transition "${row.state}" → "${to}" for "${key}" — ` +
+                `the order is saving-local → saved-local → syncing → synced|rejected|conflicted`);
+        }
+        const next = {
+            mutation: row.mutation,
+            state: to,
+            ...(detail.officialVersion !== undefined ? { officialVersion: detail.officialVersion } : {}),
+            ...(detail.reason !== undefined ? { reason: detail.reason } : {}),
+        };
+        this.store.write(key, next);
+        return next;
+    }
+    /**
+     * Crash recovery: an unfinished materialization is resumed from the
+     * journal already on disk — rows still `saving-local` need their
+     * materialization re-applied (idempotently), rows `saved-local` and
+     * later resume from the pump.
+     */
+    unfinishedMaterializations() {
+        return this.store.pendingShared().filter((row) => row.state === 'saving-local');
+    }
+}
+//# sourceMappingURL=journal.js.map

package/dist/machines/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../src/machines/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAyC,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAmB9F,MAAM,KAAK,GAA8D;IACvE,cAAc,EAAE,CAAC,aAAa,CAAC;IAC/B,aAAa,EAAE,CAAC,SAAS,CAAC;IAC1B,OAAO,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,CAAC,EAAE,mDAAmD;IACjH,MAAM,EAAE,EAAE;IACV,QAAQ,EAAE,EAAE;IACZ,UAAU,EAAE,EAAE;CACf,CAAC;AAQF,MAAM,OAAO,eAAe;IACG;IAA7B,YAA6B,KAAsC;QAAtC,UAAK,GAAL,KAAK,CAAiC;IAAG,CAAC;IAEvE,sGAAsG;IACtG,MAAM,CAAC,QAAiC;QACtC,MAAM,GAAG,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,QAAQ;YAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;QAC7D,MAAM,GAAG,GAA0B,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC;QACvE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC3B,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,OAAO,CACL,GAAW,EACX,EAAiB,EACjB,SAAwD,EAAE;QAE1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,uBAAuB,GAAG,+CAA+C,CAAC,CAAC;QAC7F,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,+BAA+B,GAAG,CAAC,KAAK,QAAQ,EAAE,UAAU,GAAG,MAAM;gBACnE,gFAAgF,CACnF,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAA0B;YAClC,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,KAAK,EAAE,EAAE;YACT,GAAG,CAAC,MAAM,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5F,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClE,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,0BAA0B;QACxB,OAAO,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,cAAc,CAAC,CAAC;IAClF,CAAC;CACF"}

package/dist/machines/ordering.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The sequence ledger — ordered, gap-free application of state events.
+ *
+ * Client obligations (local-live-protocol.md §6): never re-apply an event
+ * at or below the applied seq; on a gap, run exactly one backfill at a
+ * time (`GET /state/events?after=`); on backfill failure or a `reset`
+ * frame, converge on a full re-sync. Every decision is returned as data —
+ * the host performs the fetches.
+ */
+import type { StateEvent } from '../contracts/events.js';
+export type LedgerDecision = 
+/** In order: apply to local state, advance the ledger. */
+{
+    readonly action: 'apply';
+    readonly event: StateEvent;
+}
+/** At or below the applied seq: drop silently (duplicate delivery is normal). */
+ | {
+    readonly action: 'skip-duplicate';
+    readonly event: StateEvent;
+}
+/** A gap opened. Run one backfill after `after`; the event is buffered and will replay once the gap closes. */
+ | {
+    readonly action: 'backfill';
+    readonly after: number;
+    readonly buffered: StateEvent;
+}
+/** A backfill is already in flight: buffer only (single-flight obligation). */
+ | {
+    readonly action: 'buffer';
+    readonly buffered: StateEvent;
+};
+export declare class SequenceLedger {
+    #private;
+    constructor(appliedSeq: number);
+    get appliedSeq(): number;
+    get backfilling(): boolean;
+    /** Feed one live event; act on the returned decision. */
+    accept(event: StateEvent): LedgerDecision;
+    /**
+     * Deliver the backfill body. Returns the events to apply, in order,
+     * merged with everything buffered while the backfill was in flight.
+     * Backfilled and buffered ranges may overlap; the ledger dedupes by seq.
+     */
+    completeBackfill(events: readonly StateEvent[]): StateEvent[];
+    /** Whether `completeBackfill` left the ledger still gapped — the caller must re-sync. */
+    needsResync(nextBufferedSeq?: number): boolean;
+    /** Backfill failed, or a `reset` frame arrived: drop everything and let the caller re-snapshot. */
+    abandonToResync(): void;
+    /** A full snapshot installed at `seq` supersedes anything older. */
+    resumeFrom(seq: number): void;
+}
+//# sourceMappingURL=ordering.d.ts.map

package/dist/machines/ordering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ordering.d.ts","sourceRoot":"","sources":["../../src/machines/ordering.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,MAAM,cAAc;AACxB,0DAA0D;AACxD;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE;AAC1D,iFAAiF;GAC/E;IAAE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE;AACnE,+GAA+G;GAC7G;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAA;CAAE;AACxF,+EAA+E;GAC7E;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAA;CAAE,CAAC;AAEjE,qBAAa,cAAc;;gBAKb,UAAU,EAAE,MAAM;IAI9B,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,yDAAyD;IACzD,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc;IAezC;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,EAAE;IAmB7D,yFAAyF;IACzF,WAAW,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO;IAI9C,mGAAmG;IACnG,eAAe,IAAI,IAAI;IAKvB,oEAAoE;IACpE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAY9B"}

package/dist/machines/ordering.js

@@ -0,0 +1,87 @@
+/**
+ * The sequence ledger — ordered, gap-free application of state events.
+ *
+ * Client obligations (local-live-protocol.md §6): never re-apply an event
+ * at or below the applied seq; on a gap, run exactly one backfill at a
+ * time (`GET /state/events?after=`); on backfill failure or a `reset`
+ * frame, converge on a full re-sync. Every decision is returned as data —
+ * the host performs the fetches.
+ */
+export class SequenceLedger {
+    #appliedSeq;
+    #backfilling = false;
+    #buffer = [];
+    constructor(appliedSeq) {
+        this.#appliedSeq = appliedSeq;
+    }
+    get appliedSeq() {
+        return this.#appliedSeq;
+    }
+    get backfilling() {
+        return this.#backfilling;
+    }
+    /** Feed one live event; act on the returned decision. */
+    accept(event) {
+        if (event.seq <= this.#appliedSeq)
+            return { action: 'skip-duplicate', event };
+        if (this.#backfilling) {
+            this.#insertBuffered(event);
+            return { action: 'buffer', buffered: event };
+        }
+        if (event.seq === this.#appliedSeq + 1) {
+            this.#appliedSeq = event.seq;
+            return { action: 'apply', event };
+        }
+        this.#backfilling = true;
+        this.#insertBuffered(event);
+        return { action: 'backfill', after: this.#appliedSeq, buffered: event };
+    }
+    /**
+     * Deliver the backfill body. Returns the events to apply, in order,
+     * merged with everything buffered while the backfill was in flight.
+     * Backfilled and buffered ranges may overlap; the ledger dedupes by seq.
+     */
+    completeBackfill(events) {
+        this.#backfilling = false;
+        const merged = [...events, ...this.#buffer].sort((a, b) => a.seq - b.seq);
+        this.#buffer = [];
+        const toApply = [];
+        for (const event of merged) {
+            if (event.seq <= this.#appliedSeq)
+                continue;
+            if (event.seq !== this.#appliedSeq + 1) {
+                // The backfill itself was gappy — the buffer cannot repair it.
+                // Converge on the recovery rule: full re-sync.
+                this.#buffer = [];
+                return toApply;
+            }
+            this.#appliedSeq = event.seq;
+            toApply.push(event);
+        }
+        return toApply;
+    }
+    /** Whether `completeBackfill` left the ledger still gapped — the caller must re-sync. */
+    needsResync(nextBufferedSeq) {
+        return nextBufferedSeq !== undefined && nextBufferedSeq > this.#appliedSeq + 1;
+    }
+    /** Backfill failed, or a `reset` frame arrived: drop everything and let the caller re-snapshot. */
+    abandonToResync() {
+        this.#backfilling = false;
+        this.#buffer = [];
+    }
+    /** A full snapshot installed at `seq` supersedes anything older. */
+    resumeFrom(seq) {
+        this.#appliedSeq = seq;
+        this.#backfilling = false;
+        this.#buffer = this.#buffer.filter((event) => event.seq > seq);
+    }
+    #insertBuffered(event) {
+        // Keep the buffer sorted and deduped; delivery may repeat frames.
+        const at = this.#buffer.findIndex((held) => held.seq >= event.seq);
+        if (at === -1)
+            this.#buffer.push(event);
+        else if (this.#buffer[at].seq !== event.seq)
+            this.#buffer.splice(at, 0, event);
+    }
+}
+//# sourceMappingURL=ordering.js.map

package/dist/machines/ordering.js.map

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

package/dist/machines/presence.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Presence receiver — arrival-clock TTL over replace-not-merge frames.
+ *
+ * A presence frame carries the FULL peer list for one resource; receivers
+ * replace their view and treat absence as the default that publishing
+ * re-earns (local-live-protocol.md §2). The server already expires stale
+ * publishers, but receivers must apply their OWN arrival-clock TTL — a
+ * frozen stream must not preserve ghosts.
+ */
+import { type PresenceFrame, type PresencePeer } from '../contracts/presence.js';
+export interface SeenPeer extends PresencePeer {
+    /** Receiver's clock when the peer last arrived — TTL runs on this, never on sender timestamps. */
+    readonly arrivedAtMs: number;
+}
+export declare class PresenceView {
+    #private;
+    private readonly ttlMs;
+    constructor(ttlMs?: number);
+    /** Replace one resource's peer view. `nowMs` is the receiver's clock (host-supplied — the SDK holds no clock). */
+    accept(frame: PresenceFrame, nowMs: number): void;
+    /** Live peers for a resource, with expired entries dropped as of `nowMs`. */
+    peers(resource: string, nowMs: number): readonly SeenPeer[];
+    /** Delivery was lost: presence is not replayed after a gap, so the view must not outlive its stream. */
+    clear(): void;
+}
+//# sourceMappingURL=presence.d.ts.map

package/dist/machines/presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../src/machines/presence.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAiB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAEhG,MAAM,WAAW,QAAS,SAAQ,YAAY;IAC5C,kGAAkG;IAClG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,qBAAa,YAAY;;IAGX,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,GAAE,MAAsB;IAE1D,kHAAkH;IAClH,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IASjD,6EAA6E;IAC7E,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,QAAQ,EAAE;IAY3D,wGAAwG;IACxG,KAAK,IAAI,IAAI;CAGd"}