docs: define sync conflict semantics

docs/architecture.md

@@ -185,6 +185,9 @@ Resource kinds:
 
 ## Module Overview
 
+The current per-resource sync and conflict behavior is a documented
+automation-facing contract in [`conflict-semantics.md`](conflict-semantics.md).
+
 `geth-cas` is implemented locally first using BLAKE3 hashes and filesystem blob
 storage. Local pin/unpin metadata is tracked in SQLite and surfaced in
 `cas list`. `cas cleanup` removes unpinned local blobs while retaining pinned

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.

docs/production-readiness-roadmap.md

@@ -221,12 +221,12 @@ Goal: make convergence and failure behavior predictable enough for automation.
   - `[ ]` Tests cover partial stream failure.
   - `[ ]` Tests cover duplicate records and stale cursors.
 
-- `[ ]` Define per-resource conflict semantics.
+- `[x]` Define per-resource conflict semantics.
   Acceptance criteria:
-  - `[ ]` CAS/file-root conflict semantics are documented and tested.
-  - `[ ]` KV conflict semantics are documented and tested.
-  - `[ ]` Document merge semantics are documented and tested.
-  - `[ ]` DB change application limits are documented and tested.
+  - `[x]` CAS/file-root conflict semantics are documented and tested.
+  - `[x]` KV conflict semantics are documented and tested.
+  - `[x]` Document merge semantics are documented and tested.
+  - `[x]` DB change application limits are documented and tested.
 
 - `[ ]` Add live-sync retry and backoff policy.
   Acceptance criteria: