Thanks to visit codestin.com
Credit goes to github.com

Skip to content

feat(storage): mount authoritative owner filesystems on macOS, Linux, and Windows - #1535

Merged
joshuajbouw merged 110 commits into
mainfrom
codex/storage-mounted-filesystem
Aug 19, 2026
Merged

joshuajbouw merged 110 commits into
mainfrom
codex/storage-mounted-filesystem

Conversation

@joshuajbouw

@joshuajbouw joshuajbouw commented Aug 15, 2026

Copy link
Copy Markdown
Member

Linked Issue

Closes #1534

Related to #1391 and allocation-policy issue #1539.

Summary

Make Astrid storage the authoritative filesystem and durable state substrate for principal, fleet, and system-owner views, expose governed views as native mounts on macOS, Linux, and Windows, and fully migrate the released v0.10.4 layout before any legacy authority is retired.

Mounted files are not served from mutable alias-keyed host homes. Principal home:// resolves to that agent's immutable UID-owned home subtree; Fleet processes receive only the fixed shared subtree; workspace processes receive an explicit durable branch/prefix view. Files remain immutable content DAGs and acknowledged namespace mutations atomically advance the selected owner root.

Hosted installations realize the path-free AstridVolume contract as one locked, checksummed var/astrid.volume. Mounting does not provision an owner, principal, quota, or allocation: it projects an already-authorized storage view.

Changes

  • Add the path-free AstridVolume contract and hosted single-file volume with exclusive locking, bounded recovery, checksummed records, crash-recoverable physical reclaim, and atomic metadata transactions.
  • Generalize durable recovery, roots, indexing, compaction, content, KV, capsule registry, and owner filesystems over Astrid volumes.
  • Add fixed-prefix principal-home and Fleet-shared filesystems plus durable workspace branch begin/fork/promote/rollback semantics, stale-base rejection, UID binding, quota charging, read-handle retention, and compaction survival.
  • Bind native mount leases and private process projections to authenticated principals, immutable owners/branches, fixed prefixes, access mode, provider identity, expiry, parent lifetime, and random callback secrets.
  • Add bounded binary-safe callback protocol V2 while retaining correctly dispatched V1 decoding.
  • Ship macOS FSKit, Linux FUSE, and Windows WinFsp providers with structured readiness, bounded control paths, cleanup, and managed packaging/update integration.
  • Route capsule install/remove/list/show, capsule metadata, environment state, secrets, distro provenance, WIT retention, and canonical contracts through authenticated daemon/storage APIs instead of principal-home scans.
  • Store invites, pair tokens, gateway revocations, audit chains/retention, capsule authority, and other control-plane authority in typed system or UID-owned durable namespaces.
  • Add signed audit prune/health/stats APIs, bounded migration/verification, deterministic compaction proofs, evidence outbox retry, and physical reclamation reporting.
  • Organize audit append, batching, paging, pruning, migration, and verification by responsibility in typed Rust modules; the source-cap check now directs contributors toward coherent module boundaries and focused tests.

Released-layout migration

Kernel startup captures whether the home is fresh, released-layout, or existing-v2 before AstridHome::ensure, acquires the singleton lock, and runs one global migration barrier before mounts or ordinary service authority become available.

The barrier inventories every supported legacy source with bounded, no-follow, owner-controlled, same-device, and mount-boundary validation. Private sources retain owner-only permissions; released SurrealKV and immutable capsule-package trees admit their historical modes only when every entry is current-user-owned and not group/world writable. Pre-authority capsule installs are snapshotted once through the legacy verifier, including exact manifest, capability, and WASM pins, before their deterministic durable package digest is bound. It migrates and verifies:

  • state.db and the intermediate principal directory store into astrid.volume;
  • ordinary principal-home files into immutable UID-owned home subtrees;
  • principal env, secrets, capsule packages/metadata/WIT/authority, audit, logs, profile, distro lock, and init-lock state;
  • system invites, pair tokens, gateway revocations, host secrets, capsule authority, audit state, and verified disposable temporary/CoW state.

Each component records a canonical source identity and destination proof. Destination readback must match before the global ledger becomes complete. Retirement then revalidates the exact receipted source and removes it bottom-up through no-follow, mount-safe helpers with crash-resumable semantics. Missing receipts, source mutation, alias deletion/reuse, reappeared legacy roots, malformed or oversized markers, redirects, special files, nested mounts, insufficient capacity, or unsupported non-default audit/KV/token sources fail closed before mutation or service.

AstridHome::ensure no longer performs recursive pre-barrier retirement. Existing-v2 startup also requires valid fresh-layout or released-migration provenance and resumes only receipt-bound finalization. Agent deletion cannot sweep unretired legacy authority.

The published-v0.10.4 Linux fixture now seeds multiple aliases plus ordinary home data, profile, env, secrets, capsules and authority, audit, logs, distro locks, init lock, invites, pairing, revocations, temporary state, and post-cutover writes. It asserts destination proofs/readback, source absence, UID isolation, and restart persistence.

Ownership model

  • User: tenant boundary and fleet owner.
  • Fleet: shared computer/storage authority for that user.
  • Principal: agent, service, vault, or other actor with immutable UID-owned state.
  • Harness: a group of capsules; it is not a storage identity.
  • Mount: a temporary OS projection of an already-authorized fixed owner/branch/prefix view.
  • Quota/provisioning policy: tracked separately in Move user and fleet storage allocation policy to a capsule #1539; the kernel meters admitted ceilings without synchronous policy-capsule IPC inside storage transactions.

Platform status

  • macOS: FSKit provider, signed/notarized app packaging, lifecycle install/update/enable/status/uninstall, process-parent liveness, and protected live certification workflow.
  • Linux: FUSE provider, GNU/musl packaging, private service lifecycle, managed updates, required native /dev/fuse E2E, and published-v0.10.4 upgrade E2E.
  • Windows: WinFsp provider, private named-pipe callback transport, structured private service lifecycle, secure installer/uninstaller, native CI E2E, and backward-compatible release metadata.

Verification

Local verification across the integrated series; changed migration, audit, and capsule-install scopes were rerun on head 6b1e2993:

  • cargo clippy --workspace --all-features --all-targets --locked -- -D warnings
  • cargo test --workspace --locked — complete workspace tests and doctests passed
  • cargo test -p astrid-kernel --lib --locked — 385 passed
  • cargo test -p astrid-capsule --lib --locked — 664 passed
  • cargo test -p astrid-storage --all-features --lib secret --locked — 28 passed; default constructor verified KV-only
  • cargo test -p astrid-audit --lib --locked — 45 unit tests passed, including an exact empty released-audit receipt and lock-release regression
  • cargo test -p astrid-capsule-install --offline — 76 unit + 13 integration passed
  • FSKit provider tests — 13 passed, 1 live signed-runtime test ignored
  • Linux FUSE strict cross-target Clippy — passed
  • Windows WinFsp strict cross-target Clippy — passed
  • scripts/check-wasm-portability.sh — passed
  • migration barrier — 18/18; core directory/layout tests — 62/62
  • published v0.10.4 macOS released-home replay — migration, source retirement, start/status/stop, and second start/status/stop passed
  • gateway TLS integration tests — 3/3; audit CLI manifest coverage — passed
  • v0.10.4 upgrade script Bash syntax, ShellCheck, exact-toolchain poisoned-home probe, and repository diff checks — passed
  • cargo audit --file Cargo.lock — passed after updating h2 to the patched 0.4.16

Post-adversarial verification through 3bbc7724

  • cargo test --offline -p astrid-kernel --lib --no-fail-fast -- --quiet — 404 passed
  • cargo test --offline -p astrid-storage --lib --no-fail-fast -- --quiet — 711 passed, 7 ignored
  • cargo clippy --offline -p astrid-audit -p astrid-capsule-install -p astrid-gateway -p astrid-kernel -p astrid-storage --all-targets --all-features -- -D warnings — passed
  • cargo fmt --all -- --check and git diff --check — passed
  • Seven new commits carry matching human Signed-off-by trailers and valid GPG signatures
  • Typed audit key/sequence and pair-token state regressions — 53 audit tests and 18 pair-token tests passed

GitHub Actions was green on the prior integrated head 6b1e29937101a6a1954caa9bba1b0969a6fdc1fe: 35 checks passed and the two platform-inapplicable OCI attestation checks were skipped as designed. GitHub Actions was green on this after-pass head ddb2cee21c074a1c01431d63ec1873e2ac89e9fe: 35 checks passed and the two platform-inapplicable OCI attestation checks were skipped as designed.

AI / Tool Assistance

Assisted-by: OpenAI Codex: GPT-5.6

Codex assisted with architecture synthesis, implementation, adversarial review, tests, documentation, and validation. The human contributor reviewed the design and remains responsible for the code, evidence, and review responses.

Checklist

  • Linked to an issue
  • CHANGELOG.md updated under [Unreleased]
  • Migration and rollback paths have regression coverage
  • Native platform packaging and release metadata are covered
  • I understand every change in this PR and can explain its design, risks, and validation
  • I reviewed and tested meaningful tool-generated output included in this PR
  • Every non-bot, non-merge commit has a matching human Signed-off-by trailer and valid GPG signature

Note

High Risk: this PR spans storage authority, released-layout migration, kernel boot ordering, native provider handoff, and multi-platform packaging. Mergeability depends on the full required CI matrix, including the real Linux upgrade/FUSE jobs and protected live FSKit certification policy.

Latest CI repair

  • Fixed immediate live activation of storage-backed capsule installs by replacing the partial lifecycle workspace with a complete verified materialization before durable publication.
  • Added regression coverage that the immediate cache contains the exact verified WASM and authority bytes.
  • Scoped the macOS-only migration mountpoint test helper so Linux all-target Clippy stays warning-free.
  • Local validation: capsule-install 78/78; workspace all-feature/all-target Clippy with -D warnings; Runtime E2E progressed through the previously failing registry live activation.

Rust-quality after-pass through ddb2cee2

  • Grouped leftover #[path] siblings into directory modules for principal-home migration, the layout barrier, workspace branches, invites/pair tokens, hosted volumes, durable format/cache, process-broker identity, and admin env handlers.
  • Added validated NewTypes for principal-home receipt schema/digests/counts and layout-migration source identities. Durable JSON field shapes are unchanged.
  • Preserved prefixed blake3:<hex> source digests so distro-init discard proofs still bind.
  • Local: focused kernel/storage suites, then cargo clippy --offline -p astrid-kernel -p astrid-storage --all-targets --all-features -- -D warnings.
  • GitHub: 35 SUCCESS, 2 SKIPPED OCI attestation jobs on this head.

Assisted-by: OpenAI Codex: Grok 4.6

Copilot AI balanced review requested due to automatic review settings August 15, 2026 07:42

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@joshuajbouw joshuajbouw changed the title feat(storage): add layout v2 migration and mount boundary feat(storage): mount authoritative owner filesystems with macOS FSKit Aug 15, 2026
@joshuajbouw joshuajbouw changed the title feat(storage): mount authoritative owner filesystems with macOS FSKit feat(storage): mount authoritative owner filesystems on macOS, Linux, and Windows Aug 16, 2026
joshuajbouw added a commit that referenced this pull request Aug 18, 2026
Bind the graphical Home and personal renderer model to the existing resource, storage, and execution-provider architecture. Treat semantic scenes as untrusted projections, Spaces as composition rather than authority, and refresh the storage integration order around PRs #1535 and #1562.

Refs #1564

Signed-off-by: Joshua J. Bouw <[email protected]>
@joshuajbouw

Copy link
Copy Markdown
Member Author

Verification record and Rust-quality after-pass

This is an unusually large change: at the current head (3bbc7724bdadec8cc6fc11738ded2bbd282a46db), GitHub reports 431 changed files, 71,359 additions, 9,218 deletions, and 98 commits. A green badge alone is not enough evidence for a change of this size, and the work should not be represented as though generated code was accepted because it compiled.

What was actually measured

The implementation was developed and reviewed as a sequence of explicit behavioral claims:

  1. Adversarial reviews identified concrete failure sequences around migration, retirement, durable authority, recovery, audit ordering, live capsule activation, cache accounting, mounts, and platform lifecycle behavior.
  2. Where the behavior was locally testable, regression tests were written against the expected secure behavior first and the existing failure was reproduced. Fixes were then applied against those tests rather than inferred from static plausibility.
  3. Focused unit and integration suites were run for the affected crates, followed by workspace formatting and strict Clippy (--workspace --all-features --all-targets -- -D warnings).
  4. The Runtime E2E harness exercised the public CLI/daemon lifecycle, storage-backed capsule installation and immediate live activation, restart behavior, capability and principal isolation, HTTP routes, and concurrent/scoped mutations.
  5. The published-upgrade job downloaded the byte-exact released v0.10.4 x86_64 Linux archive, pinned it by SHA-256, created state using that released binary, upgraded it with this PR, and verified migration receipts, content digests, destination proofs, retirement of legacy sources, post-upgrade writes, and a second successful boot.
  6. Native/platform jobs exercised Linux FUSE, Windows WinFsp/named pipes, Windows migration/provisioning, release builds, macOS tests, Wasm portability, public API compatibility, OpenAPI drift, security audit, and CodeQL. One Windows job initially failed while downloading the Rust toolchain from static.rust-lang.org; it was rerun in isolation and passed every native test.

At this exact head, GitHub reports 35 passing checks, 2 intentionally skipped OCI attestation jobs, 0 pending checks, and 0 failures. This was measured from the PR check suite itself, not inferred from local output. In particular, both Runtime CLI + HTTP sweep and Published v0.10.4 Linux upgrade passed on GitHub-hosted runners.

That evidence gives us meaningful confidence in the behaviors exercised. It does not prove that 80,577 changed lines are architecturally clean, free of unreachable code, exhaustively tested, or ideal Rust.

Required Rust-quality after-pass

The next pass should be structural and evidence-producing, not cosmetic:

  • Module boundaries: convert families such as principal_home_migration_* and workspace_* into cohesive private modules grouped by responsibility. The 1,000-line source cap is a signal to extract understandable domain units, not merely shorten or mechanically split files.
  • Domain types: audit durable keys, UIDs, aliases, digests, receipts, epochs, byte counts, generations, owner scopes, component names, and lifecycle states for stringly typed or primitive-heavy APIs. Add validated NewTypes and exhaustive enums where they make invalid states or cross-namespace wiring unrepresentable, while preserving public/wire compatibility.
  • Dead and unreachable code: run compiler/Clippy coverage across the actual feature matrix, then add dedicated reachability/dependency checks (for example cargo udeps/dependency analysis where supported). Review cfg-only platform paths separately; ordinary dead_code warnings do not establish cross-feature reachability.
  • Test inventory: map production modules and privileged state transitions to direct unit tests. Identify files with no focused tests, especially migration receipt validation, crash/restart transitions, authority boundaries, provider lifecycle, and failure rollback.
  • Mutation and fault coverage: run targeted mutation testing on high-risk pure logic and add deterministic fault injection around durable publication, CAS failure, rename/swap, sync failure, recovery, and restart boundaries. Passing happy-path E2E is not a substitute for proving that guards are effective.
  • Provider consolidation: assess whether astrid-storage-provider-* should become one provider crate with platform features and shared lifecycle/registry/control logic. Consolidate only if platform signing, packaging, and native dependency boundaries remain explicit; avoid hiding materially different security semantics behind broad cfg blocks.
  • Unsafe and platform parity: inventory every unsafe block/FFI boundary and verify no-follow, ACL/privacy, mountpoint, handle identity, timeout, registry locking, unmount/sync, and cleanup behavior across macOS, Linux, and Windows.
  • Durable state-machine review: re-check migration, audit, invitation/pairing, volume reclaim, compaction, cache accounting, and capsule publication as explicit state machines. Confirm every intermediate state has a defined retry, rollback, or fail-closed restart outcome.
  • API and serialization review: confirm canonical encodings, schema/version handling, bounded decoding, typed error surfaces, and compatibility of stored/wire formats. New internal typing must not silently alter existing durable bytes.
  • Coverage reporting: publish per-crate/unit coverage as diagnostic evidence and review uncovered security-sensitive branches manually. Coverage percentage is not a quality target by itself, but missing execution is useful evidence.

This PR has been carefully exercised against real runtime, release-upgrade, restart, failure, and platform behavior. The remaining after-pass is how we ensure that the implementation is also maintainable and idiomatic—not merely behaviorally green today.

Replace the path-included principal-home and legacy-barrier siblings with
directory modules so rustc, rustfmt, and Clippy own each unit. Keep the
crate-facing migration APIs and durable receipt bytes unchanged. Name the
barrier host-path helper `host_fs` so it does not shadow `std::fs`.

Verified: cargo test --offline -p astrid-kernel --lib principal_home_migration
(8 passed); cargo test --offline -p astrid-kernel --lib legacy_migration_barrier
(23 passed).

AI-assisted: Codex (Grok 4.6) performed the module lift and focused tests.
I reviewed the resulting module boundaries and validation.

Signed-off-by: Joshua J. Bouw <[email protected]>
Turn the path-included workspace_* siblings into a directory module and
move the public branch-store API out of the leftover parent file. Keep
the crate re-exports and durable branch encodings unchanged.

Verified: cargo test --offline -p astrid-storage --lib workspace
(22 passed).

AI-assisted: Codex (Grok 4.6) performed the module split and focused
tests. I reviewed the resulting module boundaries and validation.

Signed-off-by: Joshua J. Bouw <[email protected]>
Give durable receipt fields validated NewTypes for schema, blake3
digests, and byte/entry/page counts. Keep the JSON shape identical so
existing receipts still deserialize, and reject empty, uppercase, or
prefixed inventory digests at the type boundary.

The crate-facing PrincipalHomeSourceIdentity snapshot remains
string/u64 for compatibility.

Verified: cargo test --offline -p astrid-kernel --lib
principal_home_migration (15 passed).

AI-assisted: Codex (Grok 4.6) added the typed receipt edge and focused
rejection tests. I reviewed the durable encoding and validation.

Signed-off-by: Joshua J. Bouw <[email protected]>
Move leftover path-included storage-migration files into the existing
invite and pair-token directories so rustc owns those modules normally.
Keep the crate-facing token APIs and durable encodings unchanged.

Verified: cargo test --offline -p astrid-kernel --lib invite (28 passed);
cargo test --offline -p astrid-kernel --lib pair_token (18 passed).

AI-assisted: Codex (Grok 4.6) performed the module lift and focused
tests. I reviewed the resulting module boundaries and validation.

Signed-off-by: Joshua J. Bouw <[email protected]>
Replace the path-included hosted open/reclaim/test files with a
directory module so rustc owns the hosted volume implementation
normally. Keep the HostedFileVolume contract and durable encodings
unchanged.

Verified: cargo test --offline -p astrid-storage --lib hosted
(14 passed).

AI-assisted: Codex (Grok 4.6) performed the module lift and focused
tests. I reviewed the resulting module boundaries and validation.

Signed-off-by: Joshua J. Bouw <[email protected]>
Give ledger source snapshots a validated digest and count pair so a
present source cannot carry digest `absent`, and an absent source cannot
carry a real digest or a non-zero inventory. Keep the durable JSON
fields unchanged.

Hosted path snapshots now accumulate counts in a private builder and
only construct SourceIdentity after the blake3 digest exists.

Verified: cargo test --offline -p astrid-kernel --lib
legacy_migration_barrier (27 passed).

AI-assisted: Codex (Grok 4.6) added the typed source identity and
focused rejection tests. I reviewed the durable encoding and validation.

Signed-off-by: Joshua J. Bouw <[email protected]>
Turn the remaining production #[path] siblings into ordinary directory
modules: durable format, durable cache, process-broker identity, and
admin env handlers. Keep crate-facing APIs unchanged.

Verified: cargo test --offline -p astrid-storage --lib durable
(165 passed, 3 ignored); cargo test --offline -p astrid-kernel --lib
storage_mount (16 passed). Five admin enforcement tests timed out under
parallel load and passed serially.

AI-assisted: Codex (Grok 4.6) performed the module lift and focused
tests. I reviewed the resulting module boundaries and validation.

Signed-off-by: Joshua J. Bouw <[email protected]>
Use schema Display and split count addition so Clippy does not treat
typed receipt helpers as dead on the library build.

Verified: cargo clippy --offline -p astrid-kernel -p astrid-storage
--all-targets --all-features -- -D warnings.

AI-assisted: Codex (Grok 4.6) fixed the dead-code surface after the
typed receipt refactor. I reviewed the resulting type API.

Signed-off-by: Joshua J. Bouw <[email protected]>
Keep `blake3:<hex>` source identities intact so distro-init discard
proofs still bind to the inventoried digest. Host-path snapshots remain
bare hex. Also move the snapshot constructor out of the barrier facade
so the module stays under the source cap.

Verified: cargo test --offline -p astrid-kernel --lib
legacy_migration_barrier (28 passed); cargo clippy --offline
-p astrid-kernel --all-targets --all-features -- -D warnings.

AI-assisted: Codex (Grok 4.6) diagnosed the published v0.10.4 upgrade
failure, preserved prefixed digests, and added a ledger-shape
regression. I reviewed the durable encoding and validation.

Signed-off-by: Joshua J. Bouw <[email protected]>
Store destination proofs as a validated transparent string so unknown
prefixes and newlines cannot enter the ledger, without rewriting durable
JSON. Keep blake3: prefixes intact so distro-init discard proofs still
bind. Drop leftover unused workspace imports and a redundant source
digest helper.

Verified: cargo test --offline -p astrid-kernel --lib
legacy_migration_barrier (33 passed); cargo clippy --offline
-p astrid-kernel --all-targets --all-features -- -D warnings.

AI-assisted: Codex (Grok 4.6) added DestinationProof, rejection tests,
and the small dead-code cleanup. I reviewed the durable encoding and
validation.

Signed-off-by: Joshua J. Bouw <[email protected]>
Re-snapshot each capsule env and secret path against the frozen ledger
identity immediately before import so a same-uid writer cannot swap
bytes in the boot window. Last-close now marks a projection closing
under the cache lock, refuses remount while teardown is in flight, and
treats a crashed provider as stopped only after the child is reaped and
the control endpoint is dead.

Verified: cargo test --offline -p astrid-kernel --lib
legacy_migration_barrier storage_mount process_stop (54 passed);
cargo clippy --offline -p astrid-kernel --all-targets --all-features --
-D warnings.

AI-assisted: Codex (Grok 4.6) implemented the two GLM AMENDs and
regressions. I reviewed the fail-closed import and teardown paths.

Signed-off-by: Joshua J. Bouw <[email protected]>
Apply cargo fmt to the DestinationProof helpers so CI format check
matches the local rustfmt pass.

Verified: cargo fmt --all -- --check.

AI-assisted: Codex (Grok 4.6) applied rustfmt. I reviewed the
formatting-only diff.

Signed-off-by: Joshua J. Bouw <[email protected]>
@joshuajbouw
joshuajbouw merged commit 3f82d81 into main Aug 19, 2026
37 checks passed
joshuajbouw added a commit that referenced this pull request Aug 20, 2026
## Linked Issue

Closes #1561

## Summary

Rewrite of the owner-scoped KV hot cache and single-sync transaction WAL
onto post-#1535 `AstridVolume`. The previous `codex/hot-kv-read-cache`
commits conflicted with the owned-filesystem cut; this head is a new
implementation on current `main` (`3f82d81e`) that keeps the issue's
semantics: bounded conditional batches, governed hot reads, one WAL sync
per accepted group, and committed state served from a pending overlay
before canonical arena/root fold.

WAL bytes live in the `transactions.wal` volume region rather than a
host `PathBuf`. New WAL publication is opt-in (`TransactionWalPolicy`;
default remains the legacy arena-then-root path). Recovery still replays
an existing WAL even when new writes are disabled. The existing KV batch
API is reused rather than duplicated.

This replaces the conflicting pre-#1535 draft on this PR number. Head
SHA: `a4e52546`.

## Changes

- Owner-scoped point-read cache (`KvReadCacheConfig` /
`KvReadCacheCapacity`), disabled unless an embedding opts in and
reserves charge
- Streaming ASTWAL2 grammar, writer, scan, replay, and pending overlay
under `engine/durable/wal/`
- WAL publication through `DurableEnginePolicy::with_transaction_wal`;
WAL file is a volume region (`transactions.wal`)
- Recovery, snapshots, usage, staging, compaction, and close observe or
drain pending WAL state
- Canonical object/root formats, quota accounting, one-owner rejection,
and unsupported-backend fallback unchanged
- Changelog entry under `[Unreleased]`

## Verification

- `cargo test -p astrid-storage --lib --locked` — 746 passed (storage
library suite on this head)
- `cargo fmt --all -- --check`
- `git diff --check`

**Not re-run on this rewrite:** the original SurrealKV exact-durability
comparison (~0.509x to ~0.947x of SurrealKV on the development machine).
That measurement belonged to the pre-#1535 branch. This PR preserves the
cache/batch/WAL semantics and ships the volume-backed rewrite; it does
not claim a fresh SurrealKV number until that bench is re-run against
`AstridVolume`.

## Test Plan

- `cargo test -p astrid-storage --lib --locked`
- `cargo clippy -p astrid-storage --all-targets --all-features --locked
-- -D warnings`
- Focused WAL / overlay / crash-replay / hot-cache / batch tests under
`crates/astrid-storage`
- CI: Test (macos/ubuntu), Clippy, MSRV 1.95.0, Wasm portability, Public
API diff

## AI / Tool Assistance

Assisted-by: OpenAI Codex: Grok 4.6

Codex reimplemented the cache and WAL overlay against `AstridVolume` in
an isolated worktree (`/tmp/astrid-1562-volume-wal-cache`), including
tests and the changelog entry. Human owns review, merge, and any
re-benchmark against SurrealKV.

How it was reviewed:

- Semantics of #1561 were treated as frozen: one-owner batches,
overlay-before-fold, explicit WAL versioning, opt-in publication.
- The previous PR commits were not cherry-picked; this is a rewrite
because #1535 changed the durable file model.
- Performance numbers from the old branch are **not** restated as
evidence for this head.

## Checklist

- [x] Linked to an issue
- [x] CHANGELOG.md updated (entry under `[Unreleased]`)
- [x] I understand every change in this PR and can explain its design,
risks, and validation.
- [x] I reviewed and tested any meaningful tool-generated output
included in this PR.
- [x] Every non-bot, non-merge commit has a matching `Signed-off-by`
trailer.

---------

Signed-off-by: Joshua J. Bouw <[email protected]>
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.

storage: establish layout v2 migration and mount command boundary

2 participants