Skip to content

feat: release native transparent session filesystem preview - #1

Merged
jstar0 merged 36 commits into
mainfrom
feat/transparent-session-fs
Jul 23, 2026
Merged

feat: release native transparent session filesystem preview#1
jstar0 merged 36 commits into
mainfrom
feat/transparent-session-fs

Conversation

@jstar0

@jstar0 jstar0 commented Jul 18, 2026

Copy link
Copy Markdown
Contributor

CodexFold v0.3.0-beta.1

This release turns the transparent session filesystem work into a versioned,
reviewable preview. The storage engine remains local-first and byte-exact. On
macOS, the terminal architecture is an Apple-native Swift FSKit extension
connected to the Go daemon over a capability-negotiated Unix-domain-socket
protocol.

Highlights

  • Transparent JSONL paths backed by packfiles, indexes, manifests, and append
    deltas.
  • Copy-on-write backing for non-append mutation and unknown safe write paths.
  • Transactional App, helper, launchd-definition, mount, and rollback updates.
  • Current-client compatibility contracts and fail-closed quarantine.
  • Native namespace refresh, descriptor streaming, bounded concurrent
    read-ahead, generation invalidation, and stale-size repair.
  • Recoverable archive/unarchive and fork behavior without sharing writable
    tails between parent and child sessions.

macOS Canary Evidence

The signed local build 102 candidate passed an isolated Apple-native FSKit
Canary without routing the production Codex home or production SQLite state.
Release source metadata is 0.3.0 (103): build 103 completed a signed Release
build and nested Host/extension signature verification. Its FSKit behavior is
unchanged from build 102, so the mounted and real-client evidence below remains
attributed to the exact candidate that produced it.

  • Real bundled Codex CLI 0.145.0-alpha.30 resume, history use, tool execution,
    and append passed.
  • Real Codex Desktop 26.715.72359+5718 resume, send, fork, child continuation,
    archive/unarchive, and restart passed.
  • Parent and child histories remained valid JSONL and byte-identical to their
    expected native or reconstructed forms.
  • All 11 fs doctor components were healthy after the final host restart.
  • Five independently restarted 256 MiB managed-file matrices passed the fixed
    cold-read ratio gate of 0.70 and warm-read ratio gate of 0.80.
  • Accepted cold ratios were 0.762, 2.042, 0.800, 1.761, and 0.941;
    warm ratios were 0.954, 1.011, 0.963, 0.993, and 0.981.
  • Post-matrix aggregate RSS was 164,688 KiB, below the 256 MiB bound.
  • A post-restart sample measured managed cold and warm reads at 5.96 GiB/s
    and 17.73 GiB/s; FSKit append plus fsync measured 5.21 ms p50,
    9.51 ms p95, and 19.71 ms p99. These are observations, not guaranteed
    throughput on other machines.

Install the CLI

This prerelease changes the canonical module path. Install it explicitly:

go install github.com/samekind/codexfold/cmd/codexfold@v0.3.0-beta.1
codexfold --version

GitHub Release archives contain the default storage-oriented CLI for macOS,
Linux, and Windows on amd64 and arm64, plus checksums.txt.

FSKit Source Build

The FSKit App is intentionally not attached as a public binary. The validated
candidate is signed with a maintainer Apple Development identity, not a
Developer ID distribution identity, and is not notarized for general use.
Build the App from platform/darwin/fskit with Xcode 27, XcodeGen, an eligible
Apple development team, and isolated test paths. Follow the maintainer guide
and macOS Canary report before enabling any route.

Readiness Boundary

This is a preview release, not permission to delete native session sources or
bulk-enroll a production Codex home. Production promotion still requires:

  • retained native sources and verified rollback throughout the Canary period;
  • actual in-flight power-loss testing;
  • the incident-free observation gate;
  • current-client compatibility approval after each Codex upgrade;
  • real runtime validation before Linux or Windows receives a production-ready
    capability claim.

The complete evidence and limitations are documented in
docs/validation-macos-canary.md, docs/validation-linux-fuse3.md, and the
transparent filesystem product contract.

jstar0 added 30 commits July 12, 2026 00:14
@jstar0 jstar0 changed the title feat: native transparent session filesystem preview feat: release native transparent session filesystem preview Jul 23, 2026
@jstar0
jstar0 merged commit 204f65a into main Jul 23, 2026
7 checks passed
@jstar0
jstar0 deleted the feat/transparent-session-fs branch July 23, 2026 14:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant