# 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.