geth/docs/roadmap.md

# Roadmap

This roadmap is intended to be checkable. Each item should either be completed
with tests/docs or split into smaller items before implementation.

Status markers:

- `[ ]` Not started
- `[~]` In progress
- `[x]` Done

## Phase 0: Bootstrap

Goal: establish a compiling single-binary local runtime with local state, local
control, local CAS, service installation, and written architecture decisions.

- `[x]` Single `geth` binary with daemon and control modes.
  Acceptance criteria:
  - `cargo run -p geth -- init` initializes a temp `GETH_HOME`.
  - `cargo run -p geth -- daemon run` starts one local daemon.
  - No `gethd` or `gethctl` binaries exist in the workspace.

- `[x]` Local daemon control socket.
  Acceptance criteria:
  - Control request/response types roundtrip through JSONL serialization.
  - `geth status` and `geth node id` talk to a running daemon.
  - Control decoding treats input as untrusted and returns structured errors.

- `[x]` Local metadata store and identity.
  Acceptance criteria:
  - SQLite migrations are idempotent.
  - Agent identity persists across repeated opens of the same `GETH_HOME`.
  - Store schema includes resources, auth/keychain logs, CAS, peers, modules,
    SSH cert requests, certificates, and revocations.

- `[x]` Local filesystem CAS.
  Acceptance criteria:
  - `geth cas add/hash/has/get/list` work through the daemon.
  - Blob paths use BLAKE3 hashes under `cas/blobs/<aa>/<bb>/<hash>`.
  - Unit or integration tests verify bytes roundtrip unchanged.

- `[x]` User service installer.
  Acceptance criteria:
  - `geth daemon service print --manager systemd|launchd|windows-task` prints
    the expected user-level service definition or command.
  - Linux install targets a systemd user unit, not a system service.
  - macOS install targets a launchd user agent.
  - Windows install targets a per-user scheduled task.
  - Tests verify generated definitions do not target privileged system services.

- `[x]` Bootstrap docs and ADRs.
  Acceptance criteria:
  - README explains what geth is and what it is not.
  - Architecture docs state Iroh-only remote communication and SSH trust role.
  - ADRs cover single binary, Iroh-only transport, resources, auth, SSH, CAS,
    synchronized structures, service installation, and SSH certificate flows.

## Phase 1: Iroh Foundation

Goal: make the daemon own a real Iroh endpoint and establish authenticated
geth-to-geth connections without granting trust from discovery alone.

- `[x]` Pin and compile Iroh dependencies.
  Acceptance criteria:
  - `iroh` is added only after APIs are pinned and `cargo check --workspace`
    passes.
  - `geth-iroh` exposes endpoint startup/shutdown wrappers.
  - Docs note exact crate versions and any API assumptions.

- `[x]` Daemon-owned Iroh endpoint.
  Acceptance criteria:
  - The daemon creates one shared Iroh endpoint on startup.
  - `geth status --json` reports endpoint status and EndpointID.
  - Endpoint identity is bound to agent/node identity in local metadata.
  - Restarting the daemon preserves higher-level node identity.

- `[x]` Built-in relay policy and configuration.
  Acceptance criteria:
  - Config can select disabled, default Iroh relays, and staging relays.
  - The intended product default uses relays unless explicitly disabled.
  - `geth status --json` reports the selected relay mode.
  - Tests cover config parsing and endpoint builder relay-mode selection.

- `[x]` Custom relay maps.
  Acceptance criteria:
  - Config can define and select named custom relay maps.
  - Invalid relay URLs fail config validation with clear errors.
  - Status output identifies the selected custom relay map without exposing
    unrelated config.

- `[x]` Iroh LAN address discovery.
  Acceptance criteria:
  - Config can enable or disable Iroh local-network discovery.
  - The daemon registers Iroh's local mDNS-like discovery service when enabled.
  - `geth status --json` reports whether local-network discovery is enabled.

- `[x]` Signed peer-card LAN discovery payloads.
  Acceptance criteria:
  - `[x]` Manual `geth peer export/import/list` can exchange signed peer cards
    and store them as untrusted candidates.
  - `[x]` Exported daemon peer cards include Iroh EndpointID plus available
    relay/direct address candidates.
  - `[x]` The daemon can advertise and discover signed geth peer cards over LAN
    discovery.
  - `[x]` Imported peer cards are stored only as untrusted peer candidates.
  - `[x]` Discovered EndpointIDs do not grant module access without keychain/auth
    validation.

- `[x]` Protocol/router scaffold.
  Acceptance criteria:
  - ALPN constants are registered through one module router.
  - Unknown ALPNs are rejected explicitly.
  - Tests cover registration collisions and unknown protocol handling.

- `[x]` Peer cards.
  Acceptance criteria:
  - A peer card contains node ID, agent ID, endpoint candidates, timestamp, and
    signature metadata.
  - Peer-card signatures cover deterministic canonical payloads and reject
    tampered endpoint candidates.
  - Peer cards are stored in `peer_cards`.
  - Invalid or unsigned peer cards do not update trust state.

- `[x]` Untrusted discovery backend trait.
  Acceptance criteria:
  - Discovery returns candidate peer cards only.
  - No discovery result grants capabilities or trust.
  - `auth explain` can distinguish "discovered" from "trusted".

- `[x]` Basic authenticated peer connection.
  Acceptance criteria:
  - `[x]` `geth peer ping <node-id>` dials another node over Iroh using an
    imported signed peer card.
  - `[x]` The remote side validates the caller's signed peer card and stores it
    as a candidate only.
  - `[x]` The ping response records negotiated ALPN and remote endpoint
    identity.
  - `[x]` The remote side proves an agent/node binding before protected module
    access.
  - `[x]` Protected module handlers reject requests that only know an
    EndpointID and lack resource capabilities.

- `[x]` Authorized sync status summary.
  Acceptance criteria:
  - `[x]` The daemon can ask an imported peer for sync stream watermarks over
    the protected Iroh control ALPN.
  - `[x]` The serving peer validates the caller's signed peer card against the
    observed Iroh EndpointID before returning watermarks.
  - `[x]` The serving peer only includes streams where the caller already has
    the relevant resource capability.
  - `[x]` Background live-sync skips per-module pulls when the authorized remote
    watermark has not advanced.
  - `[x]` `geth sync status` reports last local attempt, success, cursor,
    import/rejection counts, and error for each recorded peer stream.
  - `[x]` `geth sync now [node]` triggers the same best-effort sync pass that
    background live sync uses.
  - `[x]` Tests verify unauthorized streams are omitted from summary output.
  - `[x]` Tests verify persisted stream health is exposed in local sync status.

## Phase 2: Trust And Authorization

Goal: replace stubs with signed, reducible keychain/auth operation logs and
resource-scoped capability decisions.

- `[x]` Canonical signed operation envelope.
  Acceptance criteria:
  - Keychain and auth ops use deterministic canonical encoding for signatures.
  - JSON is not used as the signed representation.
  - Tests verify equivalent operations hash/sign identically across runs.

- `[~]` SSH-admin-rooted keychain initialization.
  Acceptance criteria:
  - `[x]` `geth keychain init` records a local `KeychainInit`.
  - `[x]` `geth keychain init --admin-key <path>` records an admin SSH public
    key fingerprint.
  - `[x]` `geth keychain status` reports the reduced local keychain view.
  - `[x]` `geth keychain init --signing-key <path>` signs recorded keychain ops
    with `ssh-keygen -Y sign`.
  - `[x]` OpenSSH keychain signatures use the explicit
    `geth.keychain.v1@geth.local` namespace.
  - `[x]` Keychain OpenSSH signatures are stored in local SQLite.
  - `[x]` `geth keychain status` reports the stored keychain signature count.
  - `[x]` `geth keychain status` verifies stored keychain signatures against
    canonical payloads with OpenSSH when public key material is available.
  - `[x]` Missing `ssh-keygen` or unavailable hardware keys produce clear
    errors during signing.
  - `[x]` Tests cover signed keychain init with a generated local OpenSSH key
    when `ssh-keygen` is available.
  - `[x]` Tests cover local OpenSSH verification of stored keychain signatures.
  - `[x]` `geth init --admin-key --signing-key --node-name` records signed
    owner/user/device/node/agent binding operations.
  - `[x]` `geth node list/rename/revoke` operate on the reduced keychain view.
  - `[x]` `geth node rename/revoke` require an admin signing key.
  - `[x]` `geth keychain sync <node>` verifies signatures from currently
    trusted admin keys before accepting keychain ops.
  - `[x]` Keychain live sync advertises and consumes per-peer high-water
    cursors instead of blindly re-requesting the full log on every tick.
  - `[x]` `geth node enroll request` creates an agent-key-signed enrollment
    request with requested node name and capabilities.
  - `[x]` `geth node enroll submit/import/list` moves pending enrollment
    requests over Iroh or JSON file for owner review.
  - `[x]` `geth node enroll approve --signing-key` records signed keychain ops
    for device/node/agent/endpoint enrollment.
  - `[x]` `geth node enroll sync <owner-node>` pulls approved signed keychain
    and auth state onto the requesting node.
  - `[x]` `geth node endpoint-add/revoke --signing-key` records signed endpoint
    rotation operations.

- `[x]` Keychain operation reducer.
  Acceptance criteria:
  - Admin keys, users, devices, nodes, agents, and endpoint bindings reduce into
    a current keychain view.
  - Revoked keys/devices/nodes are excluded from active views.
  - Tests cover add, rename, revoke, and endpoint rotation.

- `[x]` Node capability management.
  Acceptance criteria:
  - `[x]` `geth node grant <node> <resource> <capability>` records a
    signed resource-scoped capability grant for a known node.
  - `[x]` `geth node revoke-grant <resource> <grant-id>` records grant
    revocation as a signed auth op.
  - `[x]` Node names can be used for management commands where the keychain view
    has a unique active node name.
  - `[x]` Enrollment approval signs capability grants as auth ops.
  - `[x]` `geth auth sync <node>` imports only auth ops signed by currently
    trusted admin keys.
  - `[x]` Auth live sync advertises and consumes per-peer high-water cursors
    instead of blindly re-requesting the full log on every tick.
  - `[x]` `geth auth grant/revoke --signing-key` records signed auth ops.

- `[x]` Resource auth operation reducer.
  Acceptance criteria:
  - Resource create, authority set, grants, revocations, and groups reduce into
    a current permission view.
  - Capabilities are strings, including scoped forms such as
    `kv.write_prefix:apps/foo/`.
  - Tests cover grant, revoke, group membership, and denied access.

- `[~]` `auth explain` real decision path.
  Acceptance criteria:
  - `[x]` `geth auth grant` and `geth auth revoke` persist signed local auth
    ops when run through the CLI.
  - `[x]` `geth auth explain <subject> <resource> <capability>` reports
    allowed/denied from the local auth-op reducer when local ops exist.
  - `[x]` Output includes the grant ID or missing grant that caused the result.
  - `[x]` JSON output is stable enough for tests and scripts.
  - `[x]` Replicated auth sync requires trusted-admin signatures before import.

- `[~]` Resource secrets and bearer invites.
  Acceptance criteria:
  - `[x]` `geth secret create <resource>` records resource secret epoch 1
    metadata.
  - `[x]` `geth secret rotate <resource>` records the next resource secret
    epoch.
  - `[x]` Secret epoch rotation is represented in durable metadata.
  - `[x]` Bearer secrets grant only resource-scoped capabilities.
  - `[x]` Bearer principals cannot mutate trust graph state by default.
  - `[x]` Tests verify bearer access does not imply node identity.
  - `[x]` `geth secret bearer challenge/prove/verify` exercises
    resource-scoped bearer challenge-response proofs.
  - `[x]` Tests verify valid bearer proofs and capability-scoped proof denial.
  - `[x]` Remote module authorization paths accept optional bearer proofs for
    the requested resource capability without granting node identity.
  - `[x]` Tests verify remote CAS fetch succeeds through a bearer proof before
    the caller has a node grant.
  - `[x]` Bearer creation separates the persisted public bearer id from the
    private bearer token returned to the caller.
  - `[x]` Bearer list/revoke operate on public bearer ids while proof and remote
    authorization use the private token.
  - `[x]` Tests verify the public bearer id differs from the private token and
    remote bearer auth uses the token.

- `[~]` SSH certificate and revocation lifecycle.
  Acceptance criteria:
  - `[x]` `geth ssh cert request/requests/approve/import/list` persist local
    metadata.
  - `[x]` Approval emits an explicit `ssh-keygen -s ...` command for
    CA/YubiKey use.
  - `[x]` `geth ssh cert approve --sign` can run `ssh-keygen`, import the
    resulting OpenSSH certificate, and mark the request signed.
  - `[x]` Tests cover signing with a generated local OpenSSH CA key when
    `ssh-keygen` is available.
  - `[x]` `geth ssh revocation add/list/export` persists and exports
    revocations.
  - `[x]` Revocations can be exported as JSONL and OpenSSH KRL specification
    text or as a binary OpenSSH KRL through `ssh-keygen`.
  - `[x]` Authorized peers can pull SSH cert-flow metadata with
    `geth ssh cert sync <node-id>`.
  - `[x]` Authorized peers can pull SSH revocation metadata with
    `geth ssh revocation sync <node-id>`.
  - `[x]` The daemon background live-sync loop refreshes known peers without a
    manual command.
  - `[x]` Background live-sync can be disabled or retuned with `[sync]`
    `live_sync_enabled` and `live_sync_interval_ms`.
  - `[x]` SSH metadata live-sync stores per-peer high-water cursors in
    `module_state` and requests only records at or beyond the cursor.
  - `[x]` Local SSH cert request/read/approve/import commands can enforce
    `ssh_cert.request`, `ssh_cert.read`, `ssh_cert.approve`, and
    `ssh_cert.import` for explicit non-owner `--subject` principals.
  - `[x]` Local SSH revocation publish/read/import commands can enforce
    `ssh_revocation.publish`, `ssh_revocation.read`, and
    `ssh_revocation.import` for explicit non-owner `--subject` principals.
  - `[x]` Tests cover denied and granted non-owner local SSH cert request and
    revocation publish flows.
  - `[x]` Sync import rejects conflicting certificate request, certificate, and
    revocation records with ids that already exist locally.
  - `[x]` Tests verify conflicting SSH cert request and revocation records do
    not overwrite local metadata.
  - `[x]` Accepted SSH cert/revocation records carry agent-key signed
    provenance over deterministic canonical payloads.
  - `[x]` Sync import rejects unsigned or invalidly signed cert-flow and
    revocation records that are not already-known conflicting ids.

## Phase 3: CAS, KV, And Pubsub

Goal: turn local CAS and stubs into Iroh-backed replicated modules while keeping
authorization and durable-state boundaries clear.

- `[~]` Iroh-blobs CAS integration.
  Acceptance criteria:
  - `[x]` `geth cas fetch <node-id> <hash>` can fetch a blob from an imported
    peer over the daemon-owned Iroh control ALPN.
  - `[x]` The serving peer validates the caller's signed peer card against the
    observed Iroh EndpointID before considering authorization.
  - `[x]` Remote CAS fetch requires `cas.fetch` on `resource:cas:local`.
  - `[x]` The requester verifies returned bytes against the requested BLAKE3
    CAS hash before storing them locally.
  - `[x]` Local add/get/hash/has/list behavior remains backward compatible.
  - `[x]` Successful fetches record the serving peer as a local provider for
    the CAS hash.
  - `[x]` `geth cas providers <hash>` lists locally known providers.
  - `[x]` Tests cover local provider metadata storage.
  - `[ ]` Replace the bootstrap control-ALPN transfer with `iroh-blobs`
    provider/fetch behavior.

- `[x]` CAS pin and cache policy.
  Acceptance criteria:
  - `[x]` `geth cas pin <hash>` persists local pin metadata.
  - `[x]` `geth cas unpin <hash>` removes local pin metadata.
  - `[x]` `geth cas list` reports pinned versus unpinned blobs.
  - `[x]` Pinned blobs are retained across cache cleanup.
  - `[x]` Unpinned cached blobs can be evicted by policy.
  - `[x]` Tests cover attempted eviction of pinned data.

- `[x]` Encrypted private blobs.
  Acceptance criteria:
  - `[x]` `geth cas add-private <resource> <path>` stores an encrypted CAS
    envelope instead of plaintext payload bytes.
  - `[x]` `geth cas get-private <resource> <hash> --out <path>` decrypts with
    a matching local resource secret epoch.
  - `[x]` Access is gated by local resource secret epoch material.
  - `[x]` Tests verify encrypted blob roundtrip and wrong resource/secret
    rejection.
  - `[x]` Docs explicitly avoid claiming forward secrecy or PCS.

- `[~]` Iroh-docs KV integration.
  Acceptance criteria:
  - `[x]` `geth kv create/set/get` works against a named local KV resource.
  - `[x]` KV metadata and entries are durable in the local SQLite store.
  - `[x]` The auth evaluator allows `kv.write_prefix:<prefix>` grants to
    satisfy matching `kv.write_key:<key>` requests.
  - `[x]` Tests cover allowed and denied prefix-scoped KV write explanations.
  - `[x]` `geth kv set --subject <principal>` enforces local capability
    decisions for non-local test callers.
  - `[x]` `geth kv sync <node-id> <name>` pulls authorized updates from an
    imported peer over Iroh.
  - `[x]` Remote KV sync requires `kv.read` on `resource:kv:<name>`.
  - `[x]` Background live-sync refreshes local KV stores from known peers using
    per-peer/per-KV high-water cursors.
  - `[ ]` KV metadata is replicated through Iroh Documents.

- `[~]` Iroh-gossip pubsub integration.
  Acceptance criteria:
  - `[x]` `geth pubsub pub/sub` works against the local daemon.
  - `[x]` Local pubsub messages are kept in a bounded daemon-lifetime ring
    buffer.
  - `[x]` Pubsub messages are documented and tested as lossy notifications, not
    durable facts.
  - `[x]` `geth pubsub pub <topic> <message> --node <node-id>` publishes to an
    imported peer over Iroh.
  - `[x]` Remote pubsub publish requires `pubsub.publish` on
    `resource:pubsub:<topic>`.
  - `[x]` `geth pubsub sub <topic> --node <node-id>` reads an authorized peer
    snapshot over Iroh.
  - `[x]` Remote pubsub subscribe requires `pubsub.subscribe` on
    `resource:pubsub:<topic>`.
  - `[x]` Tests cover denied and allowed remote pubsub subscribe.
  - `[ ]` Replace bootstrap remote publish with iroh-gossip topics.
  - `[x]` Docs and tests keep durable state in CAS/KV/document/db instead.

## Phase 4: Pipes, SSH Proxy, And SSH Distribution

Goal: add authorized stream-oriented management workflows over Iroh.

- `[~]` Dumbpipe-style Iroh streams.
  Acceptance criteria:
  - `[x]` `geth pipe listen/connect` works against a local daemon-lifetime
    registry.
  - `[x]` Tests cover local listener registration, local connect matching, and
    daemon restart behavior.
  - `[x]` `geth pipe connect <name> --node <node-id>` can connect to an
    imported peer over Iroh at the control-plane level.
  - `[x]` Remote pipe connect requires `pipe.connect` on
    `resource:pipe:<name>`.
  - `[x]` `geth pipe listen <name> --node <node-id>` can register an authorized
    daemon-lifetime listener on an imported peer.
  - `[x]` Remote pipe listen requires `pipe.listen` on
    `resource:pipe:<name>`.
  - `[x]` Tests cover denied and allowed remote listener registration.
  - `[x]` `geth pipe send <name> [message|--in <path>|--in -] --node <node-id>`
    carries a byte message over the dedicated `/geth/pipe/1` Iroh ALPN.
  - `[x]` `geth pipe recv <name>` drains daemon-lifetime pipe messages.
  - `[x]` Remote pipe send requires `pipe.connect` on
    `resource:pipe:<name>`.
  - `[x]` TCP forwarding carries bidirectional byte streams over Iroh.
  - `[x]` TCP streams close cleanly and propagate errors through the local
    forwarder logs.

- `[~]` TCP forwarding.
  Acceptance criteria:
  - `[x]` A local loopback TCP listener can forward over an authorized Iroh
    pipe with `geth pipe forward-tcp`.
  - `[x]` The remote side connects only to explicit loopback socket addresses
    in the prototype.
  - `[x]` Forwarding is resource-scoped with `pipe.forward` on
    `resource:pipe-tcp:<target>`.
  - `[x]` Tests cover address validation and TCP pipe wire
    request/response serialization.
  - `[x]` A conditional two-node integration test covers a TCP
    request/response forwarding exchange when local Iroh endpoint binding is
    available in the test environment.

- `[~]` Unix socket forwarding where supported.
  Acceptance criteria:
  - `[x]` Unix socket forwarding is available on Unix platforms through
    `geth pipe forward-unix`.
  - `[x]` Forwarding is resource-scoped with `pipe.forward` on
    `resource:pipe-unix:<target>`.
  - `[x]` Unix socket paths must be absolute and reject parent-directory
    components.
  - `[x]` Tests cover Unix path validation and pipe wire request serialization.
  - `[ ]` Unsupported platforms return clear errors.
  - `[x]` Tests cover a full two-node Unix socket forwarding exchange.

- `[x]` SSH proxy over Iroh.
  Acceptance criteria:
  - `[x]` `geth ssh proxy <node>` contacts an imported peer over the dedicated
    `/geth/ssh-proxy/1` Iroh ALPN.
  - `[x]` Remote daemon checks `ssh_proxy.connect` on
    `resource:ssh-proxy:local` before returning proxy connection metadata.
  - `[x]` Tests cover denied and granted SSH proxy control-plane attempts.
  - `[x]` Knowing an EndpointID alone cannot reach sshd.
  - `[x]` The proxy opens a dedicated authorized Iroh byte stream.
  - `[x]` Remote daemon connects that stream to local sshd at `127.0.0.1:22`
    only after authorization.
  - `[x]` Future completion adds a restricted built-in geth admin shell option.

- `[~]` SSH certificate and revocation distribution.
  Acceptance criteria:
  - `[x]` Cert request and imported certificate records can be pulled from an
    imported peer over Iroh.
  - `[x]` Revocation records can be pulled from an imported peer over Iroh.
  - `[x]` Remote sync validates the caller's signed peer card against the
    observed Iroh EndpointID before considering authorization.
  - `[x]` Cert metadata sync requires `ssh_cert.sync` on `resource:ssh:certs`.
  - `[x]` Revocation metadata sync requires `ssh_revocation.sync` on
    `resource:ssh:revocations`.
  - `[x]` Consumers can list current certs/revocations from local state while
    offline after sync.
  - `[x]` Background live-sync uses the same protected Iroh path and cursor
    state as manual sync.
  - `[ ]` Replace pull-only metadata sync with a resource log or CRDT model.
  - `[x]` Conflicting records with already-known ids are rejected during import
    rather than replacing local metadata.
  - `[x]` Unsigned records are rejected during sync import once signed
    provenance is part of the metadata format.

- `[x]` OpenSSH KRL import/export.
  Acceptance criteria:
  - `[x]` Revocation records can produce an OpenSSH KRL specification file.
  - `[x]` Tests cover serial, key ID, and public key revocation spec lines.
  - `[x]` Revocation records can produce an OpenSSH binary KRL file.
  - `[x]` Tests cover binary KRL export for public-key revocations when
    `ssh-keygen` is available.
  - `[x]` JSONL exports and OpenSSH KRL specification source files can be
    imported into revocation metadata.
  - `[x]` Binary OpenSSH KRL import returns a clear unsupported message because
    KRL files are not enumerable through OpenSSH tooling.
  - `[x]` Tests cover JSONL and KRL-spec import.
  - `[x]` Tests cover certificate revocations.

## Phase 5: DB And Documents

Goal: add durable synchronized data structures for SQLite/cr-sqlite and
Automerge documents.

- `[x]` DB resource registration.
  Acceptance criteria:
  - `geth db add <name> <path>` records DB metadata.
  - `geth db status <name>` reports local path, schema metadata, and sync state.
  - Nonexistent paths and invalid names produce clear errors.

- `[x]` cr-sqlite change extraction.
  Acceptance criteria:
  - `[x]` DB status detects whether `crsql_changes` exists.
  - `[x]` DB status reports `crsql_changes` row count, columns, and max
    `db_version` when available.
  - `[x]` Tests use a temp SQLite DB and deterministic fixture changes.
  - `[x]` The module can extract typed change batches from `crsql_changes`.
  - `[x]` Schema hash/version metadata is included in extracted change batches.
  - `[x]` Extracted batches are exposed through `geth db changes`.

- `[~]` DB sync over Iroh.
  Acceptance criteria:
  - `[x]` `geth db sync <node-id> <name>` exists and talks to the daemon.
  - `[x]` Remote DB sync uses the protected Iroh control ALPN.
  - `[x]` The serving peer validates the caller's signed peer card against the
    observed Iroh EndpointID before considering authorization.
  - `[x]` Remote DB sync requires `db.sync` on the remote
    `resource:db:<name>`.
  - `[x]` The response carries typed `crsql_changes` batches plus schema
    metadata.
  - `[x]` The requester detects schema mismatch before advancing the sync
    cursor.
  - `[x]` Background live-sync runs DB sync for local DB resources and known
    peers.
  - `[x]` Per-peer/per-DB high-water cursors are stored in `module_state`.
  - `[x]` Extracted batches are exposed through `geth db changes`.
  - `[x]` Compatible remote batches are inserted into the local
    `crsql_changes` table or view before advancing the cursor.
  - `[x]` Tests cover typed batch application into deterministic fixture
    `crsql_changes` tables.
  - `[ ]` Add an integration test with a real cr-sqlite-enabled SQLite DB that
    proves two local test nodes exchange and apply changes.
  - `[ ]` Optional CAS-backed snapshots or batches are documented if used.

- `[~]` Automerge document resource.
  Acceptance criteria:
  - `[x]` `geth document create/status` works for local documents.
  - `[x]` Document metadata and empty JSON state are stored durably.
  - `[x]` `geth document set/get` stores and returns validated local JSON
    state.
  - `[x]` Tests cover create, update, save, and reload of local JSON document
    state.
  - `[x]` `geth document sync <node-id> <name>` pulls authorized JSON state
    from an imported peer over Iroh.
  - `[x]` Background live-sync refreshes local JSON documents from known peers
    using per-peer/per-document cursors.
  - `[ ]` Automerge document state is stored durably.
  - `[ ]` Tests cover Automerge create, update, save, and reload.

- `[ ]` Automerge sync over Iroh.
  Acceptance criteria:
  - `[x]` Bootstrap JSON last-writer-wins sync works across two local test
    nodes over Iroh.
  - Resource authorization gates read/write sync.
  - Conflicts converge according to Automerge semantics.

## Phase 6: File Sync And Advanced Local-First Auth

Goal: build higher-level local-first collaboration on CAS trees, resource auth,
and future group key evolution.

- `[x]` CAS tree objects.
  Acceptance criteria:
  - `[x]` Tree objects describe directories, files, executable bits, and blob
    hashes.
  - `[x]` Tree objects are content-addressed and stored in CAS.
  - `[x]` Tests cover deterministic tree hashing.

- `[~]` File roots.
  Acceptance criteria:
  - `[x]` A file root maps a local path to a CAS tree resource.
  - `[x]` `geth cas root add/list/scan` persists local root metadata and latest
    tree state.
  - `[x]` Scan detects create/update/delete/rename changes.
  - `[x]` Scan output documents that geth never overwrites file roots without a
    recorded future sync decision.
  - `[x]` `geth cas root sync <node-id> <name>` pulls authorized remote
    file-root tree metadata over the protected Iroh control path.
  - `[x]` Remote file-root sync requires `cas.fetch` on
    `resource:cas-tree:<name>`.
  - `[x]` Sync imports CAS tree bytes and records a peer-qualified remote root
    with path `remote:<node>:<name>` without writing files into the working tree
    or overwriting same-named local roots.
  - `[x]` Background live-sync imports updated authorized file-root trees from
    sync-status `cas-tree:<name>` watermarks and stores per-peer cursors.
  - `[x]` `geth cas root apply <root> --to <path>` materializes missing files
    and directories from a CAS tree without deleting extras or overwriting local
    edits.
  - `[x]` Apply records durable conflicts for differing local paths.
  - `[ ]` Future completion adds a richer three-way apply using base/local/remote
    trees for automatic safe updates and deletes.

- `[x]` Conflict handling.
  Acceptance criteria:
  - `[x]` Conflicts are represented as durable metadata.
  - `[x]` CLI/control can record, list, and choose a resolution for local
    conflict metadata.
  - `[x]` Tests cover local concurrent edit conflict record/list/resolve.
  - `[x]` Future sync records conflicts automatically from base/local/remote
    tree comparisons.
  - `[x]` Tests cover automatic concurrent edit, delete/edit, and rename
    conflict detection.

- `[ ]` Keyhive-like convergent capabilities.
  Acceptance criteria:
  - Capability state is represented as local-first replicated auth data.
  - Convergent grant/revoke semantics are documented and tested.
  - Migration from current auth ops is documented.

- `[ ]` BeeKEM/CGKA-inspired group key evolution.
  Acceptance criteria:
  - Design doc states exact security properties and non-properties.
  - Prototype is behind explicit experimental module boundaries.
  - Current resource secret epoch model remains compatible or has a migration.