Skip to content

README.md

Latest commit

 

History

History
98 lines (83 loc) · 7.93 KB

README.md

File metadata and controls

98 lines (83 loc) · 7.93 KB
Raw

CodeFolderSync documentation

This repository owns the CodeFolderSync V3 product, operational contract, and engineering documentation.

V3 is an incompatible replacement for V2. The active CLI imports codefoldersync/src/v3/; src/v2/ is retained only as archived implementation and shared installation code while historical harnesses are retired.

System shape

flowchart LR
  A["Recursive scanner and derived catalog"] --> P["Signed peer checkpoint"]
  P --> H["Local or SSH V3 hub"]
  H --> M["Three-way causal merge"]
  M --> J["Journaled selected working-file apply"]
  J --> A
  T["Populated target"] --> R["Adoption recovery"]
  R --> J
Loading

The synchronized unit is one recursive included namespace. Git repositories are automatically discovered semantic boundaries, not membership records. One authority signs configuration and the one-way adoption barrier. During adoption only the authority can publish. In normal mode every enrolled peer can publish a signed causally based checkpoint.

Non-negotiable invariants

  1. The authority tree is never mutated by target adoption.
  2. A target path is moved to out-of-root recovery before adoption replaces or removes it.
  3. A stable normal-mode byte sequence that loses a causal race remains a visible conflict or retained recovery object.
  4. Immutable objects are SHA-256 addressed and verified on read.
  5. Objects reach durable storage before a signed checkpoint can reference them.
  6. The durable outbox retries the exact event after an unknown response.
  7. The hub rejects a reused event ID with a changed payload.
  8. Target apply force-revalidates the local namespace before mutation.
  9. Symlinks are scanned with lstat and never followed.
  10. Git metadata stays machine-local; default-branch transfer requires matching repository and HEAD context.
  11. Reserved paths, traversal, aliases, mounts, external Git dirs, unsupported objects, corruption, and ambiguous state fail closed.
  12. Automatic object and recovery deletion remains disabled.

Documentation map

Area Document
Components and ownership Architecture
Default-branch and selected-file scope Synchronization policies
Types, manifests, SQLite, identity Data model
Scan, merge, adoption, apply Sync engine
Hub framing and distributed previews Protocol
Outbox, journals, recovery, retention Durability and recovery
Filesystem and trust policy Safety model
Visible and retained conflicts Conflicts
Setup, enrollment, services Installation
Operator workflow Operations
Executable acceptance Acceptance scenarios
Bounded full-folder test storage Full-view storage
Complete archived-folder stress Full-folder stress
Maintainer workflow Development

Source ownership

Source Responsibility
src/product-cli.ts Active V3 CLI, daemon, lifecycle and service gates
src/v3/types.ts Schema/protocol 3 contracts
src/v3/config.ts Authority and peer keys, signed revisions, projections
src/v3/ignore.ts Root ignore compiler and hard exclusions
src/v3/catalog.ts Recursive discovery, scope projection, stable nodes, semantic digest
src/v3/objects.ts Immutable chunks/manifests and materialization
src/v3/state.ts Derived catalog, durable outbox, journals, conflicts
src/v3/hub.ts CAS checkpoints, config authority, barrier and history
src/v3/transport.ts Local adapter and bounded framed SSH process
src/v3/engine.ts Seal, adoption, merge, apply, verify and recovery
src/v3/setup.ts Authority setup and target-local enrollment
src/v3/distributed.ts Resumable multi-machine setup and per-target approval
src/v3/acceptance.ts Witnessed two-run real-snapshot pseudo-fleet execution
src/v3/acceptance-faults.ts Full-corpus crash, move, conflict, outage, corruption, and native I/O scenarios
src/v3/acceptance-reflink.ts Private bounded-volume validation and immutable object seeding
scripts/run_bounded_archived_acceptance.mjs Sequential historical Drive restores and bounded full-tree runner lifecycle
scripts/run_full_folder_stress.mjs Complete archived-folder policy stress and local Git-state proof
src/v3/backup.ts Streaming encrypted capture and portable/platform recovery oracles
src/v3/isolated.ts Three-machine SSH, native service, replay, and timing execution
src/v3/visibility.ts Hashed AI path-state observation for controller-owned timing
src/v3/watcher.ts Included-directory native watching and full-scan wakeups
src/v3/restore.ts Witnessed encrypted snapshot restoration into protected masters
src/v3/git-context.ts Committed-tree baselines for independent default-branch advances
test/product.integration.test.ts Focused V3 end-to-end proof

Vocabulary

  • Authority: the only peer allowed to sign configuration, enrollment, ignore, and cutover revisions.
  • Peer: one enrolled machine identity with a target-local private key.
  • Folder: one recursive synchronization namespace with one folder ID.
  • Catalog: rebuildable local observation state; never operator-managed membership.
  • Snapshot: one immutable included namespace manifest and its repository contexts.
  • Sequence: the hub-assigned causal order.
  • Adoption recovery: target-originated evidence displaced before source materialization.
  • Apply recovery: the prior live value moved aside by a normal transaction.

Current proof boundary

Repository tests prove local process-isolated V3 behavior in fresh roots. The repository now contains the executable pseudo-fleet and isolated three-machine runners, but a green build does not claim they ran against the protected masters or real fleet. Google Drive restore, real runner evidence, and daily-driver adoption remain external gates.