docs: define sync conflict semantics

docs/conflict-semantics.md

@@ -0,0 +1,101 @@
+# Conflict Semantics
+
+This document describes the current pre-deployment conflict behavior for
+resource sync. It is an automation contract for scripts built on `geth`; it is
+not a claim that every resource has final multi-writer reconciliation.
+
+All remote sync paths first authenticate the peer-card endpoint binding and
+check the resource capability for the requested stream. Discovery metadata,
+peer-card import, or LAN discovery never grants conflict-resolution rights by
+itself.
+
+## CAS File Roots
+
+CAS blobs are immutable and addressed by BLAKE3 hash, so blob fetch has no merge
+conflict. File-root sync and apply are the stateful parts:
+
+- `geth cas root sync <node> <name>` imports authorized remote tree metadata and
+  tree bytes into a peer-qualified remote root. It does not write files.
+- Repeated syncs retain the previous imported remote tree as the base. When a
+  same-named local root and the new remote root both changed, geth records
+  durable `concurrent-edit`, `delete-edit`, or `rename` conflicts.
+- `geth cas root apply <root> --to <path>` is conservative. Without a
+  registered local base it creates missing files/directories, does not delete
+  extra files, and does not overwrite differing local files.
+- With a registered local root base, apply performs a three-way
+  base/local/remote check. It applies non-conflicting creates, updates, deletes,
+  and renames only where local state still matches the base.
+- Ambiguous paths remain local conflict records until resolved through
+  `geth cas conflict resolve`.
+
+The current tests cover CAS tree diffing, safe three-way apply, durable
+file-conflict records, and automatic sync conflict recording.
+
+## KV Stores
+
+Named KV stores are durable local SQLite indexes mirrored through native
+Iroh Documents when available.
+
+- Manual `geth kv sync` and background live-sync require `kv.read` on
+  `resource:kv:<name>`.
+- Import is timestamp-based last-writer-wins per key.
+- A remote value replaces the local value when the remote `updated_at_ms` is
+  greater than or equal to the local timestamp.
+- A remote value older than the local value is ignored.
+- There is no tombstone or multi-value conflict record for KV yet.
+
+The current tests cover authorized KV sync and the timestamp import rule.
+
+## Documents
+
+Document resources persist Automerge save bytes, while the CLI exposes a
+validated JSON view.
+
+- Manual `geth document sync` and background live-sync require `document.read`
+  on `resource:document:<name>`.
+- A remote state older than the local document timestamp is ignored.
+- A remote state newer than the local timestamp replaces the local Automerge
+  state and JSON view.
+- Equal timestamps are merged with the current Automerge merge helper.
+- Rich document conflict UI, semantic JSON merge policy, and per-field conflict
+  reporting are future work.
+
+The current tests cover Automerge merge behavior, authorized document sync, and
+the sync timestamp decision rule.
+
+## DB Resources
+
+DB resources are a staged cr-sqlite path rather than a general SQLite merge
+engine.
+
+- Manual `geth db sync` and background live-sync require `db.sync` on
+  `resource:db:<name>`.
+- The requester compares remote schema metadata with the local DB schema before
+  applying a batch.
+- Compatible batches are inserted into the local `crsql_changes` table or view,
+  then the per-peer cursor advances.
+- Incompatible schema metadata causes the batch to be skipped and the cursor is
+  not advanced for that batch.
+- Loading/configuring the cr-sqlite extension for real application databases is
+  outside this bootstrap.
+
+The current tests cover deterministic `crsql_changes` extraction/application,
+authorized DB sync, and schema-compatible batch application. Schema evolution
+and rollback expectations are tracked in the upgrade-test roadmap item.
+
+## Signed Logs And Metadata Sync
+
+Keychain, auth, SSH certificate, and SSH revocation sync are append-only
+metadata flows with provenance checks.
+
+- New keychain/auth entries must have valid signatures from currently trusted
+  admin keys.
+- SSH certificate and revocation entries must carry valid agent-key signed
+  provenance over canonical payloads.
+- If an incoming record has an already-known id but different content, the
+  import rejects that record instead of overwriting local metadata.
+- Accepted keychain/auth op/signature groups are staged and committed through
+  store batch transactions.
+
+The current tests cover unsigned, invalidly signed, and conflicting signed-log
+imports.