101 lines
4.4 KiB
Markdown
101 lines
4.4 KiB
Markdown
# 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.
|