@deepfates/lync 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 deepfates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,374 @@
+# lync
+
+Most software forgets. Edit a document and yesterday's version is gone. Write
+with an AI that offers three options and the two you do not pick vanish. Let a
+tool merge two people's edits and you get one result with no memory of who did
+what or what was dropped. The story of how a thing came to be is thrown away at
+every step.
+
+lync keeps it. A `.lync` file is a list of events, one per line, in plain text.
+Each line records one thing that happened. Someone wrote a sentence, marked a
+version as good, or chose one branch over another. You never edit a line. To
+change something you add a new line that points at the old one and says what
+changed. The old line stays.
+
+That one rule, only ever add and never edit, is where everything good comes
+from. You can always see the whole history, every version and every branch you
+did not take. Merging two copies is safe and boring, because you keep every
+event from both and there are no edits to fight over. If the same event ever
+shows up two different ways, lync keeps both and says so out loud instead of
+quietly picking one. And because the file is plain text with a written-down
+spec, you can still read it in twenty years, on a computer that has never heard
+of this software.
+
+A lync file is more than a transcript, because it keeps the branches and the
+choices. From the same file you can make a readable document to hand someone,
+or training data built from the exact versions you marked as good.
+
+`@deepfates/lync` is the reference implementation. One package, zero runtime
+dependencies, holding the parser, the event stores, the computed views, the
+loom API, live sync, the `lync` command, and the sync relay. The format is the
+durable center. Everything else is a tool that reads and writes it.
+
+## The Format
+
+The normative specification is [FORMAT.md](./FORMAT.md). It is self-contained:
+no code in this repository is required to implement it.
+
+The short version:
+
+- A `.lync` file is UTF-8 JSONL, no BOM, one event object per LF-terminated
+  line.
+- The required event fields are `v`, `id`, `kind`, `at`, `author`, `parents`,
+  and `payload`.
+- `author.actor` is the content producer; `author.via` is the app or runtime;
+  converters use `imported_by` and preserve the original actor.
+- Events are immutable. Correction, judgment, selection, and retraction are new
+  events that point at prior events.
+- Merge is union by event id. Same id plus same body bytes is one event seen
+  twice; same id plus different body bytes is a surfaced conflict variant and is
+  excluded from ordinary views.
+- Stored line metadata may splice `digest` and `sig` at the end of the line.
+  `digest` and `sig` are reserved top-level body names; payloads may use those
+  names freely.
+- Views are computed. This package ships branch tree, transcript, memory, and
+  leaderboard helpers.
+
+Every line has the same envelope:
+
+```json
+{"v":1,"id":"root","kind":"notes/text","at":"2026-07-06T04:12:31Z","author":{"actor":"deepfates","via":"example@0.1"},"parents":[],"payload":{"text":"Once..."}}
+```
+
+That line can be copied to another file, merged back later, verified byte for
+byte, and read by software that has never heard of `notes/text`. Unknown
+kinds are carried and traversed; meaning belongs to pacts layered above the
+format — see [pacts/import.md](./pacts/import.md) (imports are transcription:
+deterministic ids, provenance preserved, zero silent drops) and
+[pacts/export.md](./pacts/export.md) (exports are projections of the event
+log, including training data).
+
+## Conformance Vectors
+
+The format is meant to be implemented in other languages, and the test
+vectors are the product that makes a port checkable:
+[test/vectors/v0](./test/vectors/v0). Each case is a directory holding a raw
+input file (`input.lync`, or `a.lync` + `b.lync` for the merge case) and an
+`expected.json` with the required classification of every physical line —
+accepted, nonconforming, garbage, damaged, conflict-variant — plus union ids,
+pending parents, and graph diagnostics. The thirteen cases cover valid events,
+splice anchoring, damaged digests, garbage classes, same-id conflicts and
+duplicates, graph obstacles, critical suppression, spelling-versus-value
+equality, `marked`/`at` semantics, merge union, carried nonconforming lines,
+and invalid signature splices.
+
+A new implementation ports the vector suite first, this package's test suite
+second, and its design never. `test/vectors/v0/README.md` documents the
+expected-output schema; `generate.py` regenerates digests deterministically.
+
+## The Library
+
+```bash
+npm install @deepfates/lync
+```
+
+Runs in Node (>=22) and the browser. No dependencies.
+
+### Parse, union, view
+
+```ts
+import { parseLyncFiles } from "@deepfates/lync/events";
+import { lyncBranchTreeView, lyncTranscriptView } from "@deepfates/lync/views";
+
+const bytes = new TextEncoder().encode(
+  '{"v":1,"id":"root","kind":"notes/text","at":"2026-07-06T04:12:31Z","author":{"actor":"you"},"parents":[],"payload":{"text":"Once..."}}\n',
+);
+
+const parsed = parseLyncFiles([{ file: "story.lync", bytes }]);
+console.log(parsed.lines[0].class); // "accepted"
+console.log(lyncBranchTreeView(parsed).roots);
+console.log(lyncTranscriptView(parsed, "root").entries.map((entry) => entry.id));
+```
+
+`parseLyncFiles` classifies every physical line and keeps the original bytes —
+accepted events, nonconforming-but-carried lines, damaged lines, garbage, and
+conflict variants (same id, different bytes) are all preserved and reported,
+never silently dropped. `exportCarriedLyncBytes(parsed)` re-emits the carried
+bytes. `LyncUnion` performs the same union incrementally and can buffer
+children until their first missing parent arrives.
+
+### Stores and looms
+
+Event stores share one contract over memory, file, and IndexedDB backends. The
+loom API gives programs turns and threads instead of raw events, on top of any
+store:
+
+```ts
+import { createLyncLooms } from "@deepfates/lync/looms";
+import { createMemoryEventStore } from "@deepfates/lync/memory-log";
+
+const looms = createLyncLooms({
+  store: createMemoryEventStore(),
+  author: { actor: "you", via: "my-app@0.1" },
+});
+
+const info = await looms.create({ title: "Story" });
+const loom = await looms.open(info.id);
+const first = await loom.appendTurn(null, { text: "Once..." });
+await loom.appendTurn(first.id, { text: "Then..." });
+```
+
+The store API accepts raw lines through `union(line)` and structured event
+bodies through `append(event)`. It reports conflicts, pending parents, garbage,
+and accepted events without making file order meaningful.
+
+### Indexes
+
+An index tracks a collection of looms — upsert entries, subscribe to changes:
+
+```ts
+import { loomRef } from "@deepfates/lync";
+import { createMemoryLoomIndexes } from "@deepfates/lync/indexes/memory";
+
+const indexes = createMemoryLoomIndexes();
+const index = await indexes.create({ title: "My looms" });
+
+index.subscribe((event) => console.log("index changed:", event.type));
+await index.addLoom(loomRef("loom-1"), { title: "Story" });
+
+console.log((await index.entries()).map((entry) => entry.title));
+```
+
+Entries carry a loom reference, optional title/kind/meta, and timestamps.
+`export()`/`import()` round-trip a whole index as a snapshot.
+
+### The loom client
+
+One object that pairs looms with an index and resolves
+loom/turn/thread/index references to and from URLs:
+
+```ts
+import { createLyncLooms } from "@deepfates/lync/looms";
+import { createMemoryEventStore } from "@deepfates/lync/memory-log";
+import { createMemoryLoomIndexes } from "@deepfates/lync/indexes/memory";
+import { createLoomClient } from "@deepfates/lync/client";
+
+const client = createLoomClient({
+  looms: createLyncLooms({ store: createMemoryEventStore(), author: { actor: "you" } }),
+  indexes: createMemoryLoomIndexes(),
+});
+
+const info = await client.looms.create({ title: "Story" });
+const ref = client.references.loom(info.id);
+
+// Round-trip a reference through a shareable URL (?ref=...).
+// In the browser, pass `window.location` instead of a URL object.
+const url = client.references.toUrl(ref, new URL("https://example.com/story"));
+const opened = await client.openReference(client.references.fromUrl(new URL(url)));
+console.log(opened.kind); // "loom" — opened.loom is ready to appendTurn
+```
+
+`@deepfates/lync/client/testing` ships `createTestLoomClient`, a fully in-memory
+client for tests and embedded experiments — deterministic when you pass
+`createId` and `now`.
+
+### Live sync inside an app
+
+The sync protocol runs in a browser or Node app with no CLI. Wrap any event
+store in `createSyncedStore`; looms and indexes built over it update live as
+collaborators append, because they already recompute through the store's
+`subscribe`:
+
+<!-- example: fragment — needs a live relay and an app render loop; covered by the synced-store tests -->
+```ts
+import { createMemoryEventStore } from "@deepfates/lync/memory-log";
+import { createLyncLooms } from "@deepfates/lync/looms";
+import { createSyncedStore, createWebSocketTransport } from "@deepfates/lync/synced-store";
+
+const transport = createWebSocketTransport("wss://host/lync");
+const store = createSyncedStore(createMemoryEventStore(), transport, {
+  onStatus: (s) => console.log("sync:", s.connection, "live:", s.liveRoots),
+});
+const looms = createLyncLooms({ store, author: { actor: "alice" } });
+
+const loom = await looms.open(loomId);
+loom.subscribe(() => render(loom)); // fires on local AND remote turns
+await loom.appendTurn(parentId, { text: "typed live" });
+```
+
+Local appends are pushed to the relay; remote lines are ingested through the
+same `union` path and surface reactively. Offline appends queue and flush on
+reconnect; the store re-subscribes automatically. The transport is an
+interface — pass your own for tests or a non-WebSocket carrier. The client
+side uses the platform's built-in WebSocket: no dependency, in the browser or
+in Node.
+
+### Subpath exports
+
+- `@deepfates/lync/events` — line parsing, carried-byte export, incremental union
+- `@deepfates/lync/store` — the event-store contract and serialization
+- `@deepfates/lync/memory-log`, `@deepfates/lync/file-log`, `@deepfates/lync/idb-log` — stores
+  (`file-log` is node-only; it keeps `node:fs` off the browser path)
+- `@deepfates/lync/views` — branch tree, transcript, memory, leaderboard
+- `@deepfates/lync/looms` — the loom/turn API
+- `@deepfates/lync/references` — loom/turn/thread/index references and URLs
+- `@deepfates/lync/synced-store` — live sync decorator and WebSocket transport
+- `@deepfates/lync/sync-protocol` — the five sync frames, encode/decode
+- `@deepfates/lync/uuid` — zero-dep UUIDv7 for event ids
+- `@deepfates/lync/indexes`, `@deepfates/lync/indexes/entries`,
+  `@deepfates/lync/indexes/memory`, `@deepfates/lync/indexes/types` — loom indexes
+- `@deepfates/lync/client`, `@deepfates/lync/client/testing`, `@deepfates/lync/client/types` —
+  the loom client
+- `@deepfates/lync/relay` — the sync relay (see [The Relay](#the-relay))
+
+## The Command
+
+The package installs a `lync` bin with seven verbs: `init`, `append`,
+`verify`, `merge`, `view`, `serve`, and `sync`.
+
+```bash
+npm install -g @deepfates/lync
+```
+
+```bash
+lync init story.lync
+printf '%s\n' '{"kind":"notes/text","author":{"actor":"you"},"payload":{"text":"Once..."}}' | lync append story.lync
+lync verify story.lync
+lync view story.lync --as transcript
+printf '%s\n' '{"kind":"notes/text","author":{"actor":"friend"},"payload":{"text":"Then..."}}' | lync append other.lync
+lync merge story.lync other.lync -o merged.lync
+lync view merged.lync --as tree
+```
+
+`append` fills the envelope for you: a UUIDv7 id, the current timestamp, `v`,
+and `parents` default in; anything you supply is kept. `verify` reports what
+every physical line is — accepted, nonconforming, damaged, garbage, or
+conflict variant — and never drops bytes; it exits 0 only when every line is
+accepted. `view` renders `transcript` or `tree`.
+
+Any lync file can converge with any other copy through a relay:
+
+<!-- example: fragment — needs a live relay pair; the serve/sync path is covered by the relay and cli test suites -->
+```bash
+lync serve ./rooms --port 8787              # the relay: one append-only file per root
+lync sync story.lync ws://host:8787         # one-shot: push what it lacks, pull what you lack
+lync sync story.lync ws://host:8787 --follow  # stay live until Ctrl-C
+```
+
+`lync sync` uses Node's built-in WebSocket — no install beyond the package.
+`lync serve` runs the relay and needs `ws` present (`npm install ws`); see
+below.
+
+## The Relay
+
+The relay is deliberately dumb. Events are immutable and merge is union by
+id, so the protocol has no merge logic: five JSON frames (`sub`, `ev`,
+`live`, `presence`, `err`) that move canonical line bytes. The server never
+parses a line beyond extracting its id, stores each root as a plain `.lync`
+file you can read with any lync tool, and echoes accepted events to every
+subscriber — echoes are duplicate no-ops under union. `seq` is a per-root
+arrival counter used as a resume cursor (`<file>.sync.json`), so an offline
+client reconnects exactly where it left off.
+
+Running a relay is the one thing that needs a WebSocket server, and Node does
+not ship one — so the relay acquires [`ws`](https://www.npmjs.com/package/ws)
+lazily at the moment you construct it. `@deepfates/lync` declares no dependency on
+`ws` at all: install it yourself next to your server
+(`npm install ws`), and everything else in the package works without it.
+If you bundle a server that runs the relay, mark `ws` as external — the
+acquisition is a dynamic require that bundlers cannot see through.
+
+Standalone:
+
+<!-- example: daemon — expect "relay on" -->
+```ts
+import { startLyncServe } from "@deepfates/lync/relay";
+
+const server = await startLyncServe({ dir: "./rooms", port: 8787 });
+console.log("relay on", server.port);
+
+// Look inside a running relay — read-only, mutates nothing. Each record is
+// { root, generation, seq, subscribers, pendingUnpersisted }, where
+// pendingUnpersisted is the durability lag: lines in memory but not yet on disk.
+for (const room of server.status()) {
+  console.log(room.root, "seq", room.seq, "subs", room.subscribers, "lag", room.pendingUnpersisted);
+}
+// later: await server.close();
+```
+
+On an existing HTTP server:
+
+<!-- example: fragment — embeds into an existing app server (free variables: app, checkSession) -->
+```ts
+import { createServer } from "node:http";
+import { attachLyncServer } from "@deepfates/lync/relay";
+
+const httpServer = createServer(app);
+const lync = attachLyncServer(httpServer, {
+  storageDir: "./rooms",
+  path: "/lync",              // default
+  keepAliveInterval: 30_000,  // optional: ping through idle proxies
+  maxConnections: 500,        // optional
+  authenticate: (req) => checkSession(req), // optional, after token check
+});
+httpServer.listen(3000);
+```
+
+For full control, `createLyncRelay` gives you `handleUpgrade` to call from
+your own `upgrade` listener. All three (`createLyncRelay`, `startLyncServe`,
+`attachLyncServer`) expose `status()` — a read-only snapshot of every live
+room's seq, subscriber count, and pending-unpersisted durability lag.
+
+Guarantees: same-id-different-bytes is never resolved — both variants are
+kept (a `.conflicts` sidecar) and both sides are told loudly. Persist failures
+are broadcast, never swallowed. A truncated final line after a crash is
+sealed and surfaced as damaged, never eaten. Presence frames are relayed,
+never stored. `--token T` (or `token` in the API) requires
+`Authorization: Bearer T` on every upgrade.
+
+The relay is a tool shipped beside the format, not part of it: FORMAT.md
+deliberately excludes sync protocols, and any transport that moves canonical
+line bytes and unions by id converges the same files without this relay.
+
+## Development
+
+<!-- example: fragment — repo setup commands that need a checkout, not a scratch dir; scripts/fresh-clone-smoke.sh runs this exact sequence in a temporary clone -->
+```bash
+pnpm install
+pnpm build
+node bin/lync.js --help
+pnpm test
+pnpm verify
+```
+
+`pnpm verify` runs the path guard, tests, build + typecheck, and executes
+every fenced example in this README against the built package
+(`pnpm check:examples`). README examples are contract: a block runs
+as-written unless an `<!-- example: fragment -->` comment above it declares
+why it can't run alone.
+
+For a fresh clone, `pnpm install && pnpm build` is the supported setup
+sequence. After that, `node bin/lync.js --help` prints the CLI help.
+`scripts/fresh-clone-smoke.sh` verifies that sequence in a temporary clone
+and runs the CLI story path: init, append, view, concatenate, merge, and
+verify.

package/bin/lync.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli/bin.js";

package/dist/cli/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":""}

package/dist/cli/bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runLyncCli } from "./index.js";
+const code = await runLyncCli(process.argv.slice(2));
+process.exitCode = code;
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACrD,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,11 @@
+export interface LyncCliIO {
+    stdout?: Pick<NodeJS.WriteStream, "write">;
+    stderr?: Pick<NodeJS.WriteStream, "write">;
+    stdin?: NodeJS.ReadStream;
+    now?: () => Date;
+    randomId?: () => string;
+}
+type ExitCode = 0 | 1 | 2;
+export declare function runLyncCli(argv: string[], io?: LyncCliIO): Promise<ExitCode>;
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;CACzB;AAED,KAAK,QAAQ,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAK1B,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,SAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAkCtF"}