feat(bin): add verified sovereign ledger replicas

.github/workflows/ci.yml

@@ -35,6 +35,15 @@ jobs:
       - name: Prove complete regression partition
         run: bin/fm-test-run.sh --check-coverage
 
+  sovereign-ledger-mutation-evidence:
+    name: Sovereign ledger mutation evidence
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v6
+      - name: Regenerate and byte-compare maintained evidence
+        run: tests/fm-sovereign-ledger-redundancy.mutation.sh --verify-evidence
+
   # Two duration-balanced portable parallel shards of the Phase 2 proven-isolated
   # set only. Composition owner: bin/fm-test-run.sh (docs/fm-test-portable-shards.md).
   tests-portable-parallel-1:

docs/documentation-audiences.json

@@ -108,6 +108,10 @@
     }
   ],
   "surfaces": [
+    {
+      "path": "tests/fixtures/sovereign-ledger-redundancy/CONTRACT.md",
+      "audience": "maintainer-verification"
+    },
     {
       "path": ".agents/skills/afk/SKILL.md",
       "audience": "agent-runtime"
@@ -352,6 +356,10 @@
       "path": "docs/verification/runtime-backends.md",
       "audience": "maintainer-verification"
     },
+    {
+      "path": "docs/verification/sovereign-ledger-redundancy-mutation.md",
+      "audience": "maintainer-verification"
+    },
     {
       "path": "docs/verification/stow-memory.md",
       "audience": "maintainer-verification"

docs/scripts.md

@@ -33,6 +33,7 @@ The shared no-mistakes gate refusal for fleet lifecycle entrypoints is summarize
 | `fm-herdr-ci-cleanup.sh` | Snapshot and tear down only job-owned `fm-lab-*` sessions in the Herdr CI lane       |
 | `fm-test-run.sh`         | Behavior-test runner: selection, portable lanes, proven-isolated `--jobs`, coverage guard, timing/JSON |
 | `fm-test-isolation-proof.sh` | Concurrent isolation proof and proven-isolated candidate set owner |
+| `fm-sovereign-ledger-redundancy.sh` | Create, append-only-refresh, and byte-verify a complete local sovereign-ledger replica bundle |
 | `fm-ensure-agents-md.sh` | Ensure a project's real `AGENTS.md`, its `CLAUDE.md` symlink, and the canonical self-governance section |
 | `fm-guard.sh`            | Warn on primary-checkout tangles, pending queued wakes, and unhealthy supervision    |
 | `fm-primary-scope-lib.sh` | Shared marker-or-plain-checkout primary-home predicate for tracked hooks             |

tests/fixtures/sovereign-ledger-redundancy/CONTRACT.md

@@ -0,0 +1,3 @@
+# Fixture sovereign ledger contract
+
+This fixture models the public `verify`, `recheck`, and `text` commands consumed by the redundancy mechanism tests.

tests/fixtures/sovereign-ledger-redundancy/fm-sovereign-ledger.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Fixture ledger verifier for the redundancy mechanism's public dependency boundary.
+set -euo pipefail
+
+ledger_dir=${LEDGER_DIR:?LEDGER_DIR is required}
+ledger=$ledger_dir/ledger.tsv
+
+verify() {
+  [ -f "$ledger" ] || exit 1
+  awk -F '\t' '
+    NF != 3 { bad = 1 }
+    $1 !~ /^ruling-[1-5]$/ { bad = 1 }
+    seen[$1]++ != 0 { bad = 1 }
+    END { exit bad || length(seen) < 4 ? 1 : 0 }
+  ' "$ledger"
+}
+
+recheck() {
+  local key source count=0 bad=0
+  while IFS=$'\t' read -r key source _; do
+    count=$((count + 1))
+    if [ ! -f "$source" ]; then
+      printf 'SOURCE_GONE   %s (%s)\n' "$key" "$source"
+      bad=$((bad + 1))
+    fi
+  done < "$ledger"
+  printf 'recheck: %s entries, %s divergent\n' "$count" "$bad"
+  [ "$bad" -eq 0 ]
+}
+
+text() {
+  awk -F '\t' -v key="$1" '$1 == key { print $3; found = 1 } END { exit found ? 0 : 1 }' "$ledger" | base64 -d
+}
+
+case "${1:-}" in
+  verify) verify ;;
+  recheck) recheck ;;
+  text) text "${2:?ruling key}" ;;
+  *) exit 2 ;;
+esac

tests/fixtures/sovereign-ledger-redundancy/tests.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Fixture companion test file: copied and compared as part of the complete bundle.
+exit 0

tests/fm-sovereign-ledger-cross-volume.test.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Prove the strict default accepts a genuine replica on a separately mounted volume.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TOOL="$ROOT/bin/fm-sovereign-ledger-redundancy.sh"
+FIXTURE="$ROOT/tests/fixtures/sovereign-ledger-redundancy"
+TMP="$(mktemp -d)"
+VOLUME_ROOT=
+ATTACHED_VOLUME=no
+
+cleanup_fixture() {
+  local scratch=$1 volume_root=$2 attached=$3 hdiutil_command=$4
+  if [ "$attached" = yes ]; then
+    if ! "$hdiutil_command" detach "$volume_root" >/dev/null 2>&1; then
+      printf 'FAIL could not detach fixture volume; retained scratch and image at %s\n' "$scratch" >&2
+      return 1
+    fi
+    attached=no
+  fi
+  rm -rf -- "$scratch"
+  if [ -n "$volume_root" ] && [ "$attached" = no ] && [[ "$volume_root" != "$scratch"/* ]]; then
+    rm -rf -- "$volume_root"
+  fi
+}
+
+finish() {
+  local status=$?
+  if ! cleanup_fixture "$TMP" "$VOLUME_ROOT" "$ATTACHED_VOLUME" hdiutil; then
+    status=1
+  fi
+  trap - EXIT HUP INT TERM
+  exit "$status"
+}
+trap finish EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+FAKE_HDIUTIL="$TMP/fake-hdiutil"
+printf '%s\n' \
+  '#!/usr/bin/env bash' \
+  "printf '%s\n' \"\$*\" >> \"\$CLEANUP_HDIUTIL_LOG\"" \
+  "exit \"\$CLEANUP_HDIUTIL_STATUS\"" > "$FAKE_HDIUTIL"
+chmod +x "$FAKE_HDIUTIL"
+export CLEANUP_HDIUTIL_LOG CLEANUP_HDIUTIL_STATUS
+
+CLEANUP_FAILURE="$TMP/cleanup-failure"
+CLEANUP_FAILURE_VOLUME="$CLEANUP_FAILURE/volume"
+CLEANUP_FAILURE_LOG="$TMP/cleanup-failure.log"
+CLEANUP_FAILURE_DIAGNOSTIC="$TMP/cleanup-failure.diagnostic"
+mkdir -p "$CLEANUP_FAILURE_VOLUME/replica"
+: > "$CLEANUP_FAILURE/ledger-volume.dmg"
+: > "$CLEANUP_FAILURE_VOLUME/replica/ledger.tsv"
+if CLEANUP_HDIUTIL_LOG="$CLEANUP_FAILURE_LOG" CLEANUP_HDIUTIL_STATUS=1 \
+  cleanup_fixture "$CLEANUP_FAILURE" "$CLEANUP_FAILURE_VOLUME" yes "$FAKE_HDIUTIL" 2> "$CLEANUP_FAILURE_DIAGNOSTIC"; then
+  printf 'FAIL cleanup accepted a failed fixture-volume detach\n' >&2
+  exit 1
+fi
+[ "$(cat "$CLEANUP_FAILURE_LOG")" = "detach $CLEANUP_FAILURE_VOLUME" ] \
+  && grep -Fq 'retained scratch and image' "$CLEANUP_FAILURE_DIAGNOSTIC" \
+  && [ -f "$CLEANUP_FAILURE/ledger-volume.dmg" ] \
+  && [ -f "$CLEANUP_FAILURE_VOLUME/replica/ledger.tsv" ] || {
+  printf 'FAIL failed detach did not retain the fixture scratch, image, and mounted-path contents\n' >&2
+  exit 1
+}
+rm -rf -- "$CLEANUP_FAILURE"
+
+CLEANUP_SUCCESS="$TMP/cleanup-success"
+CLEANUP_SUCCESS_VOLUME="$CLEANUP_SUCCESS/volume"
+CLEANUP_SUCCESS_LOG="$TMP/cleanup-success.log"
+mkdir -p "$CLEANUP_SUCCESS_VOLUME/replica"
+: > "$CLEANUP_SUCCESS/ledger-volume.dmg"
+CLEANUP_HDIUTIL_LOG="$CLEANUP_SUCCESS_LOG" CLEANUP_HDIUTIL_STATUS=0 \
+  cleanup_fixture "$CLEANUP_SUCCESS" "$CLEANUP_SUCCESS_VOLUME" yes "$FAKE_HDIUTIL"
+[ "$(cat "$CLEANUP_SUCCESS_LOG")" = "detach $CLEANUP_SUCCESS_VOLUME" ] \
+  && [ ! -e "$CLEANUP_SUCCESS" ] || {
+  printf 'FAIL successful detach did not remove the fixture scratch and image\n' >&2
+  exit 1
+}
+
+device_identity() {
+  local identity
+  if identity=$(stat -f '%d' "$1" 2>/dev/null); then
+    :
+  elif identity=$(stat -c '%d' "$1" 2>/dev/null); then
+    :
+  else
+    return 1
+  fi
+  printf '%s\n' "$identity"
+}
+
+if [ -d /dev/shm ] && [ -w /dev/shm ] \
+  && [ "$(device_identity /dev/shm)" != "$(device_identity "$TMP")" ]; then
+  VOLUME_ROOT=$(mktemp -d /dev/shm/fm-ledger-volume.XXXXXX)
+elif command -v hdiutil >/dev/null 2>&1; then
+  VOLUME_ROOT="$TMP/ledger-volume"
+  mkdir "$VOLUME_ROOT"
+  hdiutil create -quiet -size 32m -fs APFS -volname fm-ledger-r5 "$TMP/ledger-volume.dmg"
+  ATTACHED_VOLUME=yes
+  hdiutil attach -quiet -nobrowse -mountpoint "$VOLUME_ROOT" "$TMP/ledger-volume.dmg"
+else
+  printf 'FAIL no writable separate volume is available for the strict acceptance proof\n' >&2
+  exit 1
+fi
+
+PRIMARY="$TMP/primary"
+REPLICA="$VOLUME_ROOT/replica"
+mkdir "$PRIMARY"
+cp "$FIXTURE/CONTRACT.md" "$PRIMARY/CONTRACT.md"
+cp "$FIXTURE/fm-sovereign-ledger.sh" "$PRIMARY/fm-sovereign-ledger.sh"
+cp "$FIXTURE/tests.sh" "$PRIMARY/tests.sh"
+chmod +x "$PRIMARY/fm-sovereign-ledger.sh" "$PRIMARY/tests.sh"
+: > "$PRIMARY/ledger.tsv"
+for number in 1 2 3 4; do
+  printf 'ruling-%s\t/source-%s\tZml4dHVyZQo=\n' "$number" "$number" >> "$PRIMARY/ledger.tsv"
+done
+
+PRIMARY_DEVICE=$(device_identity "$PRIMARY")
+REPLICA_PARENT_DEVICE=$(device_identity "$VOLUME_ROOT")
+[ "$PRIMARY_DEVICE" != "$REPLICA_PARENT_DEVICE" ] || {
+  printf 'FAIL separate-volume fixture unexpectedly shares st_dev %s\n' "$PRIMARY_DEVICE" >&2
+  exit 1
+}
+"$TOOL" snapshot "$PRIMARY" "$REPLICA" >/dev/null
+"$TOOL" verify "$PRIMARY" "$REPLICA" >/dev/null
+printf '2 passed, 0 failed (strict cross-volume snapshot and verify; st_dev %s!=%s)\n' "$PRIMARY_DEVICE" "$REPLICA_PARENT_DEVICE"