amalgm-live

The portable realtime SDK for the Amalgm platform.

One library owns every wire contract and every delivery state machine for synchronizing entities, documents, and presence between a machine and the cloud authority — behind adapters the host injects. No filesystem, no SQLite, no UI dependency.

const binding = live.bind(surface, channel)

Start with PURPOSE.md — purpose, axioms, and layout — and ROADMAP.md for what moves here next. The normative specifications live in docs/:

| document | owns | | --- | --- | | realtime-sdk.md | the public bind(surface, channel) model | | local-live-protocol.md | the shipped local wire protocol (v1/v2) | | entity-record-queues.md | filesystem Record, local Outbox, per-UUID cloud order, and local Inbox | | entity-apply.md | intent-first, type-sensitive Apply and exact Verify | | shared-realtime-wave-3.md | the multi-user cloud-authority design | | extraction-boundary.md | what moves here from the engine runtime, and in what order | | user-ground-login.md | first-login publication, later-device materialization, and Watch readiness | | watching.md | Watch purpose, axioms, lifecycle matrix, and cross-platform test layers |

Surfaces

| surface | entry | what it is | | --- | --- | --- | | SDK | src/ → @amalgm/live | the behavior: contracts, machines, adapter ports | | API | surfaces/api/ | REST router factory a host mounts | | CLI | surfaces/cli/ | amalgm-live — inspect, derive, validate, simulate | | MCP | surfaces/mcp/ | the same actions, exposed to agents | | Skill | skills/live/ | teaches an agent this protocol via the CLI/MCP |

Every surface delegates to src/. One behavior, five doors.

Develop

npm install
npm test              # build + unit tests
npm run test:parity   # golden vectors vs the shipped engine runtime