Skip to content

Commit 9996794

Browse files
committed
docs: publish v0.3.0-beta.2 validation boundary
1 parent bcf0808 commit 9996794

5 files changed

Lines changed: 156 additions & 7 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,41 @@ pre-1.0, so a minor version may contain compatibility changes.
66

77
## [Unreleased]
88

9+
## [0.3.0-beta.2] - 2026-07-24
10+
11+
### Added
12+
13+
- Bounded-memory Pack V3 storage with indexed packfiles, exact object and
14+
manifest verification, and pack-only session reconstruction.
15+
- Dry-run-first retirement of loose objects and retained native snapshots,
16+
including durable proofs, interrupted-retirement recovery, and exact native
17+
rollback after the original snapshot is gone.
18+
- A native FSKit Unix-socket path preflight that rejects service definitions
19+
macOS cannot bind.
20+
21+
### Changed
22+
23+
- Filesystem and enrollment health checks now verify manifests through the
24+
authoritative current pack after loose objects are retired. A present but
25+
unreadable `packs/CURRENT` fails closed instead of being masked by loose
26+
objects.
27+
- The isolated current-client Canary now covers Pack-only CLI and Desktop
28+
resume, a real repository test run, official Desktop fork, parent/child
29+
isolation, service restart, process recovery, and canonical native rollback.
30+
31+
### Validation Boundary
32+
33+
- Current PATH CLI `0.144.3` and Desktop `26.721.31836+5828` completed real
34+
model turns against an isolated Pack-only parent. The parent and native child
35+
then continued independently with valid JSONL and passing `go test ./...`.
36+
- The 256 MiB managed FSKit sample passed after loose retirement with cold and
37+
warm mounted/native ratios of `3.009` and `1.024`; aggregate service RSS was
38+
`169,088 KiB`, below the `256 MiB` gate.
39+
- Go daemon, supervisor, Host wrapper, and FSKit extension termination each
40+
recovered automatically with unchanged complete SHA-256 values.
41+
- Full production promotion still requires the incident-free observation
42+
period and a deliberately controlled in-flight host power-interruption test.
43+
944
## [0.3.0-beta.1] - 2026-07-23
1045

1146
### Added
@@ -55,7 +90,8 @@ pre-1.0, so a minor version may contain compatibility changes.
5590

5691
- Initial local-first scan, fold, exact restore, and object-store release.
5792

58-
[Unreleased]: https://github.com/samekind/codexfold/compare/v0.3.0-beta.1...HEAD
93+
[Unreleased]: https://github.com/samekind/codexfold/compare/v0.3.0-beta.2...HEAD
94+
[0.3.0-beta.2]: https://github.com/samekind/codexfold/compare/v0.3.0-beta.1...v0.3.0-beta.2
5995
[0.3.0-beta.1]: https://github.com/samekind/codexfold/compare/v0.2.1...v0.3.0-beta.1
6096
[0.2.1]: https://github.com/samekind/codexfold/releases/tag/v0.2.1
6197
[0.2.0]: https://github.com/samekind/codexfold/releases/tag/v0.2.0

‎README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ It finds exact duplicate raw JSON string tokens, complete JSONL records, and con
1212
1313
## Current Status
1414

15-
`v0.3.0-beta.1` is the first versioned `fs-engine-preview`. It preserves the released storage-engine commands from `v0.2.1` and adds the transparent filesystem implementation, guarded service lifecycle, and platform validation described below.
15+
`v0.3.0-beta.2` is the current `fs-engine-preview`. It adds bounded Pack V3 storage, verified loose-object and native-snapshot retirement, Pack-only recovery, and current-client validation to the transparent filesystem introduced in `v0.3.0-beta.1`.
1616

1717
The requirements and release gates for normal JSONL paths backed transparently by shared storage are defined in [the transparent filesystem product contract](docs/superpowers/specs/2026-07-11-transparent-session-filesystem-design.md). No release may claim `随点随开`, transparent session access, or production-ready virtual sessions before the platform-specific gates in that contract pass.
1818

@@ -29,7 +29,7 @@ The transparent filesystem preview has these explicit boundaries:
2929
- The earlier synchronous FUSE-T NFS route remains historical validation evidence and a development fallback only. FUSE-T's third-party FSKit backend remains rejected after deterministic byte-loss and cache-invalidation failures; it is not the Apple-native FSKit implementation in this repository.
3030
- Linux FUSE3 has real unprivileged read, append, copy-on-write, truncate, archive rename, crash recovery, remount, performance, and `systemd --user` lifecycle evidence.
3131
- Windows has a WinFsp adapter and native Windows Service host that cross-compile, but no real Windows/WinFsp host has validated them yet.
32-
- The production service and production Codex home remain disabled. Retention, actual in-flight power loss, the incident-free observation gate, and the remaining platform-specific client gates still block promotion.
32+
- The production service and production Codex home remain disabled by default. The isolated macOS candidate has completed Pack-only current-client, restart, rollback, process-recovery, and performance gates. A controlled in-flight host power interruption and the incident-free observation period still block general production promotion.
3333

3434
See [the Linux FUSE3 validation](docs/validation-linux-fuse3.md) and [the macOS canary validation](docs/validation-macos-canary.md) for the evidence boundary. The default build remains storage-only; platform mounts require explicit build tags and installed host prerequisites.
3535

@@ -38,11 +38,11 @@ See [the Linux FUSE3 validation](docs/validation-linux-fuse3.md) and [the macOS
3838
Install the versioned preview with Go:
3939

4040
```bash
41-
go install github.com/samekind/codexfold/cmd/codexfold@v0.3.0-beta.1
41+
go install github.com/samekind/codexfold/cmd/codexfold@v0.3.0-beta.2
4242
codexfold --version
4343
```
4444

45-
The [GitHub Release](https://github.com/samekind/codexfold/releases/tag/v0.3.0-beta.1) provides checksum-covered default CLI archives for macOS, Linux, and Windows on `amd64` and `arm64`. These archives expose the local storage and recovery command surface; they do not contain a generally signed macOS FSKit App.
45+
The [GitHub Release](https://github.com/samekind/codexfold/releases/tag/v0.3.0-beta.2) provides checksum-covered default CLI archives for macOS, Linux, and Windows on `amd64` and `arm64`. These archives expose the local storage and recovery command surface; they do not contain a generally signed macOS FSKit App.
4646

4747
The FSKit App under `platform/darwin/fskit` currently requires Xcode 27, XcodeGen, an eligible Apple development team, and source signing. The validated App uses a maintainer Apple Development identity and is neither Developer ID distributed nor notarized for general installation. Follow the [maintainer guide](docs/maintainer-guide.md) and use only an isolated Codex home until the product contract permits production promotion.
4848

@@ -167,4 +167,4 @@ codexfold gc --apply
167167
git diff --check
168168
```
169169

170-
See the [changelog](CHANGELOG.md), [v0.3.0-beta.1 release notes](docs/releases/v0.3.0-beta.1.md), [architecture](docs/design.md), [Fold V1 format](docs/fold-v1.md), [v0.2 validation](docs/validation-v0.2.md), [transparent filesystem product contract](docs/superpowers/specs/2026-07-11-transparent-session-filesystem-design.md), and [maintainer guide](docs/maintainer-guide.md).
170+
See the [changelog](CHANGELOG.md), [v0.3.0-beta.2 release notes](docs/releases/v0.3.0-beta.2.md), [architecture](docs/design.md), [Fold V1 format](docs/fold-v1.md), [v0.2 validation](docs/validation-v0.2.md), [transparent filesystem product contract](docs/superpowers/specs/2026-07-11-transparent-session-filesystem-design.md), and [maintainer guide](docs/maintainer-guide.md).

‎VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
0.3.0-beta.1
1+
0.3.0-beta.2

‎docs/releases/v0.3.0-beta.2.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# CodexFold v0.3.0-beta.2
2+
3+
This prerelease completes the Pack V3 and Pack-only recovery path for the
4+
transparent filesystem preview. Folded objects can now be retired from the
5+
loose object tree after complete pack verification, while managed sessions,
6+
current Codex clients, forks, and native rollback retain exact behavior.
7+
8+
## Highlights
9+
10+
- Bounded-memory Pack V3 files and indexes replace object-per-file reads on the
11+
transparent path.
12+
- `pack retire-loose` verifies every packed object and manifest before deleting
13+
eligible loose objects.
14+
- `fs retire-native` removes a canonical retained snapshot only after pack-only
15+
recovery, writer exclusion, full materialization, and durable proof checks.
16+
- Filesystem health and automatic-enrollment gates understand Pack-only stores
17+
and fail closed when an authoritative current pack is damaged.
18+
- Native FSKit service installation rejects Unix socket paths macOS cannot
19+
bind.
20+
21+
## macOS Canary Evidence
22+
23+
The isolated Canary used signed Apple-native FSKit build 102, source metadata
24+
build 103, current PATH CLI `0.144.3`, and Desktop `26.721.31836+5828`.
25+
26+
- 63 of 63 objects and 4 of 4 manifests verified before all loose objects were
27+
retired.
28+
- Service restart preserved exact bytes for all three managed sessions.
29+
- Real CLI and Desktop turns read complete prior history, inspected a real Go
30+
project, and completed `go test ./...`.
31+
- An official Desktop fork produced an independently writable native child;
32+
child-only and parent-only markers did not cross branches.
33+
- Pack-only canonical rollback produced an exact ordinary native JSONL, and a
34+
subsequent real CLI native resume succeeded.
35+
- Go daemon, supervisor, Host, and FSKit extension crash recovery preserved
36+
exact SHA-256 values.
37+
- A 256 MiB managed performance run passed cold and warm ratio gates at `3.009`
38+
and `1.024`, with `F_NOCACHE` active and aggregate service RSS below 256 MiB.
39+
40+
## Install the CLI
41+
42+
```bash
43+
go install github.com/samekind/codexfold/cmd/codexfold@v0.3.0-beta.2
44+
codexfold --version
45+
```
46+
47+
Release archives contain the default storage-oriented CLI for macOS, Linux,
48+
and Windows on `amd64` and `arm64`, plus `checksums.txt`. The locally validated
49+
FSKit App is not attached because it uses an Apple Development identity rather
50+
than a generally distributable, notarized Developer ID identity.
51+
52+
## Readiness Boundary
53+
54+
The filesystem remains opt-in and reports `fs-engine-preview`. The isolated
55+
macOS candidate has completed executable Pack-only, current-client, restart,
56+
fork, rollback, process-recovery, and performance gates. General production
57+
promotion still requires the incident-free observation period and a controlled
58+
in-flight host power-interruption test. Linux still lacks a real Codex client
59+
gate, and Windows still lacks a real WinFsp runtime gate.

‎docs/validation-macos-canary.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,59 @@
11
# macOS Adapter And Canary Validation
22

3+
## Pack-Only Current-Client Canary (2026-07-24)
4+
5+
The signed build 102 Apple-native FSKit App/extension and helper candidate
6+
`a28ea3e8bbd213babe5467cf68daed685e884516bb6dd17b4a9116e879f8c139`
7+
completed the isolated Pack V3 retirement sequence without changing the real
8+
Codex home or the real Desktop process. Source metadata remains `0.3.0 (103)`;
9+
the mounted FSKit evidence is still attributed to behavior-identical build
10+
102 rather than relabeled as build 103.
11+
12+
- Pack doctor verified 63 of 63 objects and 4 of 4 manifests before deletion.
13+
`pack retire-loose --apply` removed all 63 loose objects and reclaimed
14+
339,968 physical bytes. After service restart, three managed files retained
15+
their exact lengths and SHA-256 values, including the 256 MiB fixture.
16+
- A temporary 4,096-byte mismatch was traced to the adjacent macOS AppleDouble
17+
file `._rollout-...jsonl`, whose SHA-256 exactly matched the alleged bad
18+
result. The canonical rollout itself remained byte-exact. Product discovery
19+
already excludes `._*`; all final checks used exact basenames.
20+
- Filesystem doctor initially exposed a genuine post-retirement gap: its
21+
manifest component still required loose objects. The shared health path now
22+
uses the authoritative current Pack resolver, and rejects a broken present
23+
`packs/CURRENT` instead of silently falling back. Final doctor reported all
24+
11 components healthy and zero issues with zero loose objects.
25+
- PATH `codex-cli 0.144.3` resumed the Pack-only parent, recovered the previous
26+
API-design rationale and concrete tests, inspected the real repository, and
27+
completed `go test ./...`. Desktop `26.721.31836+5828` displayed the complete
28+
history and completed another repository/test review.
29+
- Desktop's official `Continue in new chat from here` action created native
30+
child `019f93ea-ff0f-7753-a3b5-3e0a040c0caa`. The child inherited the full
31+
parent history, completed `go test ./...`, and matched its native backing
32+
byte-for-byte. Child-only and later parent-only markers remained isolated.
33+
- Canonical rollback materialized the Pack-only parent as a 1,196,755-byte
34+
native rollout with SHA-256
35+
`c61b3cbc0f65e860fadae315f747485bae427a31b1cf0d4b5fdebd0375f7b4b2`.
36+
The managed state was retired, service restart preserved mounted/native byte
37+
identity, and a real CLI native resume completed another model turn and
38+
`go test ./...`.
39+
- Transactional helper update made the configured, installed, and running
40+
helper SHA identical. Forced termination of the Go daemon child, supervisor
41+
child, Host wrapper, and active FSKit extension each recovered automatically.
42+
The 256 MiB managed fixture retained SHA-256
43+
`bdf04ec3fa10af7b803564739818047eb558829cb23d136dc010bd4aaa064d52`
44+
after every recovery.
45+
- The final independently restarted managed performance round measured cold
46+
native and virtual reads at 5,028.78 and 15,129.88 MiB/s, ratio `3.009`; warm
47+
reads measured 15,017.23 and 15,378.95 MiB/s, ratio `1.024`. `F_NOCACHE`
48+
applied to both cold paths. Aggregate service RSS was 169,088 KiB, below the
49+
256 MiB gate. Results are observations, not general throughput guarantees.
50+
51+
This closes the executable non-destructive Pack-only, current-client, fork,
52+
rollback, restart, process-recovery, and performance gates for the isolated
53+
macOS candidate. General production promotion still requires the dedicated
54+
incident-free observation period and a deliberately controlled host power
55+
interruption while a transaction is in flight.
56+
357
## Native FSKit Development Checkpoint
458

559
As of 2026-07-23, the terminal macOS validation candidate is the signed build 102 Apple-native Swift FSKit App/extension running the current Go helper through versioned binary UDS IPC. The transactionally installed isolated candidate passes mounted metadata and xattr behavior, append, `fsync`, `F_FULLFSYNC`, overlapping open lifetimes, random write, truncate, namespace and archive moves, mmap, open-unlink, external file and directory refresh, read-ahead coherency, eight-way virtual concurrent reads, exact-byte comparison, and managed service restart. Build-identity checks, environment sanitization, transactional app/definition/helper installation, and rollback also pass.

0 commit comments

Comments
 (0)