fieldlog 0.15.0

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# fieldlog changelog
+
+All entries describe user-visible changes shipped under each tag, in tag order.
+Untagged commits are folded into the next tag that shipped them.
+
+## Unreleased
+
+(No unreleased changes yet.)
+
+## v0.15.0 — truncate guards, fail-closed gates, relay budgets
+
+- Retention: `truncate()` guarded by `guardSeal` — sweep stops at the acked/applied prefix, skips legally-held events, and never splits a tombstone hide/show pair; report names held events and pairs that blocked the rest.
+- Read-model: tamper gate fails closed on hash mismatch (no silent merge of edited payloads); swept UUIDs recorded in `_swept_ids` so re-appending an excised id throws instead of forking log vs store.
+- Hash chain: `verifyChain` checks seq continuity plus hash/prev linkage, with `opts.base`/`opts.startSeq` to pin a post-sweep base (foreign `prev_hash` hints at `log.verify()` instead of failing cryptic).
+- Quota wired: `createKernel({ quotaLimitBytes })` reserves per append and throws `ERR_QUOTA_EXCEEDED`/`ERR_QUOTA_UNKNOWN` fail-closed before anything is written; `kernel.quota()` reports usage.
+- Relay budgets: per-batch event-count and per-event byte caps on push, revoke push, and raw frames; pull paginated with count + total-byte caps (client walks pages to the global cursor); oversized startup file refused loud instead of OOMing; byte sizes measured in UTF-8, not UTF-16 length.
+- Auth: `CapToken.notBefore` activation floor (early token fails closed); corrupt delta-sync resume/dead-set meta throws instead of silently refetching or resurrecting poison.
+- Surface: `health()`/`verifyLog()` expose `skipped` poison lines (open-time replay warns `WARN_REPLAY_SKIPPED`); CAS quarantine persisted in the manifest (`has` hides quarantined keys, `stat` reports the sidecar, `gc` skips them); tombstone `show` atomic with same-replica check; snapshot lock file serializes cross-process writers (`ERR_SNAPSHOT_IN_FLIGHT`); torn-tail repair fsyncs file + dir.
+- Compat: interop-seal test skips when the sibling checkout is absent (green CI without it).
+- Bench (2026-09-12, slice fa03a62, bun 1.4.0): append 262/s (p50 3.06 ms, p99 7.89 ms); that cost is fsync-per-append + SQLite apply — durability, not overhead. Full numbers in `docs/bench.md`, the single source of truth.
+- Decisions: `docs/decisions.md` records five standing calls (epoch-less token reissue, `dist/` out of scope, plaintext relay behind WireGuard, no claim engine here, dated single-source bench pins).
+
+## v0.13.0–v0.14.26 — folded (no per-tag notes; untagged waves per the rule above)
+
+- Auth: granular per-token capabilities (named TTLs) enforced per operation; revoke event log with convergent merge, revoke handshake on every relay connect/pull, revoke quarantine + retroactive purge on sync.
+- Storage: sha-keyed CAS store (refcount, quarantine); tombstone soft-delete engine with GC guard + legal hold; quota guard with reserve + fail-closed admission.
+- Sync: manifest-first delta sync (want-list resume, UUID idempotency); hash-chain-log facade with quarantine + re-anchor.
+- Compat: v0.5 fixtures + conformance runner (writer superset rule).
+- Rig & harness: two-device rig, seeded corpus + corruption generators, bench-honesty doc + check script, cold-drill log-only recovery, model oracle, soak runner, chaos-kill drill, flake-hunter, pre-merge conformance gate, watchdog, mismatch-stop, completion protocol, ff-only merge runner.
+- Audit + perf waves: typecheck clean (`PushResult` exported, relay rng field, CAS writeSync narrowing); 30 audit suspects fixed (relay fail-closed persist — no ack for unwritten events, ack only stored ids; store seq-vs-id collision no longer swallowed; fractional value rejected; sync dead-letter cursors; retain empty-guard returns 0; revokelog convergent tie-break; tombstone guard covers show/target; quota remaining clamped; canonical payload key order; duplicate-id append rejected; seq-gap verification; device mismatch throws with first-explicit adoption; threshold misconfig throws; CAS orphan sweep + EEXIST tolerance + fstat + guarded quarantine; deltasync real dead-letter list + honest fetched metric); kernel split healing O(1) steady-state; relay liveBuf dedup via persistent Set, token verdicts cached per revoke size, incremental `purgeRevoked`, deterministic backoff jitter by default. Suite: 218 tests green, tsc clean.
+## v0.14.27 — docs, gallery, universal wire keys
+
+- Wire keys universalized (no commerce terms): `entry`/`value`/`tally`/`resolve`, device ids; English CLI/demo/scripts/tests narrative (schema field `oleh` kept, fixtures kept).
+- Docs: README is now the entry point + index; one concern per topic page (install,
+  quickstart, architecture, kernel-api, sync-protocol, relay, retention,
+  auth, contracts, cli, limits-troubleshooting), API tables verified against `src/`.
+- New: `SECURITY.md`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md` (solo/small-team).
+- Bench: full numbers in `docs/bench.md` (single source of truth for figures).
+- Repo: lean tarball (no docs), OIDC tag-publish provenance, byte-exact fixtures via gitattributes.
+
+- Gallery: 8 APNG explainers + logo in README (docs/gifs/, outside the tarball).
+## v0.1.0 — offline kernel
+
+- Initial release: offline-first `createKernel({ file })` with `append` / `query` / `undo`, no network needed for local writes.
+- Append-only JSONL log with a sha256 hash chain per event (`GENESIS` anchor, `tail -f` friendly).
+- SQLite read-model via `bun:sqlite` (plain SQLite file, opens in external tools); money honesty rule (offline money is only RECORDED, resolution needs online ack) and fail-fast `checkAppend` so rejected writes leave no log line behind.
+- Device identity: per-device keypairs, event signing/verification, scope grants, countersignatures with threshold check, revocation list.
+- Sync core: `MemoryRelay`, `pushPending` / `pullRemote` / `syncKernel` with ack-cursor resume and backoff; open conflicts queryable via `kernel.conflicts()`; `undo` as compensating events.
+
+## v0.2.0 — real ws relay
+
+- `WsRelayServer` / `WsRelayClient`: real websocket transport over `Bun.serve`, no extra dependencies.
+- Client reconnects with backoff and jitter and resumes from the ack cursor; server live-broadcasts arrivals as a hint (pull stays the source of truth) with heartbeat ping/pong.
+
+## v0.3.0 — hardening and clock skew
+
+- Corrupt log lines are quarantined to `<log>.quarantine` (with forensics) instead of failing open; torn tail writes from a mid-append kill are truncated on open and reported via `repairedTail`.
+- Wall clocks are display-only: `ts_device` never decides order, `kernel` accepts an injectable `clock`, and ordering stays on the monotonic seq even with 30-minute device skew.
+- New `kernel.health()` (`events`, `quarantined`, `repairedTail`, `gaps`) and `verifyLog()` gap reporting for re-anchored seqs.
+- `kill9` tests fixed to run from any working directory; new `demo/two-node.ts` (20 offline sales, then two-device sync with equal totals).
+
+## v0.4.0 — relay survives restart
+
+- Relay persists every stored event to a JSONL file before acking; kill and restart resumes exact-once by event UUID from the client ack cursor.
+- Stress coverage with 10 concurrent clients; README rewritten as operator docs.
+
+## v0.5.0 — snapshot, truncate, atomic apply
+
+- Retention: `kernel.snapshot(dest)` captures the read-model plus sealed seq; `kernel.truncate()` sweeps the sealed log prefix behind a `fieldlog-truncate` marker that chains the kept suffix to the removed prefix.
+- Atomic apply: a kill between log append and read-model apply can no longer orphan an event; reopen replays the log into the store idempotently.
+
+## v0.6.0 — cli
+
+- New `bin/fieldlog.ts`: `serve --port <n> --file <relay.log>` runs a file-backed ws relay, `sync --file <ledger.db> --relay <ws url>` pushes and pulls a kernel file's delta, `demo` runs the two-node roundtrip and proves equal totals.
+
+## v0.7.0 — relay capability tokens
+
+- Relays can require capability tokens: `kernel.capToken(privateKeyPem, scopes, ttlMs)` mints push/pull-scoped tokens, the server verifies and enforces them per operation.
+- Revoked devices are broadcast to connected clients and token state persists across relay restarts.
+
+## v0.8.0 — failover and bounded outbox
+
+- `kernel.sync` accepts an ordered relay list: failing relays cool down with backoff, get re-probed, and the list order decides fail-back.
+- Bounded outbox: `append` refuses with `ERR_OUTBOX_FULL` once unsynced events reach the cap (default 50_000, tunable via `maxPending`), so an offline device fails fast instead of growing unbounded.
+
+## v0.9.0 — v0.5 log compat
+
+- Forward-compat guarantee: v0.5-era log files replay byte-for-byte on the current build (fixture test), with the writer superset rule documented in `docs/compat.md`.
+
+## v0.9.1 — poison, forgery, late undo
+
+- Poison pull events are quarantined instead of wedging sync in a livelock; the cursor advances past them.
+- Pull events whose origin signature does not verify against the trusted device key are rejected.
+- `undo` (and `resolve`) targeting an event that has not arrived yet parks and resurrects: the compensation applies once the target arrives late instead of being lost.
+
+## v0.10.0 — ack implies stored
+
+- The ack cursor only advances over events the relay actually acknowledged, closing the ack-without-store hole.
+- `truncate` clamps the seal to the stored and acked prefix, so a sweep can no longer delete unacked or unapplied data (stale seals become safe no-ops).
+
+## v0.11.0 — review highs, failover stripe
+
+- Kernel appends are signed; per-relay pull cursors; CLI signed by default.
+- Failover stripe backfills the acked prefix on relay switch.
+
+## v0.12.0 — release hygiene
+
+- MIT license, pack files list, README install quickstart + docs links.
+- CLI die race fixed: sync stderr write before exit; signed serve documented.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arfoux
+
+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,107 @@
+<p align="center">
+  <img src="docs/gifs/logo.svg" alt="fieldlog logo — event log with verification stamp" width="128">
+</p>
+
+# fieldlog — Fieldlog
+
+Write anywhere, resolve later.
+
+Offline-first event log for apps that keep writing through outages and
+sync later: append-only log (source of truth) + SQLite read-model + sync-later.
+Works for game events, file versions, telemetry samples — a ledger entry
+(below) is one domain, not the whole story.
+
+```js
+import { createKernel } from 'fieldlog';
+
+const k = await createKernel({ file: 'ledger.db' });
+await k.append({ type: 'entry', value: 5000, actor: 'device-01' });
+const rows = await k.query('SELECT SUM(value) AS total FROM entries WHERE voided = 0');
+console.log(rows[0].total); // 5000 — RECORDED, not resolved
+k.close();
+```
+
+Any event shape is stored and synced — game kills, file versions, telemetry
+samples ride the same log:
+
+```js
+import { createKernel } from 'fieldlog';
+
+const k = await createKernel({ file: 'app.db' });
+await k.append({ type: 'kill', killer: 'player-1', victim: 'boss-3' });
+await k.append({ type: 'version', file: 'notes.txt', rev: 3 });
+await k.append({ type: 'sample', sensor: 'temp-1', celsius: 21.5 });
+k.close();
+```
+
+Offline writes are stored as `DRAFT`/`RECORDED` (pre-resolved); sync/ack happens when online.
+`append`/`query`/`undo` never touch the network — only `sync` does. Any event
+shape is stored and synced; the read-model projects `entry` / `tally` / `undo`
+into queryable tables.
+
+## Getting started
+
+- [quickstart](docs/quickstart.md) — 1 device offline, 2 devices syncing (dev + signed mode), runnable
+- [cli](docs/cli.md) — `serve` / `sync` / `demo`, every flag verified against `bin/fieldlog.ts`
+- Two demos, one regime each, no surviving state: `bun run demo`
+  (`demo/two-node.ts`, unsigned dev, fixed port 8091) vs
+  `bun bin/fieldlog.ts demo` (`bin/fieldlog.ts:cmdDemo`, signed, ephemeral
+  port). Either proves 20-entry totals then exits; neither graduates to
+  the other (unsigned rows carry no signatures). Real ledger example:
+  `example/ledger.mjs` (`bun example/ledger.mjs`)
+- Single writer, one process per file: the kernel mutex is cooperative
+  in-process only (`src/kernel.ts:145-156`). Details:
+  [kernel-api](docs/kernel-api.md),
+  [limits-troubleshooting](docs/limits-troubleshooting.md).
+
+## Gallery
+
+| | |
+|---|---|
+| <img src="docs/gifs/part1-log.png" alt="Every append seals to the previous entry, forming a hash chain." width="480"><br>hash chain — every append seals to the previous entry | <img src="docs/gifs/part2-sync.png" alt="Delta sync sends only the diff, resuming from the last ack." width="480"><br>delta sync — only the diff flies, resuming from the last ack |
+| <img src="docs/gifs/part3-relay.png" alt="Offline devices exchange messages through the relay server." width="480"><br>relay — offline devices exchange messages via the server | <img src="docs/gifs/part4-retain.png" alt="Snapshot plus truncate trims the log without losing the trail." width="480"><br>snapshot+truncate — trim the log without losing the trail |
+| <img src="docs/gifs/part5-auth.png" alt="Signed capability tokens gate access, and revocation is ruthless." width="480"><br>capability+revoke — signed tokens, ruthless revocation | <img src="docs/gifs/part6-quarantine.png" alt="Corrupt entries are quarantined, never silently dropped." width="480"><br>quarantine — corrupt entries jailed, never silently dropped |
+| <img src="docs/gifs/part7-readmodel.png" alt="The SQLite read model is rebuilt from the append-only log." width="480"><br>read model — SQLite rebuilt from the log | <img src="docs/gifs/part8-tombstone.png" alt="Delete writes a tombstone, so history stays intact." width="480"><br>soft delete — delete = tombstone, history stays intact |
+
+## Concepts & architecture
+
+- [architecture](docs/architecture.md) — module map: log/store/kernel/sync/relay/cas/retain
+- [contracts](docs/contracts.md) — binding promises: dead-letter, blind compensators,
+  seal<=ack, device.explicit, incremental purge, deterministic jitter, v0.5 superset
+- [kernel-api](docs/kernel-api.md) — `createKernel`, `Kernel`, `LogEvent`, `EventStore`
+- [sync-protocol](docs/sync-protocol.md) — push/pull, failover, backoff, deltasync
+- [relay](docs/relay.md) — `WsRelayServer` + `WsRelayClient`
+- [retention](docs/retention.md) — snapshot + truncate
+- [auth](docs/auth.md) — device key, grant, capability token, countersign, revoke
+
+## Subsystems (details)
+
+- token: [capability-token](docs/capability-token.md) · revoke:
+  [revoke-handshake](docs/revoke-handshake.md),
+  [revoke-event-log](docs/revoke-event-log.md) — regrouped in [auth](docs/auth.md)
+- delta-sync: [delta-sync](docs/delta-sync.md) · hash chain:
+  [hash-chain-log](docs/hash-chain-log.md) · quarantine: [quarantine](docs/quarantine.md)
+- attachments: [cas-store](docs/cas-store.md) · soft-delete:
+  [tombstone-engine](docs/tombstone-engine.md) · quota: [quota-guard](docs/quota-guard.md)
+- rig & harness: [multi-device-rig](docs/multi-device-rig.md),
+  [corpus-generator](docs/corpus-generator.md),
+  [corruption-generator](docs/corruption-generator.md),
+  [cold-drill](docs/cold-drill.md), [soak-runner](docs/soak-runner.md),
+  [chaos-kill](docs/chaos-kill.md), [flake-hunter](docs/flake-hunter.md),
+  [conformance-gate](docs/conformance-gate.md), [watchdog](docs/watchdog.md),
+  [mismatch-stop](docs/mismatch-stop.md), [completion-protocol](docs/completion-protocol.md),
+  [merge-runner](docs/merge-runner.md), [model-oracle](docs/model-oracle.md),
+  [compat-vectors](docs/compat-vectors.md), [decision-log](docs/decision-log.md)
+
+## Numbers, limits, contributing
+
+- Benchmark: [bench](docs/bench.md) — all figures live there (single source
+  of truth). Re-run via `bun run bench:append | bench:query | bench:sync`.
+- Log compat: [compat](docs/compat.md) · changelog: [CHANGELOG](CHANGELOG.md)
+- Limits + troubleshooting: [limits-troubleshooting](docs/limits-troubleshooting.md)
+- Contributing: [CONTRIBUTING](CONTRIBUTING.md) · security: [SECURITY](SECURITY.md) ·
+  conduct: [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md)
+
+CLI serve/sync default to signed mode: serve needs `--trust <id=pub.pem>`
+(repeat per device), sync needs `--key <priv.pem> --as <device>`.
+`--unsigned` open relay is for local dev only, not production.

package/bin/fieldlog.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// bin/fieldlog.js — npm bin shim (valid .js entry). Exec bun on sibling TS entry; clear fallback when bun missing.
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const dir = dirname(fileURLToPath(import.meta.url));
+const entry = join(dir, 'fieldlog.ts');
+const r = spawnSync('bun', [entry, ...process.argv.slice(2)], { stdio: 'inherit' });
+if (r.error) {
+  if (r.error.code === 'ENOENT') {
+    console.error('fieldlog needs the Bun runtime (https://bun.sh). Install Bun, then retry: bun bin/fieldlog.ts --help');
+    process.exit(1);
+  }
+  console.error(r.error.message);
+  process.exit(1);
+}
+process.exit(r.status ?? 1);

package/bin/fieldlog.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env bun
+// bin/fieldlog.ts — small CLI: serve the ws relay, sync a kernel file, run the two-node demo.
+// Bun only. Signed mode by default: serve needs --trust id=pub.pem (repeatable)
+// and sync needs --key priv.pem --as <device>; --unsigned selects the legacy
+// open relay (accepts any device_id, local dev only).
+// examples:
+//   bun bin/fieldlog.ts serve --port 8091 --file ./relay.log --trust device-01=./device-01.pub
+//   bun bin/fieldlog.ts sync --file ./ledger.db --relay ws://127.0.0.1:8091 --key ./device-01.priv --as device-01
+//   bun bin/fieldlog.ts serve --port 8091 --file ./relay.log --unsigned
+//   bun bin/fieldlog.ts demo
+import { mkdtempSync, readFileSync, writeSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createKernel, generateDeviceKey, WsRelayClient, WsRelayServer } from '../src/index.ts';
+
+function usage(): string {
+  return [
+    'usage: fieldlog <serve|sync|demo> [options]',
+    '  serve --port <n> --file <relay.log> --trust <id=pub.pem> [--trust ...]',
+    '    run the file-backed ws relay in signed mode (rejects unknown devices)',
+    '  serve --port <n> --file <relay.log> --unsigned   open relay (dev only)',
+  '  sync --file <app.db> --relay <ws url> --key <priv.pem> --as <device>',
+    '    push+pull the kernel delta with a capability token',
+  '  sync --file <app.db> --relay <ws url> --unsigned   unsigned (dev only)',
+    '  demo   two-node: offline events, then signed-mode sync with matching totals',
+  ].join('\n');
+}
+
+function arg(args: string[], name: string, def?: string): string | undefined {
+  const i = args.indexOf(name);
+  if (i < 0) return def;
+  return args[i + 1] ?? def;
+}
+
+function argAll(args: string[], name: string): string[] {
+  const out: string[] = [];
+  for (let i = 0; i + 1 < args.length; i++) if (args[i] === name) out.push(args[i + 1]);
+  return out;
+}
+
+function die(msg: string): never {
+  // write synchronously: console.error + process.exit race when stderr is piped
+  // (the cli-auth test reads the child process stderr; async writes can be lost).
+  writeSync(2, msg + '\n' + usage() + '\n');
+  process.exit(2);
+}
+
+async function cmdServe(rest: string[]): Promise<void> {
+  const port = Number(arg(rest, '--port', '8091'));
+  const file = arg(rest, '--file', 'relay.log')!;
+  const unsigned = rest.includes('--unsigned');
+  const trustedDevices: Record<string, string> = {};
+  for (const t of argAll(rest, '--trust')) {
+    const eq = t.indexOf('=');
+    if (eq < 0) die(`--trust wants id=pubkey-path, got: ${t}`);
+    const id = t.slice(0, eq);
+    if (!id) die(`--trust wants id=pubkey-path, got: ${t}`);
+    try {
+      trustedDevices[id] = readFileSync(t.slice(eq + 1), 'utf8').trim();
+    } catch {
+      die(`cannot read pubkey for --trust ${id}: ${t.slice(eq + 1)}`);
+    }
+  }
+  if (Object.keys(trustedDevices).length === 0 && !unsigned) {
+    die('serve needs --trust <id=pub.pem> or --unsigned for an open relay');
+  }
+  const server = new WsRelayServer({ port, file, trustedDevices, allowUnsigned: unsigned });
+  const actual = await server.start();
+  console.log(`fieldlog relay listening ws://127.0.0.1:${actual} file=${file}`);
+  console.log(`ready port=${actual}`);
+  const stop = () => {
+    server.kill();
+    process.exit(0);
+  };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+  await new Promise(() => {}); // run until killed
+}
+
+async function cmdSync(rest: string[]): Promise<void> {
+  const file = arg(rest, '--file');
+  const relay = arg(rest, '--relay');
+  if (!file || !relay) die(usage());
+  const unsigned = rest.includes('--unsigned');
+  const keyPath = arg(rest, '--key');
+  const asId = arg(rest, '--as');
+  if (!keyPath && !unsigned) die('sync needs --key <priv.pem> --as <device> or --unsigned for unsigned mode');
+  if (keyPath && !asId) die('sync --key needs a matching --as <device>');
+  const privateKeyPem = keyPath ? readFileSync(keyPath, 'utf8').trim() : undefined;
+  const kernel = await createKernel({ file: file as string, deviceId: asId, privateKeyPem });
+  const token = privateKeyPem ? kernel.capToken(privateKeyPem) : undefined;
+  const client = new WsRelayClient(relay as string, token ? { capToken: token } : {});
+  try {
+    const r = await kernel.sync(client);
+    console.log(`sync pushed=${r.pushed} acked=${r.acked} pulled=${r.pulled} applied=${r.applied}`);
+  } finally {
+    client.close();
+    kernel.close();
+  }
+}
+
+async function cmdDemo(): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), 'fieldlog-demo-'));
+  const k1 = generateDeviceKey('device-01');
+  const k2 = generateDeviceKey('device-02');
+  const server = new WsRelayServer({ port: 0, file: join(dir, 'relay.log'), trustedDevices: { 'device-01': k1.publicKeyPem, 'device-02': k2.publicKeyPem } });
+  const port = await server.start();
+  const node1 = await createKernel({ file: join(dir, 'device-01.db'), deviceId: 'device-01', privateKeyPem: k1.privateKeyPem });
+  const node2 = await createKernel({ file: join(dir, 'device-02.db'), deviceId: 'device-02', privateKeyPem: k2.privateKeyPem });
+  const c1 = new WsRelayClient(`ws://127.0.0.1:${port}`, { capToken: node1.capToken(k1.privateKeyPem) });
+  const c2 = new WsRelayClient(`ws://127.0.0.1:${port}`, { capToken: node2.capToken(k2.privateKeyPem) });
+  try {
+    let expected = 0;
+    for (let i = 0; i < 20; i++) {
+      const value = 5000 + i * 250;
+      expected += value;
+      await node1.append({ type: 'entry', value, actor: 'device-01' });
+    }
+    await node1.sync(c1, { trustedDevices: { 'device-02': k2.publicKeyPem } });
+    await node2.sync(c2, { trustedDevices: { 'device-01': k1.publicKeyPem } });
+    const t1 = await node1.query<{ total: number }>(`SELECT SUM(value) AS total FROM entries WHERE voided = 0`);
+    const t2 = await node2.query<{ total: number }>(`SELECT SUM(value) AS total FROM entries WHERE voided = 0`);
+    console.log(`sync: device-01 = ${t1[0].total} | device-02 = ${t2[0].total} | expected = ${expected}`);
+    if (t1[0].total !== expected || t2[0].total !== expected) {
+      console.error(`totals differ: device-01=${t1[0].total} device-02=${t2[0].total} expected=${expected}`);
+      process.exit(1);
+    }
+    console.log('match on both sides, totals agree');
+  } finally {
+    c1.close();
+    c2.close();
+    node1.close();
+    node2.close();
+    server.kill();
+  }
+}
+
+const [cmd, ...rest] = Bun.argv.slice(2);
+if (cmd === 'serve') await cmdServe(rest);
+else if (cmd === 'sync') await cmdSync(rest);
+else if (cmd === 'demo') await cmdDemo();
+else {
+  console.error(usage());
+  process.exit(2);
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "fieldlog",
+  "version": "0.15.0",
+  "description": "Fieldlog — write anywhere, resolve later. Offline-first append-log + SQLite read-model + sync.",
+  "repository": { "type": "git", "url": "git+https://github.com/arfoux/fieldlog.git" },
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "fieldlog": "bin/fieldlog.js"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc -p tsconfig.json",
+    "demo": "bun demo/two-node.ts",
+    "bench:append": "bun bench/bench-append.ts",
+    "bench:query": "bun bench/bench-query.ts",
+    "bench:sync": "bun bench/bench-sync.ts"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "bun-types": "^1.4.1",
+    "typescript": "^7.0.2"
+  }
+}