# Benchmarking the durable store
The `store_backend` benchmark (`cargo bench --features bench`) measures the three metrics a future
log-structured backend would be compared against for the file backend: whole-log read latency
(`list_events`), single-append latency, and on-disk amplification. The synthetic groups
(100 / 1k / 10k events) are generated in-process and need nothing external — anyone can run them, and
they carry the portable baseline.
## Foundation workload smoke
The `store_foundation` target freezes two backend-neutral qualification workloads before any
alternative store is implemented:
- `synthetic-legacy-shape` is a small public fixture that exercises legacy event, object-artifact,
and note-body records.
- `modeled-foundation-workload` covers root and replacement generations, continuation, every
relation-proof status, every supported fact-port relation, relation-proof content, auxiliary
documents, and multi-round artifact growth.
Run its non-timing smoke mode with:
```sh
cargo bench --features bench --bench store_foundation -- --smoke
```
The target prints one JSON record containing build identity, a Cargo lockfile hash, Rust version,
OS, filesystem, configuration, logical capabilities, and manifest hashes/counts. It does not select
or time a storage implementation.
An optional versioned external workload must be a separately supplied read-only copy:
```sh
export POINTBREAK_QUALIFICATION_CORPUS=/path/to/external-corpus-copy
cargo bench --features bench --bench store_foundation -- --smoke
```
Never point this variable at a live Pointbreak store. The loader rejects source-tree paths and
symbolic links, reads only `events/`, `artifacts/objects/`, and `artifacts/notes/`, and emits only
hashes, counts, byte totals, and sanitized status. It never prints the supplied path or record
bytes. When the variable is absent, the public workloads still validate and the external row is
reported as `not_configured`.
The current external workload contains 6,706 files totaling 58,212,172 decoded bytes. Its manifest
carries 6,702 logical workload records (6,392 events, 309 object artifacts, and one note body;
58,210,604 decoded bytes). The loader separately checks the four store-metadata files and their 1,568
bytes without reading their content, then verifies the versioned manifest hash. Any logical, metadata,
or manifest mismatch fails closed. The earlier 6,437-file frozen-legacy workload and its loader remain
available only for reproducing historical reports; it is not relabeled as the current workload.
## Plain LMDB build-closure proof
The non-default `lmdb-proof` feature compiles a source-only, developer-gated LMDB closure. It pins
the reviewed heed3 wrapper and upstream `mdb.master3` native source, uses no wrapper, native,
encryption, bindgen, sanitizer, Valgrind, or alternate-key-size features, and links the native
`liblmdb.a` archive statically. It does not select a store, read a Pointbreak store, route production
records, or enable encryption.
Validate the embedded closure contract and exercise one plain open/close against a disposable
directory with:
```sh
cargo bench --locked --features bench,lmdb-proof --bench store_foundation -- \
--lmdb-proof-open-close
```
The JSON report records the exact wrapper and native source commits, linked LMDB version, plain and
encrypted status, dynamic-host-dependency status, and the disposable carrier filenames. The focused
LMDB closure tests fail closed if the source trees, build inputs, generated bindings,
licenses/notices, feature set, release target matrix, or default-package exclusion drift from
`vendor/lmdb-proof/closure.json`; they run in the default test suite. The portable open/close command
validates the embedded structural contract without requiring a source checkout at runtime. The proof
sources are excluded from default Cargo packages and release archives; default builds do not resolve
or compile heed3 or LMDB.
The native tree retains two ordered, hash-bound source corrections over the immutable LMDB commit:
an explicit byte-pointer cast required by MSVC and the `SYNCHRONIZE` process access required before
Windows can test whether a retained process object has exited. Failed process opens and failed waits
remain conservative and never establish that a reader is dead.
The same feature contains a plain qualification-only journal/profile core with physical identity
`qualification-lmdb-plain-v1`. It uses one journal database, versioned metadata and value envelopes,
default durable commits, exact create-once retries, deterministic byte-ordered replay, and independent
content carriers. Its fixed map policy starts at 16 MiB, grows in 64 MiB increments under a
cross-process resize lock, stops at 256 MiB, and permits at most four resize attempts. Those values are
derived from the public 64 MiB G2 ceiling and reserve four times its decoded bytes; they are not tuned
from candidate timings.
Run its non-timing G0 semantic and receipt smoke against a fresh disposable root with:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS
cargo bench --locked --features bench,lmdb-proof --bench store_foundation -- --lmdb-smoke
```
The smoke emits no timing samples or feasibility verdict. It verifies create-once journal writes,
sorted replay, exact decoded hashes, the oldest/middle/newest/absent read schedule, and the deterministic
head marker.
Run the separate non-timing lifecycle smoke with:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS
cargo bench --locked --features bench,lmdb-proof --bench store_foundation -- \
--lmdb-lifecycle-smoke
```
This mode uses deterministic process barriers and only generated public inputs in disposable roots.
It proves that a pinned reader retains its old snapshot while later writers commit, clears a dead
reader slot without evicting a live reader, and keeps the fixed reader-retention workload within a
16 MiB native-allocation bound. After the reader is released, an additional fixed write cohort may
grow native allocation by at most 2 MiB; ordinary page reuse satisfied that predeclared bound. These
are lifecycle bounds derived from the fixed map and workload, not feasibility thresholds.
Backup uses heed3's ordinary online-copy primitive with compaction disabled; it never copies a live
`data.mdb` through filesystem APIs. Candidate and independent-content carriers are published through
the shared backup manifest contract, and the completion marker is written last. The smoke overlaps an
online copy with a writer cohort, accepts only an exact coherent cohort prefix, rejects interrupted or
incomplete destinations, restores in a fresh process without changing the backup, and repairs by
replaying validated logical truth into a fresh copy. Restore and repair both compare the exact
database/content carrier-set identity as well as profile, head, journal, and content receipts. Repair
never replaces an open environment or modifies source carriers in place.
The report schema is `pointbreak.qualification-lmdb-lifecycle-smoke.v1` with report mode
`non_timing_lifecycle_receipts`. It serializes exact receipt hashes and sanitized inventory only:
carrier classes, counts, set hashes, encoded bytes, and native allocated bytes. The exhaustive classes
are database, lock, resize lock, independent content, copy, temporary, obsolete, pinned, repair, and
sidecar. Native allocation uses filesystem allocation metadata and excludes the virtual map
reservation. Separate steady, reopened, and all-carrier high-water snapshots use the shared sanitized
inventory document. Every owned class remains explicit even when the engine has no distinct carrier for
it; for example, reader-pin state is proven by the lifecycle receipt and LMDB lock carrier, so the separate
`pinned` class has a zero count rather than invented bytes. Runner barrier/request/result files are control
evidence, not candidate storage carriers. Windows runs additionally require open-handle replacement to fail while mapped,
succeed after close, reopen exactly, and clean interrupted-copy carriers. The mode emits no timing
samples, performance evaluation, feasibility verdict, selection, migration, or production routing.
## Generated public scale workloads
The foundation target also owns three public, versioned scale workloads. They are generated in
process and do not read an external corpus, a Pointbreak store, the filesystem, environment paths,
the clock, locale state, or operating-system randomness.
| `G0` | 128 | 1,048,576 | 4 | `5dd08fab4e371f90f9de401ea78c6e281d442627967a3a16db55f724eb32c928` | `b35ebf4bd7bf09a40133e2066cce43cb901a07bf06d5b1caa0f4881bdad27595` | `8f2c69c54a1ea590d05c139cc5405a3e3081be1c9ca50278e3a5ec03df8f788b` |
| `G1` | 1,024 | 8,388,608 | 8 | `9a4b6c1ef8363866005d47860206f94f089a0ad0e2b0e89471dd7254098d368a` | `f520817b751d672810bd8fbe842bb2983b5ff437cce1ad4db3341d79c9b4bf4f` | `a8a094aee8b4154d1c6d1c8c1dcf82f1bf2ecd12d22d4d8ffa4391960e1c0f58` |
| `G2` | 8,192 | 67,108,864 | 8 | `d19e86ed2ca9c0ccc03c1356d721216d3a8a9cba0c49ce19c29c3d52fc1a567c` | `295240840539fbd500796d0cd125d3c1e5266cb61a9feba4aeab2a4d0c2c9158` | `e9f0e9e983873c5251b2ca401718e0ae2bfbde32a046c31b6ece7295c88199a9` |
The canonical generator schema is `pointbreak.qualification-workload-generator.v1`. Its public
seed is
`f4da49601a212010bae444e6ca2de6c6bf28b5ec1b0a05bf42154a533ca513ff`.
Every deterministic decision uses domain-separated counter expansion:
```text
Each tier repeats the same eight decoded-size bins—512, 1,024, 2,048, 4,096, 8,192,
12,288, 16,384, and 20,992 bytes—so every eight records total exactly 65,536 bytes. Records
cycle through low, medium, and high compressibility padding and all nine public record kinds. They
also cover root-only, root-to-replacement, continuation, forked-replacement, carried-open,
resolved, removable-content-present, removed-content-absent, and restored-from-backup lifecycle
motifs. Each record kind and lifecycle motif occurs at least once in every tier.
Logical keys are lowercase portable ASCII and are sorted by their raw UTF-8 bytes before manifest
hashing. Exactly 50% use a digest-uniform shape, 25% use one long common prefix with independent
suffixes, and 25% use cohort-prefixed ordered suffixes. Record ordinals are divided into contiguous,
equal-width logical-age cohorts. The operation schedule selects distinct existing records from the
oldest, middle, and newest cohorts plus one independently derived absent key. Its 30 unique append
indices address the canonical sorted manifest, not host directory order.
Generation has a collected API for bounded consumers and a streaming API that retains key/ordinal
plans but no payload collection. The streaming path buffers one generated record at a time and
computes the same canonical `pointbreak.qualification-corpus.v1` hash incrementally. The repository
commits only the small identity fixture, not generated record bytes.
Regenerate all three public identities without timing or candidate mutation with:
```sh
cargo bench --features bench --bench store_foundation -- --generated-workload-smoke
```
The command emits only the canonical generator, seed, spec, manifest, schedule, count, byte, and
declared-coverage summaries. The JSON omits runtime identity and external-corpus fields so the same
source emits byte-identical output on macOS, Linux, and Windows. `G3` is not an executable workload
in this target.
## Longitudinal access contracts
The bench-gated longitudinal surface freezes two disjoint, public-input-only contracts before any
root materializer or evidence runner exists. `pointbreak.longitudinal-workload.v1` retains the
1,024/7,168/25,600/102,400-event product-operation workload and its proposed envelopes.
`pointbreak.longitudinal-capacity-sentinel.v1` separately defines the 10,000-object L100 variant,
required 262,144-event capacity sentinel, gated 524,288-event extension, fixed-output probes,
memory ownership fields, and bounded two-writer/one-reader exercise. Companion rows never pool
with or substitute for the product-operation workload.
Print both canonical contracts without constructing a root, reading private input, or collecting
timing, memory, or counter observations:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS POINTBREAK_BENCH_FIXTURE POINTBREAK_BENCH_REPO
cargo bench --locked --features bench --bench store_foundation -- --longitudinal-contract
```
The contract records exact release/debug/counting lane separation, retained samples, nearest-rank
statistics, semantic receipts, manifest and pair identity, attribution fields, package boundaries,
capacity gates, and non-compensation. Fast wall time cannot turn whole-history fixed-output work
into bounded work. Exact audit, export/import verification, migration, repair, backup/restore
verification, removal/compaction reconciliation, and deliberate rebuild retain their explicit
history-proportional allowance.
Contract-only package validation derives the C262 identity-complete gate input from the included
materialization pair. Package-verification completion and host-pressure clearance remain hash-bound
observations that the later raw-evidence verifier must derive; this publication does not infer them.
List the currently available longitudinal modes and their side-effect boundary with:
```sh
cargo bench --locked --features bench --bench store_foundation -- --longitudinal-help
```
The public surface also provides a disposable, non-timing mechanics check:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS POINTBREAK_BENCH_FIXTURE POINTBREAK_BENCH_REPO POINTBREAK_HOME
just longitudinal-smoke
```
It creates two temporary public `L1` roots, proves their pair identity, closes and strictly
reopens both roots, checks complete carrier/content/state/projection receipts, and exercises raw
inventory hashing. Its receipt states that timing and terminal-evidence use are inadmissible.
Completed native packages are verified read-only with:
```sh
just longitudinal-verify-package /absolute/path/to/completed-package
```
The verifier requires exactly one workload or capacity package document, validates its typed
revision/lane/gate relationships, recursively hashes every inventoried raw file, rejects extra or
missing files, and never regenerates evidence. The frozen operator command may add only
`package-receipt.json`, an exact typed copy of the already-verified package; later verification
checks that sidecar for equality and excludes it from the immutable raw inventory. Native
materialization and collection are deliberately
absent from routine recipes: an external operator must use the frozen explicit command ledger and a
clean exact source revision. The public façade refuses existing, protected, synchronized, non-local,
dirty, mixed-identity, or protected-environment destinations. Neither the smoke nor the verifier
selects storage, reads external store data, migrates a store, changes production routing, or makes an
architecture verdict.
The bench-gated builder keeps fresh and resumed construction distinct.
`materialize_longitudinal_workload_v1` and `materialize_longitudinal_capacity_v1` remain
create-all entrypoints. An explicit operator ledger may instead call
`resume_longitudinal_workload_v1` or `resume_longitudinal_capacity_v1` for an interrupted or cloned
public fixture. Resume accepts only exact existing records, requires the complete frozen final
state, and binds pre/post store-data inventories plus exact Created/Existing counts. The separate
materializer-equivalence verifier compares complete store bytes and strict semantic receipts while
binding—rather than equating—the two execution identities and the implementation-diff hash.
Immutable roots may be reused under a corrected execution identity only through the versioned
carry-forward surface. The operator first creates an isolated clone, then supplies a
`pointbreak.longitudinal-carry-forward-request.v1` document containing the source and clone paths,
a new authority-output path, the original materialization receipt, the corrected execution, the
scheduled tier/lane/run slot, and the accepted materializer-equivalence receipt:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS POINTBREAK_BENCH_FIXTURE POINTBREAK_BENCH_REPO POINTBREAK_HOME
cargo bench --locked --features bench --bench store_foundation -- \
--longitudinal-carry-forward \
--longitudinal-carry-forward-request=/absolute/path/to/request.json
```
The command reads both data roots strictly, rejects aliases or any byte/semantic/contract/schedule
drift, and writes only to the new authority-output directory. It emits the carried materialization
first and `carry-forward-receipt.json` last. The carried manifest changes only the execution
identity and its dependent canonical hash; the source manifest and both store roots remain
unchanged. A disposable public check exercises these rules without admissible timing or terminal
evidence:
```sh
cargo bench --locked --features bench --bench store_foundation -- \
--longitudinal-carry-forward-smoke
```
After collection, derive a typed verifier receipt rather than asserting verification in controller
state:
```sh
cargo bench --locked --features bench --bench store_foundation -- \
--longitudinal-verify-package-receipt \
--longitudinal-package-root=/absolute/path/to/completed-package
```
The final `pointbreak.longitudinal-carry-forward-authority-package.v1` must contain all twelve
scheduled v1 carry receipts and a matching parsed workload-package verification receipt. Release
source slots require `buildProfile: "release-uninstrumented"` and debug source slots require
`buildProfile: "debug-uninstrumented"`. Source executions must be identical within a lane and share
all non-runner, non-profile identity across lanes. The corrected execution and final authority diff
must be identical across all twelve slots; the final diff must also equal every embedded
materializer implementation diff. Each tier's three slots must embed one exact equivalence receipt,
and every tier must bind the same equivalence baseline and successor executions. Verify that
binding with:
```sh
cargo bench --locked --features bench --bench store_foundation -- \
--longitudinal-verify-carry-forward \
--longitudinal-authority-package=/absolute/path/to/carry-forward-authority-package.json \
--longitudinal-package-root=/absolute/path/to/completed-workload-package
```
Controller failures use a separate typed receipt with only an operation selector, HTTP
status/body classification plus length/hash, Inspector exit classification, and sanitized stderr
classification plus length/hash. Raw response bodies, stderr, paths, environment values, tokens,
or payload bytes have no serializable field in that contract. The pre-existing evidence-package
failure entry remains a short immutable reason classifier plus a detail hash; new controller
failures bind that detail hash to the separately persisted typed receipt instead of placing
diagnostic text in the package.
Before allocating a longitudinal evidence root, build the product release and debug binaries, the
benchmark controller, and any external evidence driver with mutually disjoint `CARGO_TARGET_DIR`
values. Freeze and hash each executable before materialization so a later Cargo build cannot replace
one lane's artifact with another lane's feature set or profile.
## Loose-profile baseline evidence
The foundation target has a candidate-independent loose-profile runner. Its evidence document uses
the schema `pointbreak.qualification-loose-baseline-evidence.v1` and cannot represent a candidate,
comparison, threshold, or verdict. It measures the current loose representation directly; the output
is observational input for a later replacement contract, not a storage decision.
Run a native evidence shard from a clean exact commit on a quiesced host with:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS
export POINTBREAK_QUALIFICATION_QUIESCED=1
cargo bench --features bench --bench store_foundation -- --loose-baseline-evidence
```
The runner uses only disposable roots and the frozen public generator. `G0` is a diagnostic row;
`G1` and `G2` are baseline rows. Every workload gets three warm-up iterations, 30 measured
iterations, and two independently prepared roots. All raw samples are retained and no outlier is
removed. There is deliberately no pass/fail evaluator.
Each measured root records durable append, strict replay, fresh-process open/recovery, and separate
oldest, middle, newest, and absent keyed reads. Every sample carries a sanitized semantic receipt.
Raw durations cover the verified operation rather than bare I/O: the timed window includes the
semantic verification needed to prove the receipt, and open/recovery includes child-process startup
and teardown. A later comparison must use the same operation windows.
Allocation inventories cover event and complete-profile scopes in steady, reopened, and high-water
states using the same native allocation APIs as the existing qualification runner:
`stat(2)` blocks on APFS/ext4 and `FILE_STANDARD_INFO.AllocationSize` on NTFS.
The evidence validator binds the source commit, `Cargo.lock`, generator schema and seed, workload
specification, manifest and operation schedule, platform, filesystem, allocation API, independent
run, operation, read class, receipt, and allocation inventory. Output retains aggregate receipt and
carrier-set hashes, counts, byte totals, and raw durations. It cannot serialize disposable paths,
environment values, payloads, logical keys, record-level hashes, or error text.
For a quick correctness check, use the non-timing mode:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS
cargo bench --features bench --bench store_foundation -- --loose-baseline-smoke
```
The smoke document uses `pointbreak.qualification-loose-baseline-smoke.v1`. It exercises `G0`, all
four operation families, all four keyed-read classes, both allocation scopes, and all three inventory
states without serializing timing samples.
Both documents also expose the value-free
`pointbreak.qualification-prospective-contract-proposal-shape.v1` checklist. The checklist requires
the later proposal to cover operation-specific absolute ceilings, relative allowances, small-baseline
guard bands and their combination formula; small-store overhead and peak headroom; the first public
crossover; event and complete-profile savings at `G1`/`G2`; steady, reopened, and high-water states;
high-water amplification and maintenance duration; `P0`/`M0`/`G0`/`G1`/`G2` roles; manifests, seed,
generator version, schedule, and the verified-operation timing-window definition; platform,
filesystem, and allocation rules; independent keyed-read classes; external evidence authority;
provenance and privacy; and causal early stops. It names those fields only—it contains no proposed
numeric values or evaluator.
## Content-only APFS falsifier contract
The candidate-independent content-only contract is compiled into the benchmark target as
`pointbreak.qualification-content-only-contract.v1`. Its canonical SHA-256 is
`77ce55dd47363bc924d0612c3b508db92bd7969a0ca9bac8d9c7e096e985f654`. Print the contract and its
generated decision table without constructing a candidate, reading a corpus, or collecting timing or
allocation observations:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS
cargo bench --features bench --bench store_foundation -- --content-only-contract
```
| Profile | `qualification-loose-journal-pbrf-content-v1` |
| Physical profile ID | 3 |
| Logical capability epoch | `pointbreak.foundation.v1` |
| Events | unchanged raw loose carriers and receipt; byte-equal to loose; 0 bps informational only |
| Content | one PBRF v1 carrier per logical key across object, note, relation-proof, document-manifest, and document-blob |
| Content codec | 192-byte PBRF v1 header; adaptive raw or zstd level 1; checksum and pledged decoded size; no dictionary or trailing bytes |
| Publication | complete same-directory temp, durable create-once, cleanup, and parent-directory durability; retry compares decoded kind, key, and bytes |
| Public workloads | G0 admission, then G1 allocation; frozen manifests and schedules |
| Native platform | macos/apfs via `stat_blocks_512` |
| Independent runs | exactly [0, 1] |
| Allocation states | steady, reopened, high-water; each gates independently |
| Complete-profile floor | at least 1000 basis points in every run/state; no pooling or reruns |
| G0 | every named semantic, lifecycle, transfer, repair, migration, privacy, provenance, and inventory row passes |
| Package admission | macOS aarch64, macOS x86_64; required only for aggregate pass |
| Meaning | bounded content-only APFS falsifier; no timing, recovery-speed, physical-profile selection, migration, activation, or rollout claim |
Every named G0 row, each of the two native APFS G1 runs, and every steady, reopened, and high-water
complete-profile allocation row gates independently. A missing row evaluates as `unknown`; a present row
below the 1,000-basis-point floor evaluates as `failed`. Rows are never pooled, averaged, discarded, or rerun.
The unchanged `events/` carriers and semantic receipt must be byte-equal to loose; their reported saving is
always zero and informational, not a journal qualification criterion. Default-package evidence for both macOS
release architectures is required only for an aggregate pass and cannot rescue an earlier failure.
Evidence and packages bind clean source and tree, `Cargo.lock`, contract, profile, codec and runner sources,
frozen public G0/G1 manifests and schedules, native platform, run index, row identities, and canonical hashes.
Configured private-corpus input and stale, mixed, duplicate, unsupported, or hash-mismatched inputs are
rejected before evaluation. The publication contains no candidate
measurements or observed APFS results, and the contract makes no timing or recovery-speed claim. It does not
select or route a physical profile, authorize migration or activation, or expand qualification beyond this
bounded APFS falsifier.
## Derived-access product-integration contract
Pointbreak retains this historical contract for the source cut that first evaluated
`sqlite-wal-bodyless-v1` in normal product paths. That qualified source cut was off by default:
```sh
unset POINTBREAK_DERIVED_ACCESS
# Equivalent explicit value:
export POINTBREAK_DERIVED_ACCESS=off
```
The authoritative current runtime posture is the derived-access rollout contract below. This historical
contract and its hash are intentionally unchanged. Only `off` and `sqlite-wal-bodyless-v1` are valid. Unknown or
non-Unicode values are errors. The normal Pointbreak library and binary build the bundled
`rusqlite`/`libsqlite3-sys` closure so the profile
can be exercised without a developer feature. That compilation and package cost is present even while the
selector is `off`. The profile implementation is owned once under `session::derived_access::sqlite`;
qualification adapters and active product routes call that same core. Selecting the active profile for
`pointbreak inspect` starts an asynchronous rebuild of the private disposable sidecar when no current
generation exists. The Inspector shell remains available while derived routes report their typed
availability, and the routes begin serving from the immutable generation after publication. A running
Inspector joins a rebuild already owned by another process and requests a fresh rebuild when an out-of-band
writer advances authoritative truth; neither case requires restarting the Inspector. This does not migrate
truth. The historical default decision described here is not the current selector.
`RebuildBusy` waits for the other process to publish, while rebuilds invalidated by changing truth retry with
capped exponential backoff. Normal governed `CatchingUp` remains an in-place bounded-delta state and never
starts a competing full rebuild. If the worker thread cannot be spawned, Inspector logs the failure and keeps
the shell available so a later request can retry. The Inspector owns its local worker handle: cancel, retry,
and orderly server-state shutdown cooperatively interrupt the worker at bounded progress/retry boundaries and
join it. Explicit cancellation stays latched until retry, so status polling cannot silently restart the worker.
A cancelled in-progress candidate is discarded; stale staging from an abrupt interruption is discarded when
the next rebuild begins. Once the completion-last publication critical section begins, publication wins and
the join returns the new current state. Abrupt process termination remains a crash.
`GET /api/derived-access/status` is the generation-independent recovery document. It returns `200` with
schema `pointbreak.inspect-derived-access-status`, version `1`, including availability, current readability,
worker/fallback activity, the local rebuild-pause latch, detail, allowed actions, and any durable
phase/event/byte/time progress. A valid old
generation may remain readable while a replacement stages; any authority-stamp drift invalidates that option.
`POST /api/derived-access/cancel` and `/retry` are the only mutating Inspector routes and affect only the
disposable sidecar worker.
First bootstrap never silently switches read models. The web client offers wait or the explicit
`access=authoritative` selector. That selector runs existing authoritative domain readers with request-local
ownership, does not populate the retained history cache or shared revision-summary cache, carries
`X-Pointbreak-Access-Source: authoritative-fallback`, and is serialized by one service-wide permit. A
concurrent fallback receives `429` instead of multiplying whole-history replay. The web client also queues its
own collection, paging, polling, and detail fallbacks so its requests do not race each other for that permit.
Default-off continues to use authoritative reads as its primary path and is not labeled fallback.
Print, verify, and smoke the contract without opening a store or performing filesystem actions:
```sh
just derived-access-product-contract
just derived-access-product-contract-verify
just derived-access-product-contract-smoke
```
The product service has an observed physical-access probe at its profile boundary. Resolving `off` records
zero root-resolution and SQLite-open actions and does not stat, create, open, or quarantine a derived path.
An explicit `sqlite-wal-bodyless-v1` resolution records a successful root resolution and only successful
physical SQLite component opens; a missing sidecar therefore records no phantom SQLite open before its
background rebuild begins. The store-scoped rebuild lease deduplicates concurrent Inspector processes.
Unset or explicit `off` startup still performs no sidecar path or SQLite action.
The compiled schema is `pointbreak.derived-access-product-integration-contract.v1`; its canonical SHA-256
is `3afe3a1fd65f0d5c58246dbe426c35a32325dc42bd9931d78f0e2354411dd00d`.
| Selector | `POINTBREAK_DERIVED_ACCESS=off|sqlite-wal-bodyless-v1`; default `off`; unknown/non-Unicode values fail |
| Authority | loose `Journal` and `ContentStore` carriers remain the only truth; active state is private, bodyless, disposable, and rebuildable |
| Availability | `absent`, `bootstrapping`, `current`, `catching_up`, `rebuild_required`, `quarantined`, `unavailable`; `current` requires exact observed coverage |
| Version wire | preserve `eventSetHash` on loose responses; active responses require cursor-derived `projectionStamp` and may omit the deprecated `eventSetHash` |
| Stamp identity | store identity + profile + schema version + epoch + applied sequence; changes on every unique event and rebuild epoch; never truth/signature identity |
| Ordinary work | fixed-output routes are bounded-selected; complete collections are output-proportional; only body search is history-proportional |
| Fallbacks | cheap freshness detector, typed unavailable responses, intentional exhaustive body search, and instrumented exact-detail fallback; every invocation has a request receipt |
| Resource gate | L100 steady RSS at most `128 MiB`; zero full-history hydrated cache bytes; startup paired to measured default-off baseline; shell/status available during rebuild |
| Matched operations | retain the qualified L100 wall/CPU comparison ceilings without creating a release promise; product-only actuals remain paired to loose |
| Stop boundaries | no physical module, sidecar, active product route, production default, migration, production activation, or release |
The active response version is deliberately named `projectionStamp`, not `eventSetHash`. It binds store
identity, profile, schema version, rebuild epoch, and applied sequence. It changes on each acknowledged
unique event and every rebuild epoch, but it is neither truth identity nor a signature input. Existing loose
responses retain `eventSetHash`; consumers transition compatibly by preferring `projectionStamp` when
present and otherwise using `eventSetHash`.
The frozen product route matrix permits a cheap authoritative freshness detector, typed unavailable
responses, an instrumented bounded exact-detail fallback, and one intentional exhaustive fallback for body
search. Every fallback and unavailable response emits request-scoped counters. Ordinary active routes may
not list, decode, fold, sort, hash, or retain complete history merely to preserve a version wire.
Inspector exact revision detail deliberately scopes diagnostics to the addressed revision's supersession
component and its authoritative support carriers. The default-off path still scans truth to retain the
complete `eventSetHash` and `eventCount`, but unrelated store-wide warnings do not repeat on every detail
page. The CLI `pointbreak revision show` remains the store-audit surface and continues to report store-wide
diagnostics. Both Inspector modes use the same component closure: revision facts, removals of content those
facts reference, and detached signatures over those facts or removals.
## Derived-access production-readiness contract
The additive production-readiness contract freezes the gates that must pass before
`sqlite-wal-bodyless-v1` can be considered for a separate default decision. It does not implement the
filesystem authority stamp, change product routing, rebuild a store, collect evidence, or authorize a
default change. The existing product-integration contract remains its frozen parent.
Print, verify, and smoke the contract without opening a store or running retained-scale work:
```sh
just derived-access-readiness-contract
just derived-access-readiness-contract-verify
just derived-access-readiness-contract-smoke
```
The compiled schema is `pointbreak.derived-access-production-readiness-contract.v1`; its canonical SHA-256
is `5445781aadff791537746f1596f577ea1415fd37daf6d0da4fbc0ded94375eb3`. The embedded canonical fixture
SHA-256 is `b2e2656f6f37a1173bbeb7ce9101e1c703d03b600468fc4b62fb2dc25a05ab6a`.
| Identity | exact profile, parent/readiness contract, source commit/tree, Cargo.lock, binary, OS/architecture/filesystem, root manifest, and evidence-package identities; parent `3afe3a1fd65f0d5c58246dbe426c35a32325dc42bd9931d78f0e2354411dd00d` |
| Authority | `selected_and_frozen_by_native_falsifier_before_integration` selects and freezes the observable before integration; each scenario names its mutation locus; observation opens at most `0` carriers and walks at most `0` event entries; changed/indeterminate never proves truth: `true`; every mismatch fails closed; existing-carrier overwrite remains a validation/audit non-claim |
| Ordinary work | active no-change fixed-output routes walk at most `0` event-directory entries and fresh writer admission walks at most `0`; audits, bootstrap, fallback, default-off comparison, and body search remain explicitly classified |
| Bootstrap | preflight → population → strict_oracle_verification → authority_stability_check → publication; population carrier-open ceiling `1` per input and maximum `1` overlapping complete decoded histories; strict oracle serial/isolated: `true`; completion published last: `true` |
| Bootstrap availability | status/progress fields `phase, completed_events, total_events, elapsed_milliseconds` required and `completed_bytes, total_bytes, eta_milliseconds` optional; maximum automatic fallbacks `1`; long unexplained absent allowed: `false`; no availability case may serve stale as current: `true` |
| Revision pages | `pointbreak.inspect-revisions-page.v1`; absent limit uses default `100`: `true`; maximum `500` with over-maximum `invalid_request`; requested entries mean the accepted limit: `true`; normalized `(capturedAt, revisionId)` descending so page one contains current work; opaque snapshot-bound token; revision count comes from `derived_indexed_aggregate`; active work `output_proportional`; default-off same shape through `history_proportional` |
| Qualification | required completion-last, read-only verified gates: `native_macos_apfs_d0_l7, native_windows_ntfs_d0_l7, package_closure, rollback_and_backup, retained_l100_apfs, retained_c262_apfs, evidence_authority`; parent contract `3afe3a1fd65f0d5c58246dbe426c35a32325dc42bd9931d78f0e2354411dd00d` and all of its gates and matched-operation ceilings remain load-bearing |
| Retained inputs | tiers `L100, C262`; identity-verified read-only: `true`; rematerialization authorized: `false`; preserve sources/outputs: `true`; C524 admitted: `false` |
| Timing | this readiness contract adds no host-sensitive numeric wall-time thresholds; the parent contract's matched-operation wall/CPU ceilings still apply; counter, semantic, lifecycle, native, and evidence-authority gates decide readiness |
| Outcomes | `ready_for_default_decision`, `remain_default_off`, `reject`; all unknown outcomes match: `true` (`remain_default_off`); production default change authorized: `false` |
| Protected boundary | `owner_store`, `private_corpus`, `private_snapshot_bytes`, `qualification_corpus`, `credentials`, `installed_artifacts`, `installed_extension_dogfood_evidence`, `remote_mirror_automation_state`, `archived_evidence`, `external_participant_evidence`, `production_default`, `deferred_content_format_experiment`; physical implementation: `false`; evidence collection: `false`; migration: `false`; release: `false` |
The page contract uses normalized `(capturedAt, revisionId)` descending order and adds an opaque
continuation token bound to the profile, page schema, observed snapshot, and ordering cursor. An absent
`limit` means `100`; a value above `500` is an invalid request. The counter's requested-entry value is the
accepted limit. Active mode may examine at most `limit + 1` revision rows to produce a page and continuation
decision; it may not materialize the complete collection. Its `revisionCount` comes from a derived indexed
aggregate rather than the examined rows. Default-off returns the same page shape, but its existing
whole-history projection remains an explicitly exhaustive authoritative comparator and is never credited as
bounded work. Exact revision detail remains an independent entity-primary read.
The readiness evaluator requires one result for every frozen gate, including one result proving that all
parent product-integration gates and matched-operation limits passed. A failed correctness, native-authority,
pagination-integrity, lifecycle/package, rollback, protected-input, or default-posture gate rejects the exact
product shape. Other failed or unknown operational/evidence gates kept it default-off. Only a complete
passing matrix yielded `ready_for_default_decision`, which required the separate rollout decision recorded
below before the configuration default changed.
## Derived-access default rollout contract
Unset `POINTBREAK_DERIVED_ACCESS` now selects `sqlite-wal-bodyless-v1`. Explicit
`POINTBREAK_DERIVED_ACCESS=off` remains the immediate, artifact-free rollback. An absent or unusable
generation never blocks authoritative reads or writes: Inspector starts one asynchronous build, bounded CLI
reads use loose truth with one actionable hint per exact store and process, and writes publish loose truth
once while reporting derived degradation. Ordinary reads and writes never synchronously rebuild history.
Print, verify, and smoke the current contract without opening a store:
```sh
just derived-access-rollout-contract
just derived-access-rollout-contract-verify
just derived-access-rollout-contract-smoke
```
The compiled schema is `pointbreak.derived-access-rollout-contract.v1`; its canonical SHA-256 is
`69650f18f89329aac602ecbf34a552084decd9f48556ce0e3f5a4aa2cc711fb1`. It links to, but does not rewrite,
the historical integration and readiness contracts.
| Selector | unset `POINTBREAK_DERIVED_ACCESS` selects `sqlite-wal-bodyless-v1`; explicit `off` remains the immediate rollback |
| Authority | loose Journal and ContentStore carriers remain the sole truth; derived state is disposable and rebuildable |
| Layout | stable `derived` with compatible transition from legacy `.pointbreak-derived` |
| First use | Inspector: serve the shell and start one asynchronous build when no current generation exists; bounded CLI: remain available through authoritative truth and emit one actionable fallback hint; write: publish authoritative truth once and report disposable-generation degradation |
| Recovery | `pointbreak store derived status\|build\|rebuild`; unavailable hint at most once per exact store per process |
| Bounded CLI | history page with an effective limit and without watch, ref filter, or body search; attention list; revision list with an explicit accepted limit at most 500; cursor binds profile, schema, snapshot, normalized descending order |
| Rollback | explicit off artifact-free: `true`; ordinary synchronous rebuild allowed: `false` |
| Platform scope | native `macOS APFS`, `Windows NTFS`; Linux compile/CI only: `true` |
| Historical boundary | integration `3afe3a1fd65f0d5c58246dbe426c35a32325dc42bd9931d78f0e2354411dd00d` and readiness `5445781aadff791537746f1596f577ea1415fd37daf6d0da4fbc0ded94375eb3` remain immutable; truth migration authorized: `false` |
## Incremental derived-access falsifier contract
The candidate-independent incremental derived-access contract is compiled into the benchmark target as
`pointbreak.qualification-derived-access-contract.v1`. Its canonical SHA-256 is
`c29fd0b862cfd3594c02b88f159477adb9b8666b8dfeebd868e766f8cf025ab8`. Print and validate it without
constructing a physical profile, reading a corpus, creating a store, or collecting observations:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS
cargo bench --locked --features bench --bench store_foundation -- --derived-access-contract
```
| Contract | `incremental-derived-access-falsifier-v1` |
| Evaluator | `pointbreak.qualification-derived-access-evaluator.v2`; this revision identifies the decision procedure independently of the frozen parameter digest |
| Authority | loose journal/content carriers remain truth; derived state is private, bodyless, disposable, and rebuildable |
| Correctness tier | `D0-128`: 128 events, 16 revisions, 16 independent objects, 2 byte-identical roots, frozen transition/operation/lifecycle coverage, no timing threshold; the runner later binds one public seed and ordered-schedule receipt |
| Operations | `SEMANTIC_ID`, `FRESH_NO_CHANGE`, `NEWCOUNT_ZERO`, `WINDOW_HEAD`, `WINDOW_MIDDLE`, `WINDOW_TAIL`, `REVISION_DETAIL_ACTIVE`, `REVISION_DETAIL_REMOVED`, `APPEND_ONE`, `POST_ONE`, `RESTART` |
| Samples | 2 release roots; 1 untimed request and 3 excluded warmups; 30 retained warm/append-post samples per root; 10 restart samples per root; no outlier removal |
| Complexity | classify before latency; fixed-output work is bounded selected work; L100-to-C262 work/retention ratio at most `1.25` unless the receipt proves that all excess work is selected-output growth |
| L100 latency / CPU | `SEMANTIC_ID` `150/100 ms`; `FRESH_NO_CHANGE` `50/25 ms`; `NEWCOUNT_ZERO` `50/25 ms`; `WINDOW_HEAD` `150/100 ms`; `WINDOW_MIDDLE` `150/100 ms`; `WINDOW_TAIL` `150/100 ms`; `REVISION_DETAIL_ACTIVE` `250/175 ms`; `REVISION_DETAIL_REMOVED` `250/175 ms`; `APPEND_ONE` `250/200 ms`; `POST_ONE` `500/400 ms`; `RESTART` `3000/2500 ms` |
| Memory | store-attributable L100 steady/peak RSS at most `96/128 MiB`; L7-to-L100 steady slope at most `512 bytes/event`; zero retained body/object bytes outside the active window |
| Allocation | steady derived bytes at most `max(64 MiB, 1024 × event count)`; high-water at most `1.5×`; append write amplification at most `8×` |
| Bootstrap | L100 at most 60 minutes; C262 at most 180 minutes; progress required; experiment-cost guards only |
| Native gates | macOS/APFS and Windows/NTFS independently pass D0-128/L1/L7 before APFS L100/C262; Linux is compile/CI only |
| Non-compensation | semantics, provenance, native, lifecycle, complexity, latency/CPU, memory, allocation, write amplification, and bootstrap gate independently |
| Outcomes | `reject`, `survives_apfs_falsifier`, or `insufficient_evidence`; survival authorizes no production activation or migration |
| Inputs | qualification evidence and measurement use only public generated inputs; derivation hash commitments are provenance, not workload inputs |
| Excluded | observed candidate result, search/body persistence, private corpus, candidate measurements, production selection, activation, migration, and release promises |
The publication freezes authority, workload identities, sample counts, process scopes, semantic receipts,
counter ceilings, resource limits, native gates, and non-compensation before a physical profile is measured.
`D0-128` is correctness-only. Native macOS/APFS and Windows/NTFS D0-128/L1/L7 rows must pass before APFS
L100/C262 scale evidence is eligible; Linux remains a compile/CI gate.
Missing or unknown rows and a missing required native-platform identity yield `insufficient_evidence`.
Duplicate, unsupported, inadmissible, or mixed-authority identities are rejected before evaluation. A
semantic, lifecycle, bounded-work, resource, or cost failure yields `reject` even when another row is fast.
The sole success outcome,
`survives_apfs_falsifier`, authorizes only a later decision; it does not select or activate storage, authorize
migration, persist search/body material, change release promises, or make derived data authoritative.
### Native authority-stamp falsifier
The developer-only authority-stamp mode tests whether one O(1) observation of the loose journal's local
`events/` directory can detect every supported append without enumerating directory entries or opening an
event carrier. It exercises the same 21-scenario matrix on native macOS/APFS and Windows/NTFS, including
governed and out-of-band creates, duplicate no-create attempts, rapid mutations, crash boundaries, aliases,
temporary files, and an explicit in-place-overwrite non-claim. A changed stamp is only a reason to perform a
later exact audit; it never proves that an event is present or valid.
Run each native receipt from the same exact clean commit. The probe root must be absent or empty, and the
output must be outside source control:
```sh
cargo bench --locked --features longitudinal-counting --bench store_foundation -- \
--derived-access-authority-stamp \
--derived-access-source=/absolute/path/to/clean-pointbreak \
--derived-access-root=/absolute/path/to/empty-native-probe \
--derived-access-output=/absolute/path/to/native-receipt.json
```
The completion-last `pointbreak.derived-access-authority-stamp-native-receipt.v1` document is structurally
valid whether the candidate passes or exposes a falsifier. `allScenariosAccepted: false` is a terminal native
failure, not missing evidence. Existing-carrier overwrite remains outside the stamp guarantee and is accepted
only when selected-carrier validation detects the injected corruption. The scope is accidental and
mixed-version publication detection, not resistance to malicious tampering.
Sidecar deletion and experiment-off rollback are explicit not-applicable rows: this directory-only candidate
observes neither derived authority metadata nor the disabled profile.
After copying both receipts to one host, verify their hashes and common source/tree/lock authority read-only:
```sh
cargo bench --locked --features longitudinal-counting --bench store_foundation -- \
--derived-access-authority-stamp-verify \
--derived-access-input=/absolute/path/to/macos-apfs.json \
--derived-access-input=/absolute/path/to/windows-ntfs.json
```
Verification emits `pointbreak.derived-access-authority-stamp-native-package.v1` only when both native
matrices pass. A structurally valid rejected receipt makes package verification fail closed. These modes use
only disposable public fixtures and do not route product reads or writers, create derived production state,
select a default, migrate a store, or read `POINTBREAK_QUALIFICATION_CORPUS`.
### Derived-access qualification runner
The runner exercises a qualification-only SQLite/WAL adapter. It does not change the Inspector, CLI,
normal store resolver, event or content formats, or any production profile. Its derived namespace contains
only cursor, locator, and compact semantic rows; authoritative event, body, and object bytes remain in the
unchanged loose store.
List the available modes without creating a root:
```sh
just derived-access-help
```
`just derived-access-smoke D0-128`, `just derived-access-smoke L1`, and
`just derived-access-smoke L7` are disposable self-tests over public deterministic inputs. D0-128 records
its public seed, frozen coverage-schedule hash, distinct ordered-schedule hash, and two-root byte-identity
receipt. L1 and L7 reuse
the existing public longitudinal identities at exactly 1,024 and 7,168 events. Counter-admissible smoke
receipts require both the `longitudinal-counting` feature and an execution-bound typed request:
```sh
just derived-access-native-smoke /absolute/path/to/native-smoke-request.json
```
`just derived-access-bootstrap-smoke D0-128`, `L1`, or `L7` exercises the production lifecycle
bootstrap over one disposable public root. Its separate receipt records completed progress phases,
carrier opens/decodes/validations, and post-bootstrap decoded-event ownership. It records process RSS
where the host supports process snapshots (currently macOS); `rssObserved` is false and the three RSS
values are `null` elsewhere. This non-timing developer smoke does not change the frozen
qualification-smoke schemas, consume a retained or owner root, or activate the derived profile for
product reads.
Phase attribution is a separate diagnostic mode for revision-page, bootstrap, and governed-write work:
```sh
just derived-access-phase /absolute/path/to/phase-request.json > /absolute/path/to/phase-bundle.json
just derived-access-phase-verify \
/absolute/path/to/phase-request.json \
/absolute/path/to/phase-bundle.json
```
The typed request binds one clean source identity, D0-128/L7/L100 tier, admitted authoritative inventory,
read-only `immutableInputRoot`, and filesystem-disjoint mutable `root`. Both roots must begin with the admitted
inventory. The runner rechecks the immutable input after the governed append and emits the completion-last
`pointbreak.qualification-derived-access-phase-bundle.v1` only when it remained unchanged. The mutable root
is intentionally single-use: bootstrap writes its disposable `derived/` generation (or reuses a compatible
legacy `.pointbreak-derived/` root) and the governed-write probe appends one public synthetic event to
authoritative truth, so make a fresh clone for every run. `POINTBREAK_DERIVED_ACCESS=sqlite-wal-bodyless-v1`
is required and is checked before bootstrap.
Each operation receipt carries ordered typed samples, optional process CPU/RSS endpoints, counters, and
ownership. `parentOrdinal` makes nested samples explicit; a child sample is already included in its parent's
wall time, process CPU, and counters and must not be summed again. `residentBytesObservedMax` is the maximum
of the before/after endpoint readings, not a continuously sampled peak. The separate verifier revalidates
request/source/tier/root binding, raw-receipt hashes, phase completeness and nesting, and the completion-last
bundle manifest without opening or mutating either root.
Native smoke, lifecycle, retained-root, scale, resource, and fragment modes consume typed JSON requests:
```sh
just derived-access-lifecycle /absolute/path/to/lifecycle-request.json
just derived-access-retained-preflight /absolute/path/to/retained-root-request.json
just derived-access-retained-bootstrap /absolute/path/to/retained-root-request.json
just derived-access-scale /absolute/path/to/scale-request.json
just derived-access-resource /absolute/path/to/resource-request.json
just derived-access-fragment /absolute/path/to/fragment-request.json
```
The retained-root modes accept L7, L100, or C262. They require a separately admitted immutable input and
a distinct, precreated qualification clone; no runner mode can materialize those tiers. Preflight compares
the complete authoritative inventory. Bootstrap writes only the selected disposable derived root, reports
progress and high-water allocation, compares the incremental semantic receipt with strict full replay, and
rechecks both the input and clone truth inventories.
Scale evidence requires two already-bootstrapped roots. Each warm read receives one untimed request, three
excluded warmups, and 30 retained samples per root. Append/post uses 30 pairs per root, and restart uses ten
fresh child processes per root. Raw rows name wall nanoseconds, process CPU nanoseconds, responsible process
scope, selected rows, SQLite page count and size deltas, counters, response bytes, and semantic receipts.
Correctness and mechanically classified work complexity are checked before p95 latency or CPU is admitted.
L100/C262 timing, CPU, allocation, bootstrap, and resource modes are APFS falsifiers collected on native
macOS; Windows/NTFS independently gates the D0-128/L1/L7 smoke and lifecycle rows, and Linux remains a
compile/CI surface.
Resource evidence uses separate empty, L7, and L100 child processes so reported RSS is empty-adjusted and
the L7-to-L100 slope has a consistent process boundary. Its body/object-retention row is measured from the
actual sidecar schema and values rather than supplied as a constant.
Fragment requests bind raw receipts to one clean source/tree/lock/binary/contract/root-authority/hashed-host
execution identity. `rootProvenanceSha256` is the common campaign-authority commitment, not an assertion
that every mode operates on one physical root. Each typed raw receipt separately carries its admitted
per-root inventory hashes; each fragment promotes those hashes into execution-bound package root bindings,
and the completed package also archives the receipts and binds their exact bytes in its completion-last
manifest. The evaluator derives p95, retained counts, work/cardinality maxima, C262
work ratios, allocation, and write amplification from retained raw samples and measured inventories rather
than trusting supplied summary rows, and includes bootstrap high-water in the allocation gate. Final
package assembly rejects exact duplicate
identities, mixed source or per-platform native authority, and duplicate row authority; evaluates before
publication; accepts only raw-bound fragments (never hand-authored partial packages); reconstructs every
D0, operation, lifecycle, resource, allocation, and bootstrap summary from those archived receipts; writes
raw inputs before the manifest; and creates the completion marker last. Verify a completed
package recursively with:
```sh
just derived-access-verify-package /absolute/path/to/completed-package
```
Private-corpus configuration, source/build/private-store paths in evidence, body-bearing inventories,
mutated immutable roots, ambiguous CPU units, semantic mismatches, and corrupt or unlisted package files
fail closed. Missing native evidence remains an explicit `insufficient_evidence` result rather than a
package error.
## Prospective feasibility contract
The approved prospective contract is compiled into the benchmark target as
`pointbreak.qualification-prospective-feasibility-contract.v1`. Its canonical SHA-256 is
`8e9fb5bffef230d97d3f4abc8a70c79958e4372668af8bde19b3aa815382857d`, and it binds the exact approved
proposal SHA-256
`83446c8a40eb71fa4696ee5d71043c47beb8624fc97e2360b62337e489ad67e8`. Print the contract and its
generated decision table without running a candidate, reading an evidence corpus, or collecting timing:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS
cargo bench --features bench --bench store_foundation -- --prospective-contract
```
The contract requires two independent native runs on macOS/APFS, non-container Linux/ext4, and native
Windows/NTFS. Each run retains 30 raw samples after three warm-ups. `G0` is a diagnostic early-stop row;
`G1` is the first required allocation crossover; `G2` is the representative public scale row. `P0` and
`M0` separately gate small-store fixed overhead and peak headroom. Evidence binds the admitted loose
baseline authorities, exact source commit and tree, `Cargo.lock`, generator, public seed, manifests,
operation schedules, native allocation API, semantic receipt, and contract identity. Missing evidence
evaluates as unknown, while stale, duplicate, mixed, or hash-mismatched evidence is rejected.
For durable append, replay, fresh-process open/recovery, and each oldest/middle/newest/absent keyed read,
the candidate p95 must satisfy both the operation's absolute ceiling and this dynamic ceiling:
```text
min(absolute ceiling, max(ceil(loose p95 * 125 / 100), loose p95 + guard band))
```
The absolute ceilings are 50 ms for durable append, 500 ms for replay, 750 ms for fresh-process open,
and 5 ms for each keyed read. Guard bands are respectively 5 ms, 10 ms, 25 ms, and 1 ms. Equality passes;
one nanosecond above the resulting limit fails.
Event allocation must save at least 25% and complete-profile allocation at least 10% versus the paired
loose baseline at both `G1` and `G2`, in steady, reopened, and high-water states. `G1` must also be strictly
smaller in both scopes and every state. High-water allocation may be no more than 150% of candidate steady
allocation while still satisfying the savings floor. Small-store fixed-overhead and peak-headroom caps
are 1 MiB for event scope and 2 MiB for complete-profile scope. Maintenance foreground p95 is capped at
250 ms, with total budgets of 5 seconds at `G1` and 30 seconds at `G2`; a genuinely inapplicable
maintenance mechanism requires a hash-bound mechanism proof.
Only public native rows decide prospective feasibility. An owner-local sanitized snapshot may veto later
adoption but cannot rescue a public failure, is never pooled with the public rows, and is excluded from
the contract publication. The publication also excludes candidate observations and results. Passing this
contract establishes prospective plain-store feasibility only: it does not select a storage profile,
authorize production use or migration, or alter the historical H8 qualification artifacts below.
## Plain LMDB prospective evidence runner
The `lmdb-proof` feature includes a native evidence runner and a separate package assembler for the
approved prospective contract. The runner emits one
`pointbreak.qualification-lmdb-prospective-evidence-shard.v1` document for the current native
platform. The assembler accepts exactly one macOS/APFS, one non-container Linux/ext4, and one native
Windows/NTFS shard, then emits a
`pointbreak.qualification-lmdb-prospective-package.v1` document containing the unchanged
`pointbreak.qualification-prospective-feasibility-evidence.v1` aggregate and its frozen
`pointbreak.qualification-prospective-feasibility-evaluation.v1` evaluator output.
Before collecting evidence, exercise the runner, the plain LMDB semantic and lifecycle preflights,
and deterministic package assembly without collecting normative timing or allocation samples:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS
cargo bench --locked --features bench,lmdb-proof --bench store_foundation -- \
--lmdb-prospective-smoke
```
The smoke report schema is `pointbreak.qualification-lmdb-prospective-smoke.v1`. Its
`deterministicFixtureOnly` and `normativeMeasurementCollected` fields are respectively `true` and
`false`; its shard and package hashes cover synthetic protocol fixtures, not candidate results.
A real native shard must be built and run from the exact clean commit being evaluated, with the host
quiesced and only the generated public workloads enabled:
```sh
unset POINTBREAK_QUALIFICATION_CORPUS
export POINTBREAK_QUALIFICATION_QUIESCED=1
cargo bench --locked --features bench,lmdb-proof --bench store_foundation -- \
--lmdb-prospective-evidence > native-shard.json
```
The runner performs the non-timing semantic and lifecycle preflights first, then executes two
independently prepared runs for `P0`, `M0`, `G0`, `G1`, and `G2`. Timing-required rows retain all 30
paired candidate and loose-baseline samples after three warm-ups; allocation rows retain event and
complete-profile inventories for steady, reopened, and high-water states. Candidate operations and
their adjacent loose controls cover durable append, strict replay, fresh-process open/recovery, and
oldest, middle, newest, and absent keyed reads with the contract's verified-operation windows.
Every shard carries two distinct provenance layers. The published contract retains the source
commit, source tree, and `Cargo.lock` identities from which its thresholds were derived. The shard's
execution envelope instead records the exact clean commit and tree that produced the measurements,
the current `Cargo.lock` SHA-256, the reviewed LMDB closure-manifest SHA-256, the frozen contract and
approved proposal hashes, the public generator and seed, the physical profile, and the run controls.
Package assembly rejects stale or mixed execution envelopes, missing platforms or runs, duplicate
rows, hash mismatches, and private-data markers. Shards and packages serialize no disposable paths,
environment values, command lines, logical keys, payload bytes, or record-level hashes.
After the three native shards have been collected from the same execution identity, assemble and
evaluate them from that same clean commit:
```sh
cargo bench --locked --features bench,lmdb-proof --bench store_foundation -- \
--lmdb-prospective-package \
--lmdb-prospective-input=macos-apfs.json \
--lmdb-prospective-input=linux-ext4.json \
--lmdb-prospective-input=windows-ntfs.json
```
The assembler validates all inputs before running the frozen evaluator and binds both the evaluation
and the final package with canonical SHA-256 identities. A well-formed package can evaluate to
passed, failed, or unknown; assembly success is not a feasibility verdict. No prospective runner or
package command selects a store, changes production routing, authorizes migration, or rewrites prior
qualification evidence.
## Frozen performance qualification contract
The machine-readable performance qualification contract is compiled into the benchmark target. Print
the canonical contract, its SHA-256 identity, and its generated human decision table with:
```sh
cargo bench --features bench --bench store_foundation -- --qualification-contract
```
The contract applies the same four complete operations—durable append, strict replay, keyed read, and
fresh-process open/recovery—to the SQLite WAL and bounded-segment candidates against one common loose-file
baseline. Required quantitative rows are the external workload on macOS/APFS and the modeled workload on
macOS/APFS, native non-container Linux/ext4, and native Windows/NTFS. Public-smoke rows use the same
protocol and semantic receipts on all three platforms, but their timing and allocation remain diagnostic.
Each operation receives three untimed warm-up pairs and 30 measured adjacent pairs, alternating which role
runs first. Two independently prepared runs are required for every workload/platform row. The evaluator
retains every sample, computes candidate-to-baseline ratios, and reports nearest-rank p50 and p95, the full
range, and population standard deviation. Every quantitative run passes only when each operation's p95 is
at or below 125%; runs are never pooled. Event-scope and complete-profile native allocations must also be
strictly lower than the loose baseline in steady, reopened, and high-water states. Allocation parity fails.
Windows allocation uses `FILE_STANDARD_INFO.AllocationSize`; its native fixture test covers one-byte and
multi-cluster ordinary files, sparse allocated ranges, and compressed data. Missing, stale, unsupported,
duplicate, or hash-mismatched evidence is rejected or evaluated as unknown, never as a pass.
Run a final evidence shard only from a clean exact commit on a quiesced native host. macOS additionally
requires the validated external workload copy; Linux and Windows reject that variable because the frozen
contract assigns the external row only to macOS:
```sh
export POINTBREAK_QUALIFICATION_QUIESCED=1
export POINTBREAK_QUALIFICATION_CORPUS=/path/to/external-corpus-copy # macOS only
cargo bench --features bench --bench store_foundation -- --qualification-final-evidence > macos.json
```
The runner discards separate warm-up roots, grows fresh measured roots monotonically, validates replay and
fresh-process open receipts, and records native event-scope and complete-profile allocation. High-water
sampling includes the candidate checkpoint or seal boundary before reopen. The JSON contains only
sanitized hashes, counts, timing samples, allocation totals, and environment identity.
After collecting the macOS, native Linux/ext4, and native Windows/NTFS shards from the same source and
contract identities, assemble and evaluate the complete performance package with:
```sh
cargo bench --features bench --bench store_foundation -- --qualification-package \
--qualification-input=macos.json \
--qualification-input=linux.json \
--qualification-input=windows.json
```
Assembly rejects stale or duplicate shards and any package with a missing required run. A valid package
may still contain failed timing or allocation criteria; measurement failure is evidence, not a malformed
package.
## Native foundation qualification
The developer-gated foundation runner applies one deterministic matrix to the SQLite WAL and bounded-
segment candidates on both public workloads. It uses fresh disposable roots and real child processes for
locking, reader/writer, backup/writer, kill/reopen, and maintenance overlap. Results include exact build and
dependency identity, stable per-row seed identities reserved for future seeded placement, fixed scenario
boundary labels, filesystem policy, native allocated-byte inventories, raw samples, and a generated
completeness report.
Run the non-timing matrix used by native CI with:
```sh
just store-foundation-qualification-smoke
```
The legacy repeated matrix remains available for historical comparison with:
```sh
just store-foundation-qualification
```
That command no longer produces new qualification evidence. Its performance rows fail closed until a
complete `pointbreak.qualification-performance-evidence.v2` package is assembled and evaluated. Timing
thresholds never run in default tests or the CI smoke lane.
These matrix commands use only the checked-in public workloads. They do not read
`POINTBREAK_QUALIFICATION_CORPUS`; validate an explicitly supplied external copy separately with the
`--smoke` command above, and keep its record bytes outside the repository and generated reports.
## Non-gating performance diagnostics
The foundation target also has an explicit diagnostic mode that explains the candidate and loose-file
operation totals without changing the qualification verdict:
```sh
cargo bench --features bench --bench store_foundation -- --qualification-diagnostics
```
It runs warm-up and alternating paired samples for durable append, strict replay, keyed read, and strict
open/recovery. The JSON report binds the source commit, Cargo lockfile, diagnostic contract, candidate
profile, workload, platform, pair order, raw totals, stage totals, and steady/reopened/high-water
inventories. Diagnostic results are observations: exceeding the historical 125% ceiling does not make this
command fail and does not select a storage profile.
For order-sensitivity controls, repeat the command with
`--qualification-pair-order=candidate_then_baseline` and
`--qualification-pair-order=baseline_then_candidate`. An alternating report remains the primary paired
observation; either fixed-order report on its own is incomplete diagnostic evidence.
When `POINTBREAK_QUALIFICATION_CORPUS` names a validated external workload copy, the same process also adds
that workload. The path, logical keys, and decoded bytes are not serialized. Never point it at a live store,
a path inside a Git worktree, or `~/.pointbreak`; an absent external path leaves the public diagnostic run
complete without claiming external-corpus evidence.
## Real-world read-all sample: `POINTBREAK_BENCH_FIXTURE`
The `read_all/fixture` group runs only when `POINTBREAK_BENCH_FIXTURE` points at a **store directory** — the
directory that contains `events/`. For a captured repo that is the shared common-dir store at
`<git-common-dir>/pointbreak`. When the variable is unset, or the store does not read back, the group is **skipped,
not failed**, so the harness has no baked-in paths.
The API-level benches (`revision_overviews`, `freshness`) instead want a repo root: set
`POINTBREAK_BENCH_REPO=<repo>`, or, for the standard `<repo>/.git/pointbreak` layout, let it be
derived from `POINTBREAK_BENCH_FIXTURE`. Linked worktrees and separate Git directories must set
`POINTBREAK_BENCH_REPO` explicitly.
## Schema currency matters
The fixture store must be authored by the **current** Pointbreak schema. A store from a retired schema
(for example the legacy `writer.role` envelope, pre-0076/0079) hard-errors under the strict
`list_events`, so the real-world group silently skips — which is exactly why a rotted fixture is easy to
miss.
Two things guard against that:
- A schema-currency guard test (`bench_support` →
`a_current_schema_store_reads_back_through_the_harness`) authors a store with the current code and
asserts it reads back through the harness. If a schema break ever regresses this, that test fails
loudly in CI rather than the benchmark quietly skipping.
- The fixture is **regenerated**, not committed as a binary blob, so it can't drift out of schema.
## Getting a current-schema fixture
Capture a current-schema repository, ask Pointbreak for its canonical common store, and point the
benchmark at that directory:
```sh
REPO=/path/to/captured/repo
export POINTBREAK_BENCH_REPO="$REPO"
```
Re-capture or regenerate the source repository after any store-schema break to keep the fixture current.
> A future alternate backend must be measured on the **same** filesystem as the file backend — disk
> amplification is filesystem-specific (~8× on APFS for sub-block event files). See
> [ADR-0020](./adr/adr-0020-durable-storage-backend-seam.md).