|
| 1 | +# CodexFold v0.4.0-beta.1 |
| 2 | + |
| 3 | +This prerelease makes periodic enrollment survive a real corpus. The previous |
| 4 | +preview could fold, but a single refusal anywhere in a cycle left the store |
| 5 | +unable to make progress again, and nothing recovered on its own. Folding a |
| 6 | +2,800-session store surfaced five separate ways to get permanently stuck, each |
| 7 | +of which silently blocked every later cycle. |
| 8 | + |
| 9 | +## Highlights |
| 10 | + |
| 11 | +- Batch size is measured rather than assumed. A cycle rebuilds the whole pack |
| 12 | + whether it folds one session or two hundred, so the batch is derived from the |
| 13 | + rebuild and per-session costs recent cycles measured, keeping that fixed toll |
| 14 | + to roughly a quarter of the work. The Auto fold pane gains a "How many per |
| 15 | + pass" control, and `batch_size: 0` in `<store>/enrollment/policy.json` selects |
| 16 | + the automatic setting. |
| 17 | +- A staged canonical snapshot that is byte-identical to its source is reused |
| 18 | + instead of refused, so a migration that failed after staging can be retried. |
| 19 | +- A failed migration no longer skips reclamation. Only deleting a user's |
| 20 | + original waits for a clean cycle. |
| 21 | +- Enrollment planning consults the batch limit before pricing a candidate |
| 22 | + against the storage budget, because each price is a full store scan. |
| 23 | +- A cycle repacks once before the storage-health gate blocks it, so a pack build |
| 24 | + refused for free space no longer locks enrollment permanently. |
| 25 | +- A mount-table probe that exceeds its deadline is inconclusive rather than an |
| 26 | + outage, gated on the backend still answering. |
| 27 | +- A status channel that stops advancing degrades the indicator and escalates |
| 28 | + only once sustained; a component reporting failure still alerts at ten |
| 29 | + seconds. |
| 30 | +- Read-ahead extends its horizon only after a read advances into the adjacent |
| 31 | + block. |
| 32 | + |
| 33 | +## What Went Wrong Before |
| 34 | + |
| 35 | +These are the behaviours this release removes, with the numbers the production |
| 36 | +store recorded. |
| 37 | + |
| 38 | +- 237 sessions sat folded into the pack with their originals still on disk, |
| 39 | + because a staged snapshot could never be re-staged. That duplication was the |
| 40 | + 884 MB behind a reported saving of zero. |
| 41 | +- One unroutable session stopped reclamation while the same cycle's pack build |
| 42 | + had already written a new generation, so the store grew every cycle. |
| 43 | +- Pricing every candidate against the storage budget took planning from 0.42s |
| 44 | + to over 200s, where it was killed. The Host reported nothing left to fold and |
| 45 | + stopped. |
| 46 | +- 12,776 mount probes exceeded their deadline and were reported as recovery, |
| 47 | + each surfacing as a "needs attention" alert that healed itself within half a |
| 48 | + minute. A measured `getfsstat` on the same machine returns in 68 µs at the |
| 49 | + median and 542 µs at p99; the deadline was missed because the probe goroutine |
| 50 | + was not scheduled, not because the filesystem was slow. |
| 51 | + |
| 52 | +## Validation |
| 53 | + |
| 54 | +- 205 sessions whose native originals had been retired were read back through |
| 55 | + the mount and compared against the SHA-256 recorded at retirement: 666 MB, |
| 56 | + byte-identical, every JSONL record still parseable. The originals no longer |
| 57 | + exist, so the recorded digest is the only reference. |
| 58 | +- A real `pack build` over the production store compressed 748.50 MiB of raw |
| 59 | + session bytes into 400.35 MiB. |
| 60 | +- `fs retire-native --apply` on a live session reclaimed 98% of the original |
| 61 | + file while the mount continued to serve the exact same bytes and size. |
| 62 | +- A real `reboot -q` interruption ran at the durable-journal / partial-tail |
| 63 | + checkpoint. On the next boot, automatic recovery restored the exact base |
| 64 | + SHA-256, rejected partial data, cleared the journal, and the independent |
| 65 | + Pack-only FSKit canary returned to 11 healthy doctor components with its |
| 66 | + 256 MiB fixture unchanged. |
| 67 | + |
| 68 | +## Known Limitations |
| 69 | + |
| 70 | +- The public capability remains `fs-engine-preview`. Automatic updates are |
| 71 | + still refused before platform production readiness, and promotion is |
| 72 | + explicit. |
| 73 | +- Folding needs free space before it can reclaim any: a pack build is refused |
| 74 | + by the free-space reserve on a nearly full volume, and large sessions report |
| 75 | + `insufficient-storage-budget` until earlier ones free room. |
| 76 | +- `pack build` rewrites the whole pack each cycle. Batch sizing amortises that |
| 77 | + cost; it does not remove it. |
| 78 | + |
| 79 | +## Install the CLI |
| 80 | + |
| 81 | +```sh |
| 82 | +go install github.com/samekind/codexfold/cmd/codexfold@v0.4.0-beta.1 |
| 83 | +``` |
| 84 | + |
| 85 | +The GitHub Release provides checksum-covered default CLI archives for macOS, |
| 86 | +Linux, and Windows on `amd64` and `arm64`. These archives expose the local |
| 87 | +storage and recovery command surface; they do not contain a generally signed |
| 88 | +macOS FSKit App. |
0 commit comments