@amalgm/live 0.1.0

package/dist/entities/rules.js

@@ -0,0 +1,200 @@
+/**
+ * The registry's pure rule surface — the laws of the entity model (engine
+ * docs/entity-model.md) with every store lookup behind the injected
+ * {@link EntityReadPort} and every hash behind {@link Sha256Hex}:
+ *
+ * - the ratified version formula: version = hash(type, parentUUID, name,
+ *   status, adapterPayloadVersion) — DERIVED, never stored;
+ * - container payloads as sorted active direct membership;
+ * - lifecycle inheritance DOWN the ancestor chain as derived effective
+ *   status (deleted > trashed > own stored status);
+ * - one active owner per (parentUUID, name) slot; only containers hold
+ *   active children; the parent graph is acyclic;
+ * - what an attestation may say (leaf ground attests bytes; membership and
+ *   reference identity are never observed);
+ * - the record / syncRecord shapes and the cloud-record normalizer.
+ *
+ * Refusal messages are ported verbatim from the engine registry — they are
+ * the ratified refusal text its exams pin.
+ */
+import { CONTAINERS, DERIVED_PAYLOAD, ROOT_TYPES, TYPES, UUID_PATTERN, } from './types.js';
+/** The row a UUID must name; absence is the caller's bug, said plainly. */
+export function mustGet(uuid, byUuid) {
+    const row = byUuid(uuid);
+    if (!row)
+        throw new Error(`no entity ${uuid}`);
+    return row;
+}
+/**
+ * What an attestation may say — asked of both the type a record wears now
+ * and the type its new bytes claim, because an attestation may carry a
+ * record across leaf kinds (a pointer replaced by bytes) and both ends
+ * must be ground an observation can speak for.
+ */
+export function attestable(type) {
+    if (DERIVED_PAYLOAD.has(type)) {
+        throw new Error(`${type} payload is derived membership, never attested`);
+    }
+    if (type === 'reference') {
+        throw new Error('a reference\'s payload is the target\'s identity, set by the deliberate act that created it — never an attestation; the rendered symlink is derived state, not evidence');
+    }
+    if (!TYPES.has(type))
+        throw new Error(`unknown entity type ${JSON.stringify(type)}`);
+}
+/** The ratified formula: version = hash(type, parentUUID, name, status, payloadVersion). */
+export function canonicalVersion({ type, parentUUID = null, name, status, payloadVersion = null }, sha256Hex) {
+    return sha256Hex(JSON.stringify([type, parentUUID, name, status, payloadVersion]));
+}
+/** A name is one non-empty path segment: never '', '.', '..', a '/' or NUL. */
+export function validName(name) {
+    if (typeof name !== 'string' || name === '' || name === '.' || name === '..'
+        || name.includes('/') || name.includes('\0')) {
+        throw new Error(`invalid entity name ${JSON.stringify(name)}: a name is one non-empty path segment`);
+    }
+}
+/** A UUID may arrive only through a trusted identity binding (for example
+ * a cloud user-home bootstrap). The registry still owns the actual insert:
+ * accepting a caller-supplied UUID is not accepting a caller-supplied
+ * record, parent, status, or version. */
+export function mintOrValidateUuid(uuid, ports) {
+    if (uuid === undefined || uuid === null)
+        return ports.mintUuid();
+    if (typeof uuid !== 'string' || !UUID_PATTERN.test(uuid)) {
+        throw new Error(`entity identity must be a UUID, got ${JSON.stringify(uuid)}`);
+    }
+    if (ports.byUuid(uuid))
+        throw new Error(`entity identity ${uuid} is already registered`);
+    return uuid.toLowerCase();
+}
+/** Ancestor uuids from the given parent up to the root. */
+export function ancestorsOf(parentUuid, byUuid) {
+    const chain = [];
+    const seen = new Set();
+    let cursor = parentUuid;
+    while (cursor !== null) {
+        if (seen.has(cursor))
+            throw new Error(`registry corrupt: parent cycle at ${cursor}`);
+        seen.add(cursor);
+        chain.push(cursor);
+        cursor = mustGet(cursor, byUuid).parentUuid;
+    }
+    return chain;
+}
+/** Lifecycle inherits down: deleted if any ancestor is deleted, trashed if
+ * any is trashed, otherwise the entity's own stored status — one flip on a
+ * folder, no descendant record rewritten. */
+export function effectiveStatusOf(row, byUuid) {
+    const statuses = [row.status, ...ancestorsOf(row.parentUuid, byUuid)
+            .map((uuid) => mustGet(uuid, byUuid).status)];
+    if (statuses.includes('deleted'))
+        return 'deleted';
+    if (statuses.includes('trashed'))
+        return 'trashed';
+    return row.status;
+}
+const byUuidOrder = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+/**
+ * Container payload: the sorted active direct membership (childUUID, name).
+ * Children are sorted here by uuid, codepoint order — the same order the
+ * engine's `ORDER BY uuid` (BINARY collation over lowercase-hex uuids)
+ * produces — so the hash input is byte-identical however the port returns
+ * them. Membership counts direct children by their STORED status, never
+ * effective status: effective-status membership would ripple a version
+ * change through the entire subtree and defeat the one-flip lifecycle.
+ */
+export function membershipHash(activeChildren, sha256Hex) {
+    const pairs = [...activeChildren]
+        .sort((left, right) => byUuidOrder(left.uuid, right.uuid))
+        .map((child) => [child.uuid, child.name]);
+    return sha256Hex(JSON.stringify(pairs));
+}
+const payloadFor = (row, ports) => (DERIVED_PAYLOAD.has(row.type) ? ports.membershipHashOf(row.uuid) : row.payloadVersion);
+/** The public record: exactly the six ratified fields, version derived. */
+export function entityRecordOf(row, ports) {
+    return {
+        uuid: row.uuid,
+        type: row.type,
+        parentUUID: row.parentUuid,
+        name: row.name,
+        version: canonicalVersion({
+            type: row.type, parentUUID: row.parentUuid, name: row.name,
+            status: row.status, payloadVersion: payloadFor(row, ports),
+        }, ports.sha256Hex),
+        status: row.status,
+    };
+}
+/** The cloud form contains identity and the content/head token, never an
+ * address, watcher, inode, or SQLite bytes. `payloadVersion` is the
+ * unambiguous current head for leaf types; containers derive theirs from
+ * membership and retain null here; a repo.git retains its immutable
+ * Card/Checkpoint head. */
+export function syncRecordOf(row, ports) {
+    return {
+        ...entityRecordOf(row, ports),
+        payloadVersion: row.payloadVersion,
+    };
+}
+/** Validate and normalize a record arriving from the cloud: six fields plus
+ * payloadVersion, UUIDs lowercased, root laws enforced. */
+export function normalizeCloudRecord(value) {
+    const record = value;
+    if (!record || typeof record !== 'object'
+        || typeof record.uuid !== 'string' || !UUID_PATTERN.test(record.uuid)
+        || typeof record.type !== 'string' || !TYPES.has(record.type)
+        || (record.parentUUID !== null && (typeof record.parentUUID !== 'string' || !UUID_PATTERN.test(record.parentUUID)))
+        || typeof record.name !== 'string'
+        || !['active', 'trashed', 'deleted'].includes(record.status)
+        || (record.payloadVersion !== null && typeof record.payloadVersion !== 'string')
+        || typeof record.version !== 'string' || !/^[0-9a-f]{64}$/i.test(record.version)) {
+        throw new Error('cloud entity operation has an invalid record');
+    }
+    validName(record.name);
+    if (record.parentUUID === null && !ROOT_TYPES.has(record.type)) {
+        throw new Error(`cloud entity ${record.uuid} is not a valid tree root`);
+    }
+    if (record.parentUUID !== null && record.type === 'workspace') {
+        throw new Error('cloud entity workspace is the root type only');
+    }
+    return {
+        uuid: record.uuid.toLowerCase(),
+        type: record.type,
+        parentUuid: record.parentUUID === null ? null : record.parentUUID.toLowerCase(),
+        name: record.name,
+        status: record.status,
+        payloadVersion: record.payloadVersion,
+        expectedVersion: record.version.toLowerCase(),
+    };
+}
+/** Equality over the five stored facts plus payload — everything the
+ * version fingerprints except the fingerprint itself. */
+export function sameLogicalRecord(left, right) {
+    return left.uuid === right.uuid
+        && left.type === right.type
+        && left.parentUuid === right.parentUuid
+        && left.name === right.name
+        && left.status === right.status
+        && left.payloadVersion === right.payloadVersion;
+}
+/** Only containers — workspace, folder, repo.git — hold active children,
+ * and only while effectively active themselves. */
+export function requireActiveContainerParent(parentUuid, port) {
+    const parent = mustGet(parentUuid, port.byUuid.bind(port));
+    if (!CONTAINERS.has(parent.type)) {
+        throw new Error(`only containers hold active children: ${parentUuid} is ${parent.type}, not workspace/folder/repo.git`);
+    }
+    if (effectiveStatusOf(parent, port.byUuid.bind(port)) !== 'active') {
+        throw new Error(`parent ${parentUuid} is not effectively active — restore it before putting entities under it`);
+    }
+    return parent;
+}
+/** One active owner per (parentUUID, name) slot. Parentless records are
+ * exempt: a top-level tree is placed by its machine binding, never by name. */
+export function requireFreeSlot(parentUuid, name, port, forUuid = null) {
+    if (parentUuid === null)
+        return; // top level: address places a tree, never its name
+    const occupant = port.activeChildByName(parentUuid, name);
+    if (occupant && occupant.uuid !== forUuid) {
+        throw new Error(`slot taken: active entity ${occupant.uuid} already owns (${parentUuid}, ${name}) — move or trash it first`);
+    }
+}
+//# sourceMappingURL=rules.js.map

package/dist/entities/rules.js.map

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

package/dist/entities/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The entity alphabet and the six-field universal record — the value
+ * vocabulary of the entity model (engine docs/entity-model.md, "The entity
+ * record"). Every enrolled entity, of every type, is exactly six fields:
+ * UUID, type, parentUUID, name, version, status. Paths are derived from the
+ * parentUUID + name chain and are never identity; version is derived on
+ * read, never stored.
+ *
+ * The alphabet is PHYSICAL kinds only. Constructs — agents, apps,
+ * automations, tools, skills — are folder-and-file ground with a known
+ * structure, their meaning layered ABOVE the physical type, never encoded
+ * as one.
+ *
+ * This module also names the two ports the pure rules receive instead of a
+ * database or node:crypto: a read port over the host's identity store, and
+ * a SHA-256 hex function.
+ */
+/** `link` is a filesystem symlink: payload = the literal target text.
+ * `reference` is the OTHER link kind, never conflated: Amalgm-created by a
+ * deliberate act, its payload the TARGET ENTITY'S UUID — identity, not an
+ * address. */
+export type EntityType = 'workspace' | 'folder' | 'repo.git' | 'file.text' | 'file.binary' | 'link' | 'reference';
+export type ContainerType = 'workspace' | 'folder' | 'repo.git';
+/** active — exists normally; trashed — recoverable, UUID survives;
+ * deleted — content permanently gone, the record IS the tombstone. */
+export type EntityStatus = 'active' | 'trashed' | 'deleted';
+export declare const TYPES: ReadonlySet<string>;
+/** Only containers hold active children. */
+export declare const CONTAINERS: ReadonlySet<string>;
+/** The types a parentless record (a tree root) may wear. `folder` is
+ * deliberately absent: a folder inside no workspace is not a thing amalgm
+ * registers. `reference` is absent too — a managed pointer is always
+ * created inside a tree. */
+export declare const ROOT_TYPES: ReadonlySet<string>;
+/** Types whose payload IS their membership: derived from the records
+ * beneath them, so no observation may attest one. */
+export declare const DERIVED_PAYLOAD: ReadonlySet<string>;
+/** The one entity alphabet, published sorted for the layers that map onto
+ * it — read from here, never restated, so it cannot drift. */
+export declare const ENTITY_TYPES: readonly EntityType[];
+export declare const isEntityType: (value: unknown) => value is EntityType;
+/** RFC-4122 UUID shape (versions 1–8), the permanent identity and realtime
+ * channel of every enrolled entity. */
+export declare const UUID_PATTERN: RegExp;
+/**
+ * A stored identity row as the host's store holds it — the six fields with
+ * the payload attestation beside them and no derived version. The rules in
+ * this layer read rows through {@link EntityReadPort} and never write one.
+ */
+export interface EntityRow {
+    readonly uuid: string;
+    readonly type: EntityType;
+    readonly parentUuid: string | null;
+    readonly name: string;
+    readonly status: EntityStatus;
+    readonly payloadVersion: string | null;
+}
+/** The public record: exactly the six ratified fields, version derived by
+ * the canonical formula. Payload attestations are evidence inputs, never a
+ * seventh public field. */
+export interface EntityRecord {
+    readonly uuid: string;
+    readonly type: EntityType;
+    readonly parentUUID: string | null;
+    readonly name: string;
+    readonly version: string;
+    readonly status: EntityStatus;
+}
+/** The cloud form: the record plus the unambiguous current head for leaf
+ * types. Containers derive their payload from membership and retain null
+ * here; a repo.git retains its immutable Card/Checkpoint stateId. */
+export interface EntitySyncRecord extends EntityRecord {
+    readonly payloadVersion: string | null;
+}
+/**
+ * SHA-256 as lowercase hex over the given bytes; string input is hashed as
+ * its UTF-8 encoding (exactly node:crypto's `createHash('sha256')
+ * .update(input).digest('hex')`). Injected by the host — src/ owns hash
+ * INPUTS byte for byte, never the hash implementation.
+ */
+export type Sha256Hex = (input: Uint8Array | string) => string;
+/**
+ * The minimal read surface the rules need over the host's identity store.
+ * Lookups are by permanent identity or by (parentUUID, name) slot; the
+ * rules never enumerate, never write, and never see a path.
+ */
+export interface EntityReadPort {
+    /** The row wearing this UUID, or null/undefined when none does. */
+    byUuid(uuid: string): EntityRow | null | undefined;
+    /** The ACTIVE row owning the (parentUuid, name) slot, or null/undefined
+     * when the slot is free. */
+    activeChildByName(parentUuid: string, name: string): EntityRow | null | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/entities/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/entities/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;cAGc;AACd,MAAM,MAAM,UAAU,GAClB,WAAW,GAAG,QAAQ,GAAG,UAAU,GACnC,WAAW,GAAG,aAAa,GAC3B,MAAM,GAAG,WAAW,CAAC;AAEzB,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhE;sEACsE;AACtE,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAO5D,eAAO,MAAM,KAAK,EAAE,WAAW,CAAC,MAAM,CAAqB,CAAC;AAE5D,4CAA4C;AAC5C,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CAE1C,CAAC;AAEF;;;4BAG4B;AAC5B,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CAE1C,CAAC;AAEF;qDACqD;AACrD,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAE/C,CAAC;AAEF;8DAC8D;AAC9D,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAAwC,CAAC;AAEvF,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,UACR,CAAC;AAEhD;uCACuC;AACvC,eAAO,MAAM,YAAY,QACqD,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED;;2BAE2B;AAC3B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED;;qEAEqE;AACrE,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,KAAK,MAAM,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,CAAC;IACnD;gCAC4B;IAC5B,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,CAAC;CACnF"}

package/dist/entities/types.js

@@ -0,0 +1,40 @@
+/**
+ * The entity alphabet and the six-field universal record — the value
+ * vocabulary of the entity model (engine docs/entity-model.md, "The entity
+ * record"). Every enrolled entity, of every type, is exactly six fields:
+ * UUID, type, parentUUID, name, version, status. Paths are derived from the
+ * parentUUID + name chain and are never identity; version is derived on
+ * read, never stored.
+ *
+ * The alphabet is PHYSICAL kinds only. Constructs — agents, apps,
+ * automations, tools, skills — are folder-and-file ground with a known
+ * structure, their meaning layered ABOVE the physical type, never encoded
+ * as one.
+ *
+ * This module also names the two ports the pure rules receive instead of a
+ * database or node:crypto: a read port over the host's identity store, and
+ * a SHA-256 hex function.
+ */
+const ALPHABET = [
+    'workspace', 'folder', 'repo.git', 'file.text', 'file.binary',
+    'link', 'reference',
+];
+export const TYPES = new Set(ALPHABET);
+/** Only containers hold active children. */
+export const CONTAINERS = new Set(['workspace', 'folder', 'repo.git']);
+/** The types a parentless record (a tree root) may wear. `folder` is
+ * deliberately absent: a folder inside no workspace is not a thing amalgm
+ * registers. `reference` is absent too — a managed pointer is always
+ * created inside a tree. */
+export const ROOT_TYPES = new Set(['workspace', 'repo.git', 'file.text', 'file.binary', 'link']);
+/** Types whose payload IS their membership: derived from the records
+ * beneath them, so no observation may attest one. */
+export const DERIVED_PAYLOAD = new Set(['workspace', 'folder']);
+/** The one entity alphabet, published sorted for the layers that map onto
+ * it — read from here, never restated, so it cannot drift. */
+export const ENTITY_TYPES = Object.freeze([...ALPHABET].sort());
+export const isEntityType = (value) => typeof value === 'string' && TYPES.has(value);
+/** RFC-4122 UUID shape (versions 1–8), the permanent identity and realtime
+ * channel of every enrolled entity. */
+export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+//# sourceMappingURL=types.js.map

package/dist/entities/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/entities/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAiBH,MAAM,QAAQ,GAA0B;IACtC,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa;IAC7D,MAAM,EAAE,WAAW;CACpB,CAAC;AAEF,MAAM,CAAC,MAAM,KAAK,GAAwB,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;AAE5D,4CAA4C;AAC5C,MAAM,CAAC,MAAM,UAAU,GAAwB,IAAI,GAAG,CACpD,CAAC,WAAW,EAAE,QAAQ,EAAE,UAAU,CAA2B,CAC9D,CAAC;AAEF;;;4BAG4B;AAC5B,MAAM,CAAC,MAAM,UAAU,GAAwB,IAAI,GAAG,CACpD,CAAC,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,CAAwB,CACrF,CAAC;AAEF;qDACqD;AACrD,MAAM,CAAC,MAAM,eAAe,GAAwB,IAAI,GAAG,CACzD,CAAC,WAAW,EAAE,QAAQ,CAAwB,CAC/C,CAAC;AAEF;8DAC8D;AAC9D,MAAM,CAAC,MAAM,YAAY,GAA0B,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAEvF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAc,EAAuB,EAAE,CAClE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAEhD;uCACuC;AACvC,MAAM,CAAC,MAAM,YAAY,GACvB,4EAA4E,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @amalgm/live — the portable realtime SDK for the Amalgm platform.
+ *
+ * Three layers, one rule each:
+ *
+ * - `contracts/`  every wire shape and identity rule, as types + validators
+ * - `machines/`   the protocol's behavior, as pure state machines
+ * - `adapters/`   the ports a host injects (transport, journal, clock, crypto)
+ *
+ * Start at PURPOSE.md for the axioms; docs/ holds the normative specs.
+ */
+export * from './contracts/index.js';
+export * from './machines/index.js';
+export * from './entities/index.js';
+export * from './detection/index.js';
+export * from './merge/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @amalgm/live — the portable realtime SDK for the Amalgm platform.
+ *
+ * Three layers, one rule each:
+ *
+ * - `contracts/`  every wire shape and identity rule, as types + validators
+ * - `machines/`   the protocol's behavior, as pure state machines
+ * - `adapters/`   the ports a host injects (transport, journal, clock, crypto)
+ *
+ * Start at PURPOSE.md for the axioms; docs/ holds the normative specs.
+ */
+export * from './contracts/index.js';
+export * from './machines/index.js';
+export * from './entities/index.js';
+export * from './detection/index.js';
+export * from './merge/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC"}

package/dist/machines/arbitration.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tunnel slot arbitration — who owns `(computer_id, runtime_label)`.
+ *
+ * The gateway holds one slot per runtime identity; a newcomer's first
+ * identity-bearing hello decides the winner (local-live-protocol.md §5).
+ * This is the pure decision. The gateway supplies sockets and timers; the
+ * fencing rule — mark the loser superseded BEFORE closing it, drop its
+ * in-flight frames — is part of the contract and encoded in the verdict.
+ */
+import { CLOSE_CODES, type TunnelHello } from '../contracts/frames/tunnel.js';
+/** A newcomer with a holder present buffers unrouted until its first identity-bearing hello, bounded by this deadline (AMALGM_TUNNEL_HELLO_ARBITRATION_MS). */
+export declare const ARBITRATION_DEADLINE_MS = 3000;
+export type SlotIdentity = Pick<TunnelHello, 'instance_id' | 'boot_ts'>;
+export type SlotVerdict = 
+/** Free slot, or the newcomer won: install it. `fenceHolder` demands the holder be superseded-then-closed (4000) with its frames dropped. */
+{
+    readonly install: true;
+    readonly fenceHolder: boolean;
+    readonly rule: 'free-slot' | 'same-instance-reconnect' | 'newer-boot' | 'legacy-last-connect-wins';
+}
+/** The newcomer lost: refuse with 4009. The holder is untouched. */
+ | {
+    readonly install: false;
+    readonly closeCode: typeof CLOSE_CODES.supersededInstance;
+    readonly rule: 'older-or-equal-boot';
+};
+/**
+ * Decide a contested slot.
+ *
+ * - same `instance_id`      → newer socket wins (the same process reconnecting)
+ * - different `instance_id` → strictly newer `boot_ts` wins; older or EQUAL loses
+ * - unusable identity on either side (or the deadline expired — pass
+ *   `holder: null` identity via `legacyFallback`) → last-connect-wins, logged as such by the caller
+ */
+export declare function decideSlot(holder: SlotIdentity | null, newcomer: Partial<SlotIdentity>): SlotVerdict;
+//# sourceMappingURL=arbitration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"arbitration.d.ts","sourceRoot":"","sources":["../../src/machines/arbitration.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAqB,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjG,+JAA+J;AAC/J,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAE7C,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,GAAG,SAAS,CAAC,CAAC;AAExE,MAAM,MAAM,WAAW;AACrB,6IAA6I;AAC3I;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,yBAAyB,GAAG,YAAY,GAAG,0BAA0B,CAAA;CAAE;AAC/J,oEAAoE;GAClE;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,WAAW,CAAC,kBAAkB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAEjI;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,WAAW,CAepG"}

package/dist/machines/arbitration.js

@@ -0,0 +1,37 @@
+/**
+ * Tunnel slot arbitration — who owns `(computer_id, runtime_label)`.
+ *
+ * The gateway holds one slot per runtime identity; a newcomer's first
+ * identity-bearing hello decides the winner (local-live-protocol.md §5).
+ * This is the pure decision. The gateway supplies sockets and timers; the
+ * fencing rule — mark the loser superseded BEFORE closing it, drop its
+ * in-flight frames — is part of the contract and encoded in the verdict.
+ */
+import { CLOSE_CODES, hasUsableIdentity } from '../contracts/frames/tunnel.js';
+/** A newcomer with a holder present buffers unrouted until its first identity-bearing hello, bounded by this deadline (AMALGM_TUNNEL_HELLO_ARBITRATION_MS). */
+export const ARBITRATION_DEADLINE_MS = 3_000;
+/**
+ * Decide a contested slot.
+ *
+ * - same `instance_id`      → newer socket wins (the same process reconnecting)
+ * - different `instance_id` → strictly newer `boot_ts` wins; older or EQUAL loses
+ * - unusable identity on either side (or the deadline expired — pass
+ *   `holder: null` identity via `legacyFallback`) → last-connect-wins, logged as such by the caller
+ */
+export function decideSlot(holder, newcomer) {
+    if (holder === null) {
+        return { install: true, fenceHolder: false, rule: 'free-slot' };
+    }
+    if (!hasUsableIdentity(newcomer) || !hasUsableIdentity(holder)) {
+        return { install: true, fenceHolder: true, rule: 'legacy-last-connect-wins' };
+    }
+    const contender = newcomer;
+    if (contender.instance_id === holder.instance_id) {
+        return { install: true, fenceHolder: true, rule: 'same-instance-reconnect' };
+    }
+    if (contender.boot_ts > holder.boot_ts) {
+        return { install: true, fenceHolder: true, rule: 'newer-boot' };
+    }
+    return { install: false, closeCode: CLOSE_CODES.supersededInstance, rule: 'older-or-equal-boot' };
+}
+//# sourceMappingURL=arbitration.js.map

package/dist/machines/arbitration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arbitration.js","sourceRoot":"","sources":["../../src/machines/arbitration.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAoB,MAAM,+BAA+B,CAAC;AAEjG,+JAA+J;AAC/J,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAU7C;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,MAA2B,EAAE,QAA+B;IACrF,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAClE,CAAC;IACD,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,0BAA0B,EAAE,CAAC;IAChF,CAAC;IACD,MAAM,SAAS,GAAG,QAAwB,CAAC;IAC3C,IAAI,SAAS,CAAC,WAAW,KAAK,MAAM,CAAC,WAAW,EAAE,CAAC;QACjD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,yBAAyB,EAAE,CAAC;IAC/E,CAAC;IACD,IAAI,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;QACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAClE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,CAAC,kBAAkB,EAAE,IAAI,EAAE,qBAAqB,EAAE,CAAC;AACpG,CAAC"}

package/dist/machines/backoff.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tunnel reconnect policy (local-live-protocol.md §5, runtime client
+ * behavior).
+ *
+ * Two rules keep a two-instance fight from becoming a reconnect war:
+ *
+ * 1. Exponential backoff resets to 1s only after a connection SURVIVED the
+ *    stable window; a connection that dies younger keeps (and grows) the
+ *    previous backoff.
+ * 2. A 4009 refusal ("superseded instance") retries after a fixed long
+ *    delay — never a full stop, because a wrongly-refused instance must
+ *    still recover once the true holder dies.
+ */
+/** AMALGM_TUNNEL_SUPERSEDED_RETRY_MS */
+export declare const SUPERSEDED_RETRY_MS: number;
+/** AMALGM_TUNNEL_STABLE_RESET_MS — survival time that earns a reset to the base delay. */
+export declare const STABLE_RESET_MS = 30000;
+export declare const BASE_DELAY_MS = 1000;
+export declare const MAX_DELAY_MS = 60000;
+export interface BackoffState {
+    /** The delay the NEXT failure will use. */
+    readonly delayMs: number;
+}
+export declare const initialBackoff: BackoffState;
+export interface Disconnect {
+    readonly closeCode?: number;
+    /** How long the connection lived before dying. */
+    readonly connectedForMs: number;
+}
+export interface ReconnectPlan {
+    readonly waitMs: number;
+    readonly next: BackoffState;
+    readonly rule: 'superseded-fixed-retry' | 'stable-reset' | 'exponential';
+}
+export declare function planReconnect(state: BackoffState, disconnect: Disconnect): ReconnectPlan;
+//# sourceMappingURL=backoff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/machines/backoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,wCAAwC;AACxC,eAAO,MAAM,mBAAmB,QAAa,CAAC;AAC9C,0FAA0F;AAC1F,eAAO,MAAM,eAAe,QAAS,CAAC;AACtC,eAAO,MAAM,aAAa,OAAQ,CAAC;AACnC,eAAO,MAAM,YAAY,QAAS,CAAC;AAEnC,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,cAAc,EAAE,YAAyC,CAAC;AAEvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,wBAAwB,GAAG,cAAc,GAAG,aAAa,CAAC;CAC1E;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,GAAG,aAAa,CAWxF"}

package/dist/machines/backoff.js

@@ -0,0 +1,34 @@
+/**
+ * Tunnel reconnect policy (local-live-protocol.md §5, runtime client
+ * behavior).
+ *
+ * Two rules keep a two-instance fight from becoming a reconnect war:
+ *
+ * 1. Exponential backoff resets to 1s only after a connection SURVIVED the
+ *    stable window; a connection that dies younger keeps (and grows) the
+ *    previous backoff.
+ * 2. A 4009 refusal ("superseded instance") retries after a fixed long
+ *    delay — never a full stop, because a wrongly-refused instance must
+ *    still recover once the true holder dies.
+ */
+import { CLOSE_CODES } from '../contracts/frames/tunnel.js';
+/** AMALGM_TUNNEL_SUPERSEDED_RETRY_MS */
+export const SUPERSEDED_RETRY_MS = 5 * 60_000;
+/** AMALGM_TUNNEL_STABLE_RESET_MS — survival time that earns a reset to the base delay. */
+export const STABLE_RESET_MS = 30_000;
+export const BASE_DELAY_MS = 1_000;
+export const MAX_DELAY_MS = 60_000;
+export const initialBackoff = { delayMs: BASE_DELAY_MS };
+export function planReconnect(state, disconnect) {
+    if (disconnect.closeCode === CLOSE_CODES.supersededInstance) {
+        // Fixed, slow, and does not disturb the exponential state: an instance
+        // alternating between refusals and crashes must not launder its backoff.
+        return { waitMs: SUPERSEDED_RETRY_MS, next: state, rule: 'superseded-fixed-retry' };
+    }
+    if (disconnect.connectedForMs >= STABLE_RESET_MS) {
+        return { waitMs: BASE_DELAY_MS, next: initialBackoff, rule: 'stable-reset' };
+    }
+    const grown = Math.min(state.delayMs * 2, MAX_DELAY_MS);
+    return { waitMs: state.delayMs, next: { delayMs: grown }, rule: 'exponential' };
+}
+//# sourceMappingURL=backoff.js.map

package/dist/machines/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/machines/backoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAE5D,wCAAwC;AACxC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,MAAM,CAAC;AAC9C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AACtC,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAC;AACnC,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AAOnC,MAAM,CAAC,MAAM,cAAc,GAAiB,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;AAcvE,MAAM,UAAU,aAAa,CAAC,KAAmB,EAAE,UAAsB;IACvE,IAAI,UAAU,CAAC,SAAS,KAAK,WAAW,CAAC,kBAAkB,EAAE,CAAC;QAC5D,uEAAuE;QACvE,yEAAyE;QACzE,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC;IACtF,CAAC;IACD,IAAI,UAAU,CAAC,cAAc,IAAI,eAAe,EAAE,CAAC;QACjD,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IAC/E,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,EAAE,YAAY,CAAC,CAAC;IACxD,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;AAClF,CAAC"}

package/dist/machines/bootstrap.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 type { StateEvent } from '../contracts/events.js';
+import type { Snapshot } from '../contracts/snapshot.js';
+import { type StreamFrame } from '../contracts/frames/stream.js';
+export type BootstrapCommand = 
+/** Install the snapshot, then apply the events in order, then follow live from the snapshot's seq. */
+{
+    readonly command: 'install';
+    readonly snapshot: Snapshot;
+    readonly replay: readonly StateEvent[];
+}
+/** The peer is legacy: fetch a REST snapshot and run the full-snapshot barrier. Buffered events are handed back. */
+ | {
+    readonly command: 'fallback-legacy';
+    readonly held: readonly StateEvent[];
+    readonly reason: 'state-before-snapshot' | 'ping-before-snapshot' | 'timeout';
+}
+/** Bootstrap snapshot build failed server-side; the stream is ending. Fall back to the REST path. */
+ | {
+    readonly command: 'fallback-error';
+    readonly status?: number;
+} | {
+    readonly command: 'none';
+};
+/** One instance per bootstrap-mode connection attempt; discard after it resolves. */
+export declare class BootstrapMachine {
+    #private;
+    readonly timeoutMs = 5000;
+    /** Feed each stream frame until a command other than `none` resolves the machine. */
+    accept(frame: StreamFrame): BootstrapCommand;
+    /** The host's timer fired without a snapshot frame. */
+    expire(): BootstrapCommand;
+}
+/**
+ * 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 declare class SnapshotBarrier {
+    #private;
+    get inFlight(): boolean;
+    begin(): void;
+    /** Returns true when the event was held (a snapshot body is in flight). */
+    hold(event: StateEvent): boolean;
+    /** The snapshot body landed: install it, then apply the returned events in order. */
+    complete(snapshot: Snapshot): StateEvent[];
+    /** The snapshot fetch failed: release nothing; the caller re-syncs. */
+    abandon(): void;
+}
+//# sourceMappingURL=bootstrap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/machines/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEhG,MAAM,MAAM,gBAAgB;AAC1B,sGAAsG;AACpG;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE;AACtG,oHAAoH;GAClH;IAAE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,GAAG,sBAAsB,GAAG,SAAS,CAAA;CAAE;AAC9J,qGAAqG;GACnG;IAAE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC,qFAAqF;AACrF,qBAAa,gBAAgB;;IAI3B,QAAQ,CAAC,SAAS,QAAiC;IAEnD,qFAAqF;IACrF,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,gBAAgB;IAoC5C,uDAAuD;IACvD,MAAM,IAAI,gBAAgB;CAO3B;AAED;;;;;GAKG;AACH,qBAAa,eAAe;;IAI1B,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,KAAK,IAAI,IAAI;IAKb,2EAA2E;IAC3E,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO;IAMhC,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,UAAU,EAAE;IAO1C,uEAAuE;IACvE,OAAO,IAAI,IAAI;CAIhB"}