Skip to content

Commit 9304131

Browse files
committed
docs: record controlled in-flight host recovery
1 parent e8367e8 commit 9304131

4 files changed

Lines changed: 69 additions & 14 deletions

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,21 @@ pre-1.0, so a minor version may contain compatibility changes.
66

77
## [Unreleased]
88

9+
### Added
10+
11+
- A Darwin-only controlled host-interruption canary for the native append
12+
journal. It arms only with explicit environment variables, persists a
13+
journal and partial JSONL tail on an isolated internal-volume fixture, and
14+
requires a changed boot identity before product startup recovery can pass.
15+
16+
### Validation
17+
18+
- A real `reboot -q` interruption ran at the durable-journal / partial-tail
19+
checkpoint. On the next boot, automatic recovery restored the exact base
20+
SHA-256, rejected partial data, cleared the journal, and the independent
21+
Pack-only FSKit canary returned to 11 healthy doctor components with its
22+
256 MiB fixture unchanged.
23+
924
## [0.3.0-beta.2] - 2026-07-24
1025

1126
### Added

‎docs/superpowers/plans/2026-07-11-transparent-session-filesystem-implementation.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
1313
## Alignment Snapshot
1414

15-
Current public status remains `fs-engine-preview`. Tasks 1 through 10 and 12 through 14 are implemented. Task 11 has substantial isolated and bounded real-home macOS evidence, including current-client compatibility, sleep/wake, process-interruption recovery, and one idle retained-source managed CLI session surviving an actual host reboot. Linux FUSE3 now has real unprivileged operation, crash/restart, performance, mount-policy, and `systemd --user` lifecycle evidence. Windows WinFsp and SCM support are implemented and cross-compile, but lack a real Windows host. Actual in-flight power loss, the dedicated retention window, seven incident-free days, Linux client/upgrade/rollback/retention gates, and all real Windows gates remain open.
15+
Current public status remains `fs-engine-preview`. Tasks 1 through 10 and 12 through 14 are implemented. Task 11 has substantial isolated and bounded real-home macOS evidence, including current-client compatibility, sleep/wake, process-interruption recovery, one idle retained-source managed CLI session surviving an actual host reboot, and a separate durable-journal partial-tail controlled host-interruption recovery. Linux FUSE3 now has real unprivileged operation, crash/restart, performance, mount-policy, and `systemd --user` lifecycle evidence. Windows WinFsp and SCM support are implemented and cross-compile, but lack a real Windows host. The dedicated retention window, seven incident-free days, Linux client/upgrade/rollback/retention gates, and all real Windows gates remain open.
1616

1717
| Task | Status | Current evidence | Remaining work |
1818
| --- | --- | --- | --- |
@@ -26,11 +26,11 @@ Current public status remains `fs-engine-preview`. Tasks 1 through 10 and 12 thr
2626
| 8 | Complete | Standalone CLI, guarded lifecycle, bounded planner/apply loop, and isolated automatic-enrollment evidence | Production enablement remains gated by platform readiness |
2727
| 9 | Complete | Commit `4589ffa`; launchd, real `systemd --user`, Windows SCM compile, and update preflight tests | Windows service runtime and production update promotion remain platform-gated |
2828
| 10 | Complete | Commit `a1ac76e`; synthetic, crash, race, cross-compile, and 758 MiB evidence | This task proves only the shared engine preview |
29-
| 11 | Partial | Real macOS CLI/Desktop, FUSE-T, rollback, daemon restart, idle managed-session host reboot, and quarantine evidence | Complete the remaining disruptive and retention gates |
29+
| 11 | Partial | Real macOS CLI/Desktop, FUSE-T, rollback, daemon restart, idle managed-session host reboot, durable-journal partial-tail host interruption, and quarantine evidence | Complete the retention gate |
3030
| 12 | Complete | Bounded planner/apply/service tests plus isolated canonical automatic enrollment, native-writer probing, restart, append, quarantine, and failed-cutover evidence | Real-home automatic apply remains promotion-gated |
3131
| 13 | Complete | Fork graph reports, exact content comparison, guarded official-compatible archive transactions, recovery, static content-change boundaries, and isolated native plus managed FUSE-T round trips | None in this task |
3232
| 14 | Complete | Physical inventory, hard mutation budgets, lease-aware bounded GC, and truthful projected/actual accounting | Destructive retention remains promotion-gated |
33-
| 15 | Partial | Current macOS client contracts plus restart gates; real Linux FUSE3 operation, crash, performance, and systemd lifecycle; Windows WinFsp/SCM cross-compile | Actual in-flight power loss, retention windows, Linux client/upgrade/rollback gates, and all real Windows gates remain |
33+
| 15 | Partial | Current macOS client contracts plus restart and controlled in-flight interruption gates; real Linux FUSE3 operation, crash, performance, and systemd lifecycle; Windows WinFsp/SCM cross-compile | Retention windows, Linux client/upgrade/rollback gates, and all real Windows gates remain |
3434

3535
## Global Constraints
3636

@@ -787,6 +787,7 @@ No private path, session ID, trace content, credential, or control-plane name ma
787787

788788
- [x] Import exact compatibility contracts for the currently installed Codex Desktop and CLI versions and return the isolated canary doctor to a clean client state.
789789
- [x] Run retained-source managed macOS canaries through sleep/wake and real host restart, including process-interrupted append, compaction, migration, and rollback cases required by the contract.
790+
- [x] Run a dedicated disposable native-append canary that durably persists one journal and a half-written tail, performs a `reboot -q` host interruption, rejects same-boot verification, and on the next boot proves exact base rollback, valid JSONL, and an empty journal. Verify the independent Pack-only FSKit canary remounts with `fs doctor` healthy.
790791
- [x] Implement the Linux FUSE3 adapter with explicit `fuse fuse3` build tags and execute real unprivileged read, append, copy-on-write, truncate, canonical rename, native fallback, `SIGKILL` stale-mount recovery, remount, performance, backing-seal, and `systemd --user` install/start/status/stop gates.
791792
- [x] Implement the Windows WinFsp adapter and native SCM service host, mount probe, configuration, start/stop/status, and restart policy; default and WinFsp binaries and tests cross-compile.
792793
- [ ] Continue only bounded real-home canary observation and complete seven incident-free days before any `platform-canary` promotion decision; general automatic apply remains disabled.

‎docs/superpowers/specs/2026-07-14-transparent-session-filesystem-implementation-alignment.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,22 +38,22 @@ The validation references in this document describe the completed signed build 1
3838
| Requirement | Current implementation | Tests or evidence | Status |
3939
| --- | --- | --- | --- |
4040
| `TF-001` | `internal/cli/fs.go`, `internal/mountfs`, canonical migration, automatic enrollment, and routing | Isolated CLI/Desktop direct-open, resume, and automatic-enrollment canaries | Partial only at release level: implemented and verified on macOS canaries; real-home automatic apply remains preview-gated |
41-
| `TF-002` | `internal/mountfs`, `internal/fskitproto`, the Swift FSKit extension, canonical routing, and mount identity | Native FSKit mounted behavior plus real current CLI/Desktop resume, append, fork, archive, restart, and post-crash continuation | Implemented and verified in an isolated macOS canary; production promotion remains gated by power-loss and retention evidence |
41+
| `TF-002` | `internal/mountfs`, `internal/fskitproto`, the Swift FSKit extension, canonical routing, and mount identity | Native FSKit mounted behavior plus real current CLI/Desktop resume, append, fork, archive, restart, post-crash continuation, and controlled in-flight host-interruption recovery | Implemented and verified in an isolated macOS canary; production promotion remains retention-gated |
4242
| `TF-003` | Neutral operation layer plus exact compatibility contracts in `internal/compat` | Real macOS traces and adapter canaries plus real Linux FUSE3 operations | Partial: current installed macOS clients and Linux adapter operations are covered; real Linux Codex clients and Windows are not validated |
4343
| `TF-004` | `internal/scan`, `internal/cdc`, `internal/fold`, `internal/pack` | Repeated field, record, CDC, fork, and non-prefix corpus tests | Implemented |
4444
| `TF-005` | `internal/vfs` append delta and writer leases | Append-without-hydration tests and real CLI/Desktop append evidence | Implemented |
4545
| `TF-006` | `internal/vfs` copy-on-write backing and neutral write operations | Random-write, truncate, interruption, native FSKit mounted mutation, and historical FUSE-T tests | Implemented |
4646
| `TF-007` | Immutable packs, in-memory index, bounded cache, random-read resolver | Pack round-trip/corruption tests and 758 MiB packed-read benchmark | Implemented |
4747
| `TF-008` | Packed-read benchmark, mounted performance tests, and `internal/testfs` stress harness | 758 MiB core benchmark, three native FSKit cold/warm `F_NOCACHE` rounds, cache-coherency matrix, bounded RSS, historical synchronous FUSE-T measurements, and Linux FUSE3 race performance | Implemented and verified for the shared core and macOS adapter; Windows runtime metrics remain open |
48-
| `TF-009` | Journal recovery, generation recovery, service keep-alive, restart-safe retirement | Recovery tests, daemon restart canaries, managed Deep Idle sleep/wake, and actual retained-source host reboot | Partial: no actual power loss during an in-flight transaction |
48+
| `TF-009` | Journal recovery, generation recovery, service keep-alive, restart-safe retirement | Recovery tests, daemon restart canaries, managed Deep Idle sleep/wake, retained-source host reboot, and a durable journal / partial-tail / non-graceful-host-restart canary | Implemented and verified for the isolated macOS transaction path; retention remains open |
4949
| `TF-010` | Shadow compare, optimistic routes, retained snapshots, current-byte fallback | 90,000 real random-range comparisons, rollback and failure-containment canaries, and one bounded retained-source user-home canary | Implemented for macOS canaries; retention remains open |
5050
| `TF-011` | `internal/enroll`, `fs enroll`, and the bounded standalone-service loop discover existing, new, and forked sessions, persist stability observations, take a fail-closed native-writer snapshot, and reuse fold/pack/migrate transactions | Policy tests plus a real writable-descriptor probe and isolated canonical FUSE enrollment, daemon restart, real CLI append, quarantine, and failed-cutover evidence | Implemented; real-home automatic apply remains disabled until platform promotion |
5151
| `TF-012` | Shared Go core, Apple-native Swift FSKit on macOS, Linux FUSE3, and Windows WinFsp adapters | Native FSKit mounted behavior, current-client, crash, and rollback tests; historical FUSE-T evidence; real Linux adapter tests; and Windows cross-compiles | Partial at the cross-platform product level: macOS real-client acceptance passes, while all real Windows gates remain open |
5252
| `TF-013` | Canonical capability type in `internal/fsctl/status.go` | Status rejection tests and CLI status tests | Implemented; current status is `fs-engine-preview` |
5353
| `TF-014` | Snapshot retention and destructive-action guards | Migration, rollback, and quarantine tests | Implemented as a safety rule; retention promotion gates remain open |
5454
| `TF-015` | Exact-version compatibility and update preflight quarantine | Unknown-version fallback and isolated canary tests | Implemented; the currently installed macOS CLI and Desktop are covered |
5555
| `TF-016` | Native FSKit Host/extension packaging, non-elevating launchd, `systemd --user`, and Windows SCM lifecycle | Signed native FSKit app installation/rollback, launchd crash matrix, real Linux service, and Windows cross-compile evidence | Implemented; native release packaging and Windows runtime execution remain unverified |
56-
| `TF-017` | Canonical namespace, write-sealed backing, mount identity, route normalization, daemon/supervisor locks, and build identity | Native FSKit mounted namespace and current-client tests, four-process crash matrix, app/binary rollback, real Linux FUSE3, and historical FUSE-T evidence | Partial at the cross-platform product level: isolated macOS current-client gates pass; power-loss, retention, and Windows gates remain open |
56+
| `TF-017` | Canonical namespace, write-sealed backing, mount identity, route normalization, daemon/supervisor locks, and build identity | Native FSKit mounted namespace and current-client tests, four-process crash matrix, app/binary rollback, controlled in-flight host interruption, real Linux FUSE3, and historical FUSE-T evidence | Partial at the cross-platform product level: isolated macOS current-client gates pass; retention and Windows gates remain open |
5757
| `TF-018` | `internal/codex` spawn edges, `internal/family` graph/content evidence, `internal/archive` guarded transactions, and public `fork-family` plus `archive` commands | Diverse relationship fixtures, repeated-record performance regression, source-change rejection, official archive trace, native apply/recovery, and isolated managed FUSE-T archive/unarchive plus daemon restart | Implemented |
5858
| `TF-019` | `internal/contain` and `internal/prune`; public `contains` and `remove-contained` commands | Exact containment, archived-only apply, transaction rollback, and recovery-manifest tests | Implemented |
5959
| `TF-020` | Exact fold/migrate paths are byte-preserving; `repair-rollout` and `reconcile-rollout` write separate explicit outputs; a static production-import boundary prevents other workflows from invoking reconciliation | `internal/reconcile`, CLI behavior, and AST boundary tests | Implemented |
@@ -74,17 +74,17 @@ The validation references in this document describe the completed signed build 1
7474
| Task 8: standalone CLI and automatic enrollment | Complete | Command surface, guarded lifecycle, bounded planner/apply loop, native service arguments, and isolated real FUSE enrollment evidence | Production enablement remains outside Task 8 |
7575
| Task 9: service lifecycle and update guard | Complete | Commit `4589ffa`; launchd, real `systemd --user`, Windows SCM compile, and preflight tests pass | Windows runtime and stronger automatic update claims remain release-gated |
7676
| Task 10: synthetic, crash, performance, and compile gates | Complete for the shared engine | Commit `a1ac76e`; preview validation report | It cannot satisfy real-adapter or retention gates |
77-
| Task 11: real macOS trace, adapter, shadow, and canary | Partial | Native FSKit build 102 mounted behavior, performance/coherency, bounded RSS, four-process and host-reboot recovery, atomic update rollback, and complete real current CLI/Desktop acceptance | Actual in-flight power loss and the incident-free retention window remain |
77+
| Task 11: real macOS trace, adapter, shadow, and canary | Partial | Native FSKit build 102 mounted behavior, performance/coherency, bounded RSS, four-process and host-reboot recovery, controlled durable-journal host interruption, atomic update rollback, and complete real current CLI/Desktop acceptance | Incident-free retention window remains |
7878
| Task 12: bounded automatic discovery and enrollment | Complete | Planner/apply/service tests plus isolated canonical FUSE enrollment, daemon restart, real CLI append, quarantine, and failed-cutover evidence | Real-home automatic apply remains platform-gated |
7979
| Task 13: conservative branch lifecycle and content-change boundary | Complete | Spawn-edge family reports, exact relationship comparison, official-compatible guarded archive and recovery, separate exact-contained deletion, and static content-change boundaries pass unit, race, native, and managed FUSE-T validation | None in this task |
8080
| Task 14: hard storage budgets, retention, cleanup, and accounting | Complete | Platform-neutral inventory, hard preflight, lease-aware bounded GC, truthful accounting, low-space and repeated-GC tests | Destructive retention remains platform-gated |
81-
| Task 15: remaining platform and retention gates | Partial | Current macOS contracts and real-client acceptance; real Linux FUSE3 operation, crash, performance, backing policy, and systemd lifecycle; Windows WinFsp/SCM cross-compile | Actual in-flight power loss, retention period, Linux client/upgrade/rollback gates, and all real Windows gates remain |
81+
| Task 15: remaining platform and retention gates | Partial | Current macOS contracts, real-client acceptance, and controlled in-flight host interruption; real Linux FUSE3 operation, crash, performance, backing policy, and systemd lifecycle; Windows WinFsp/SCM cross-compile | Retention period, Linux client/upgrade/rollback gates, and all real Windows gates remain |
8282

8383
## Remaining Product Behavior And Exact Next Work
8484

8585
| Missing behavior | Exact implementation work | Required verification |
8686
| --- | --- | --- |
87-
| Remaining macOS promotion gates | Perform an actual in-flight power-loss canary and complete the incident-free retention window only on disposable or explicitly approved data | Exact full-file SHA, deterministic journal recovery, no route loss, and the required incident-free window |
87+
| Remaining macOS promotion gates | Complete the incident-free retention window only on disposable or explicitly approved data | No new route loss, exact full-file SHA where applicable, and the required incident-free window |
8888
| Linux remaining readiness | Keep the implemented FUSE3 adapter and systemd lifecycle behind platform gates | Real Linux Codex traces, client upgrade quarantine, rollback, and retention |
8989
| Windows readiness | Execute the implemented WinFsp adapter and SCM host without moving shared behavior out of the core | Native operations, crash/restart, performance, real Codex traces, upgrade quarantine, rollback, and retention on a real Windows host |
9090

0 commit comments

Comments
 (0)