IF Commons GitHub

AnyFS Bridge: two-way sync and mirror

0004Active

0004-bridge-twoway · owner if · domain commons

Requirements

FR-001checkpassing

A base MUST be the SHA-256 of each path as the two sides last agreed, kept as pairs in the order of the paths and refused where a path or a digest is not one; a sync MUST be given a base or say seed, which MUST agree on what is equal, copy what is on one side only, leave what differs to the policy and delete nothing.

Enforced (check): .github: cd commons/anyfs-bridge && bun run verify — suite/twoway.test.ts

Proved by: anyfs-bridge/suite/twoway.test.ts

Written in: anyfs-bridge/src/logical/bisync.ts

Tests: passed: suite/twoway.test.ts a base is kept as pairs in the order of the paths, and a pair that is not a path and a dig; passed: suite/twoway.test.ts a sync has no default base: a seed agrees on what is equal, copies what is on one side and

FR-002checkpassing

A path that only one side changed since the base MUST go to the other side, a path both sides changed to the same bytes MUST be agreed, a path both have as the base says MUST be left, and a sync made again after its apply MUST plan nothing.

Enforced (check): .github: cd commons/anyfs-bridge && bun run verify — suite/twoway.test.ts

Proved by: anyfs-bridge/suite/properties.test.ts, anyfs-bridge/suite/twoway.test.ts

Written in: anyfs-bridge/src/logical/bisync.ts

Tests: passed: suite/properties.test.ts a two-way sync of any two trees, seeded, makes them hold the same files, and the next sync; passed: suite/twoway.test.ts a change made on one side goes to the other, a change made on both to the same bytes is ag

FR-003checkpassing

A path both sides changed differently MUST be settled by the policy: newer-wins MUST make the newer the winner where both sides say when they changed it and are not the same time and otherwise MUST leave a conflict; keep-both MUST make the newer (or side a at a tie) the winner and keep the loser's bytes beside it under a name made of the path, the loser's side and eight digits of its digest, at the winner's side, where they reach the other side at the next sync; fail MUST leave every such path as a conflict that keeps what the base said.

Enforced (check): .github: cd commons/anyfs-bridge && bun run verify — suite/twoway.test.ts

Proved by: anyfs-bridge/suite/twoway.test.ts

Written in: anyfs-bridge/src/logical/bisync.ts

Tests: passed: suite/twoway.test.ts a path both sides changed is settled by the policy: the newer wins, both are kept, or it f

FR-004checkpassing

A delete made on one side MUST reach the other within the delete policy and as a skip where deletes are forbidden, and MUST be refused with the number wanted where it is more than the allowance; a path changed on one side and deleted on the other MUST keep the change; and a path whose change did not succeed MUST go back to what the base said.

Enforced (check): .github: cd commons/anyfs-bridge && bun run verify — suite/twoway.test.ts

Proved by: anyfs-bridge/suite/twoway.test.ts

Written in: anyfs-bridge/src/logical/bisync.ts

Tests: passed: suite/twoway.test.ts a delete reaches the other side within the allowance, is left where deletes are forbidden,; passed: suite/twoway.test.ts a path whose change did not reach the other side goes back to what the base said, so that

FR-005checkpassing

A path of a replica MUST be same where the primary and the replica hold the same bytes, diverged where the replica is not what the ledger says it was brought to, and behind otherwise; a replica MUST be in-sync where no path is behind or diverged, behind with the number of paths where some are behind, and diverged with the paths where any is.

Enforced (check): .github: cd commons/anyfs-bridge && bun run verify — suite/twoway.test.ts

Proved by: anyfs-bridge/suite/twoway.test.ts

Written in: anyfs-bridge/src/logical/mirror.ts

Tests: passed: suite/twoway.test.ts a replica is behind until it is converged, and then in sync; a path changed at the replica; passed: suite/twoway.test.ts a path is the same, behind, or diverged, by the bytes of the primary, of the replica and o

FR-006checkpassing

A convergence MUST copy and delete the paths that are behind and MUST NOT touch, merge or overwrite a path that is diverged; MUST delete only within the delete policy; and MUST give the ledger with the bytes each path was brought to, keeping the old entry of a diverged path and of an action that failed.

Enforced (check): .github: cd commons/anyfs-bridge && bun run verify — suite/twoway.test.ts

Proved by: anyfs-bridge/suite/twoway.test.ts

Written in: anyfs-bridge/src/logical/mirror.ts

Tests: passed: suite/twoway.test.ts a replica is behind until it is converged, and then in sync; a path changed at the replica; passed: suite/twoway.test.ts a delete at the primary reaches the replica within the allowance, and is left where delete

FR-007checkpassing

A replica MUST become the primary only as an explicit act that is refused while it is behind unless the caller accepts to lose that many changes and while it is diverged unless the caller accepts the divergence, and that gives the roles swapped with the number of changes that are lost.

Enforced (check): .github: cd commons/anyfs-bridge && bun run verify — suite/twoway.test.ts

Proved by: anyfs-bridge/suite/twoway.test.ts

Written in: anyfs-bridge/src/logical/mirror.ts

Tests: passed: suite/twoway.test.ts a replica becomes the primary only as an explicit act: not while it is behind unless the l

FR-008checkpassing

After a promotion the old primary MUST be a replica of the new one with a ledger of the paths where the two agree, so that whatever it holds that the new primary does not is seen as diverged until a person decides.

Enforced (check): .github: cd commons/anyfs-bridge && bun run verify — suite/twoway.test.ts

Proved by: anyfs-bridge/suite/twoway.test.ts

Written in: anyfs-bridge/src/logical/mirror.ts

Tests: passed: suite/twoway.test.ts after a promotion the old primary is a replica of the new one, and what it holds that the

Acceptance scenarios

  1. Given two sides with no base, When they are seeded, Then what is equal is agreed and what is on one side only is copied, per FR-001.
  2. Given a base, a change at a and another path changed at b, When they are synced, Then each goes to the other side and a second sync plans nothing, per FR-002.
  3. Given a path both sides changed, When the policy is keep-both, Then the newer wins and the other is kept beside it, per FR-003.
  4. Given a path deleted at one side and changed at the other, When they are synced, Then the change is kept, per FR-004.
  5. Given a replica edited by someone else, When it is converged, Then that path is left as it is and named as diverged, per FR-005 and FR-006.
  6. Given a replica that is behind, When it is promoted without accepting the loss, Then it is refused with the number of changes, per FR-007.

Out of scope

  • Merging the contents of two versions of a file; a continuous watcher that runs the convergence.
  • Keeping the base or the ledger: they are values, and the caller keeps them (for example in a collection).

Edge cases

  • A conflict copy is made at the winner's side at once and reaches the other side at the next sync (FR-003).
  • An empty base said out loud is the same as a seed (FR-001).
  • A side that does not say when a file changed leaves a newer-wins conflict as no-time (FR-003).

Assumptions

  • The sides are stores that can be read, listed and written, and their SHA-256 comes from their revisions or from their bytes (0003-bridge-transfer FR-002).

Open questions

  • None.

Key entities

  • Base, Seed, BiPlan, BiAction, Ledger, ReplicaState, Promotion.

Success criteria

SC-001success criterion

Every behaviour is tested over stores in memory and, where it touches a file system, stores in a folder, with no network and no real time.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

AnyFS Bridge: conformance

Titles, headings, exports, tables, columns and requirements. Esc closes.