Stable & Syncing — a graph of Dark instances that reconcile

[StachuDotNet]

(description is currently AI-gen'd and needs refinement. will do before requesting review)

The goal

Use Dark across all my devices. Each device runs a Dark instance; together they form a graph on my
tailnet that reconciles its package changes. Author a function on the laptop, it shows up on the desktop.
The instances agree on the same code with no central server in the loop.

Two properties make it safe to live in:

• Convergence without blocking. When two machines change the same name, sync doesn't stall — it
  auto-resolves and records the race so I can follow up.
• One answer everywhere. Every machine computes the same winner from a portable authoring time, so the
  graph converges without a coordinator — and a re-pull or full replay reproduces it.
• Resolutions travel too. An explicit override ("keep mine") is a synced Resolution overlaid on the
  op-fold, so peers adopt your choice on their next pull — without inventing a new op.

Foundation 1 — ops ⊥ projections

The op log is the source of truth; everything you see is a projection of it. Every package change (add a
fn, rename, deprecate, propagate) is an op in a branch-scoped, append-only log. The tables you query
(functions/types/values, locations, dependencies) are projections folded from that log;
package_blobs is canonical content, not a projection. rebuildProjections clears the projections, marks
ops unapplied, and re-folds the whole log → byte-identical tables. Surfaced as dark status (ops in the log
vs folded-through — is the cache current?) and dark branch rebuild.

This is what makes sync safe: replicating the op log and re-folding it is the same operation as a local
edit. Losing a projection costs only CPU; the ops are what matter.

Foundation 2 — conflicts are local; only resolutions sync

A sync conflict is a disagreement about the op log — today one kind: a name bound to two contents across
instances (a SetName race). Modeled as SyncConflict (a DU beside PackageOp, one case Divergence of location * candidates). Conflicts are detected locally during the fold and re-derivable — every instance
reaches the same conflicts deterministically, so they never sync. A resolution (which candidate is
chosen, and by whom — auto:<policy> or human, stored as a chosen hash + a resolved-by tag) is the only
thing besides ops that travels.

A runtime "can't proceed" (a missing fn) is not a conflict — it's a RuntimeError. (An earlier
speculative runtime conflict seam was removed; a later PR can add a real one — park-and-write-on-demand,
PDD-style — against an actual requirement.)

Sync

A receiver pulls the ops it hasn't seen (per-peer cursor) and folds them through the same playback path a
local edit uses. Apply is idempotent (INSERT OR IGNORE by content-hash id), so re-pulling is a no-op and
a full replay reproduces the identical projection. Ops fold onto the branch they belong to.

Conflicts & resolutions. A SetName race auto-resolves by choosing whichever op was written later —
each op carries a portable origin_ts authoring time, kept beside the op so its content hash is unchanged;
every instance computes the same winner regardless of arrival order, and an exact tie breaks deterministically
by content hash. The race is recorded, never lost: ack it, or resolve <id> mine|theirs to override.

$ dark conflicts
1 auto-resolved conflict awaiting ack — last-write-wins kept one side, nothing lost:

⚠ Stachu.MyApp.greeting
    last-write-wins → kept theirs   you a1b2c3d4 → them e5f6a7b8 ✓  · from desktop · ack 3f8a92c1

  ack <id> (agree) · ack all · resolve <id> mine|theirs (override)

The conflict report is a pure Dark package (Sync.Display.conflictReport) over structured rows from the
builtin, so the UX is package-testable and iterable without an F# rebuild.

How an override propagates (the subtle part). Sync is incremental — a peer only pulls above its cursor.
So an override can't just re-emit the original SetName: that op is content-addressed, so re-emitting
produces the same op id and a peer that already pulled it sees no change. The fix is to not make it an op
at all. An override is a Resolution — a separate synced decision overlaid on the op-fold, carrying a fresh
stamp; the effective binding is fold(ops) then apply resolutions per location (last-resolver wins). It
rides its own channel (a resolutions table + cursor + wire codec, on both transports) and syncs immediately
(published when made, not gated by commit). So a re-pulling peer adopts it and re-binds. (This replaces the
earlier OverrideName op, which existed only to manufacture a distinct hash; removed.)

Transport — two carriers; the reconciler doesn't care which:

• File — dark sync pull <peer's data.db>. Direct, offline, no server.
• HTTP over Tailscale — a peer serves /sync/{events,blobs,resolutions,health}; the client pulls the
  delta since its cursor. Trust model: machines on the tailnet are trusted (identity = the
  Tailscale-User-Login header, the tailnet is the boundary; httpClientGetUnsafe relaxes SSRF only for
  that). MagicDNS + TLS for free. (A public hub with bearer auth is designed-for, out of scope here.)

Every op kind rides sync. applyOp has no wildcard, so the compiler forces every PackageOp kind to be
folded on the receiver; opsSince ships every kind; the wire frames the raw blob byte-exact. A propagation
rides as its companion SetName ops, so dependents repoint too.

Stable — your work survives upgrades

Syncing is only safe to live in if your data survives the system changing under you.

• Durable-canon. A schema change used to kill-and-fill — drop every table, your op log included
  (fine for a seeded dev box, fatal for real work). Now it drops only the regenerable projections and
  re-folds the surviving log; the canonical op log / blobs / branch+commit state come through identical.
  The line between "a neat demo" and "I can keep my life here."
• One Release coordinate. The op-format/wire version is surfaced in /sync/health (release=N; ops=M) —
  the single version that gates cross-instance sync.
• Version-skew UX. A peer on a different Release fails closed (the wire rejects a mismatched batch,
  never corrupts); dark sync check says it plainly — " is on Release N, you're on M — upgrade
  " — instead of a raw decode error.
• Release migrator (LibDB/Releases.fs). One coordinate gates upgrades and cross-instance sync, with a
  boot guard: a newer-Release store is refused, an older one migrated forward, a fresh one stamped current. A
  step is either data-preserving (copy-and-swap SQL + optional op re-serialize + a projection re-fold) or a
  clean-break boundary that rebuilds the package dataset from source / a same-Release peer. This is the seam
  we grow into "port your state from alpha1 → alpha2."

Also landed:

• Meaning-stable hashing. Content hashes are over an alpha-normalized canonical form, so bound-variable
  names don't affect identity — fn add x y and fn add a b are the same item; argument use, binder order,
  and shadowing stay distinct. Identity is stable across a rename or an op-format change, so sync sees no
  phantom divergences.
• Sync as a managed app. The autosync daemon is a first-class dark apps entry (apps start sync,
  apps enable sync for start-at-boot), observable and lifecycle-managed like any other app, with structured
  per-cycle telemetry via dark sync events.

What's coming (the foundation is built to grow)

• MoveItem / MoveModule — reorganize the namespace; folds through the same locations machinery as
  SetName. New conflict CMoveCollision.
• Long-lived mutable package values — a stable identity whose content updates over time (config, counters,
  the stuff you keep across devices). New conflict CValueUpdateRace.
• Constraints as conflicts — an orphaning rename, a signature shadow, an ACL change on merge
  (CCapabilityDenied) — routed through the same spine. A new kind is ~four touches, no migration.

Status

• Works. Ran end-to-end against local instances — author here, reconcile there; conflicts
  auto-resolve and overrides propagate.
• Not yet tested across physical computers over the tailnet — next.
• Needs PR tightening before merge (consolidation, naming, dead-code sweep).
• Builds on already-merged pre-work, not a re-implementation.