IF Commons GitHub

Bridge mirrored store

0006Active

0006-bridge-mirrored · owner if · domain commons

Requirements

FR-001checkpassing

The store of a mirror MUST have exactly the capabilities of its primary, the compiler MUST refuse a primary without the core capabilities (read, write, list, stat, delete), and a store of a primary that has no batch or no cas MUST have neither.

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

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

Written in: anyfs-bridge/src/mirror/mirror.ts, anyfs-bridge/src/mirror/mod.ts

Tests: passed: suite/mirror.test.ts the store has the capabilities of its primary and no other, and the type says so

FR-002checkpassing

A write, a delete, a rename, an append and a batch MUST go to the primary and to no replica, MUST be queued for the replicas, and a settlement MUST bring a replica up to the primary by a plan of the bridge and a second settlement MUST change nothing.

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

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

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

Tests: passed: suite/mirror.test.ts a write goes to the primary and waits; a settlement brings the replica up, and a second on

FR-003checkpassing

A replica that cannot be reached, or that fails in the middle of a settlement, MUST NOT fail a write; it MUST be reported as behind and as not reachable where it could not be reached, what was done before the failure MUST be kept, and a later settlement MUST finish without doing again what was done.

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

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

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

Tests: passed: suite/mirror.test.ts a replica that fails in the middle of a settlement keeps what was done, is behind for the ; passed: suite/mirror.test.ts a replica that fails never fails a write: it is behind, and it catches up once it is back

FR-004checkpassing

A path at a replica that was changed by someone other than the mirror MUST be reported as diverged and MUST NOT be overwritten, merged or deleted, whatever is done to it at the primary, and the paths that are not diverged MUST still be brought up.

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

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

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

Tests: passed: suite/mirror.test.ts a replica changed by someone else is diverged and is left as it is, whatever the primary d

FR-005checkpassing

A read of the store MUST be the primary's answer alone; a read of the mirror MUST answer from a replica only where the policy says so and the primary is unavailable, MUST say that it did and which replica, and MUST say what the replica is known to hold of the path: converged, pending, diverged or unknown.

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

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

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

Tests: passed: suite/mirror.test.ts a read of the store is the primary's alone; a read of the mirror may be answered by a repl

FR-006checkpassing

The ledgers MUST be kept on the primary as typed documents below a reserved prefix, the store MUST NOT list that prefix and MUST refuse every operation on it as outside-scope, a ledger MUST NOT be copied to a replica, a new mirror over the same stores MUST read them, and a ledger that cannot be read MUST be a problem and never an empty ledger.

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

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

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

Tests: passed: suite/mirror.test.ts the ledgers are kept on the primary below a prefix that the store neither lists nor lets b

FR-007checkpassing

The mirror MUST tell each write, each queue, each convergence, each state of a replica that is behind or diverged, each promotion and each degraded read as an event with the time, to listeners and to an iterable that ends when the mirror is closed, and a listener that throws MUST be dropped without affecting the operation.

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

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

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

Tests: passed: suite/mirror.test.ts the events say what happened, in order, to a listener and to an iterable that ends when th

FR-008checkpassing

A replica MUST become the primary only by an explicit call that the bridge allows (not behind and not diverged unless the caller accepts the loss or the divergence), only where it has every capability of the store, and then the old primary MUST become a replica, the ledgers MUST move to the new primary and be taken from the old one, and the other replicas MUST be seen against the new primary by what they share with it.

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

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

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

Tests: passed: suite/mirror.test.ts a replica becomes the primary only as the bridge allows: not behind, not diverged, unless ; passed: suite/mirror.test.ts a replica that lacks a capability of the store is not promoted, and a name that is not a r

FR-009checkpassing

Where the policy says after-write a settlement MUST be started after a write and never waited for by it, settlements started while one runs MUST be combined, and drain MUST wait for those that were started.

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

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

Tests: passed: suite/mirror.test.ts after each write a settlement is started and never waited for, many writes make few, and d

FR-010checkpassing

Of two writes through the store that expect the same revision exactly one MUST succeed, as at the primary, and a mirror MUST end with a replica equal to the primary after writes at once and a settlement.

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

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

Tests: passed: suite/mirror.test.ts writers at once through the store keep the revisions of the primary: of two that expect th

FR-011checkpassing

A mirror MUST work over a store in a folder and a store in memory alike, and a replica that is a folder MUST hold exactly the files of the primary and nothing of the ledgers.

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

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

Tests: passed: suite/mirror.test.ts the mirror works over a folder and a store in memory alike, and a replica that is a folder

FR-012checkpassing

A mirror MUST be refused where a name is used twice, where a store lacks a core capability, or where the prefix of the ledgers is the root, and a replica name MUST be one identifier.

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

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

Tests: passed: suite/mirror.test.ts a mirror is refused where the primary lacks a core capability, a name is used twice or the

FR-013checkpassing

After any run of changes and settlements the replica MUST equal the primary at every path that is not diverged, and a second settlement MUST change nothing.

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

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

Tests: passed: suite/mirror.test.ts property: after any run of changes and settlements the replica equals the primary at every

FR-014checkpassing

A convergence MUST delete at a replica only within the allowance of the policy, and a policy that forbids deletes MUST leave a deleted file at the replica.

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

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

Tests: passed: suite/mirror.test.ts a delete is made at a replica only within the allowance, and the plain policy never delete

Acceptance scenarios

  1. Given a primary and a replica, When a file is written and the mirror is settled, Then the replica holds it and a second settlement does nothing, per FR-002.
  2. Given a replica that is down, When a file is written, Then the write succeeds and the replica is behind, per FR-003.

Out of scope

  • A mirror of a primary and replicas of different paths (a replica is a whole store; narrow it with sub first), a mirror that runs in the background by a timer, and the merge of a diverged path.

Edge cases

  • A promotion of a replica whose capabilities are fewer than the primary's: refused, per FR-008.
  • A primary that is down and a policy that does not allow a fallback: the read is the primary's answer, per FR-005.

Assumptions

  • A store passed as a replica is the object with all of its own capabilities, so that a replica with batch is settled as one batch.

Open questions

  • None.

Key entities

  • The mirror - the store, its replicas, and what is done with them.
  • The ledger - for one replica, the digest of what it was last brought to at each path.

Success criteria

SC-001success criterion

A fleet written to an SSH primary is held, by settlement, by a Git replica and a folder, and the Git replica can become the primary.

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

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