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.

4.4 KiB Raw Blame History