Skip to content

[v0.1.3][Stage 1][01] Build and baseline payload creation and random reads #23

Closed

Description

@yifanxuaaa

Phase 1 completion amendment (2026-09-04)

The user requires functional failures to be repaired in Phase 1. The committed amendment supersedes earlier baseline-only closure and deferral wording below. Required functional, correctness, integrity, resource, safety-deadline and cleanup gates must pass before PHASE1_TERMINAL_PASS. Optional latency/storage optimization of correct operations remains Phase 2.

Preserve all original baseline failures and producing identities; record corrected candidate evidence separately. Fix shared causes and recollect only genuinely invalidated coverage. Do not shrink fixtures, omit cases, weaken oracles, raise budgets/timeouts or add benchmark-only bypasses. Keep affected family issues and #35 open until corrected execution and independent verification pass; #21 stays open for later phases/release.

Parent: #21
Depends on: #22 (shared infrastructure and committed specification).

Problem statement

LayerFS needs an authentic initial baseline for payload creation and random reads before deciding product improvements.

Goal and family scope

Create 1/10/100/500 MiB files and execute 1/10/100/500 random 4 KiB reads; retain the two older anchors separately.

Inventory: 8 new timed cases, 24 prescribed initial performance sample slots, and 0 standalone proof recipes. The canonical planning file is docs/roadmap/0.1/0.1.3/payload-create-read.md. The snapshot below makes the current proposal reviewable until its committed revision is published.

Stage 1 work

  • Freeze this family and its exact fixture/schedule/oracle identities under the shared contract; implement its complete membership in the existing harness with one canonical definition and thin adapter.
  • Qualify route, call counts, size/resource bounds, independent oracles and selected-case self-checks. Resolve harness defects before collecting baseline evidence.
  • Run one selected case/seed to establish a valid execution path, then collect every prescribed initial sample and separate proof variant on the pinned unoptimized product. Required extended cases are explicit but remain required.
  • Retain raw failures/timeouts as classified product findings. Keep setup, performance, verification, cleanup and external command wall distinct.
  • Produce a source-bound family report with all outcomes and measured questions for later optimization; do not tune product algorithms within this issue.

Acceptance criteria

  • Complete family implementation, unique IDs, exact counts, deterministic fixtures/schedules and independent oracle checks.
  • Committed specification and product/harness/build/runtime/input identities linked in the evidence manifest.
  • Every required case/subcase executed with a retained initial outcome; no missing mandatory counter, unimplemented member or silent skipped slot.
  • All prescribed valid sample repetitions retained, with separate independent verification of distinct input/schedule variants. Failed/invalid outcomes remain explicit and ineligible for performance claims.
  • Preparation reuse, per-sample isolation, byte limits and cleanup checked; actual first-use/cache-hit command wall reported.
  • Family baseline summary delivered to the consolidated report issue; known product failures remain failing release gates and are recorded for Stage 2.

Files to read

docs/roadmap/0.1/0.1.3/payload-create-read.md, docs/roadmap/0.1/0.1.3/testing-rules.md, docs/general/benchmark_rules.md, and the existing source/test references in the specification below.

Stage 1 boundary

Build the benchmark and retain its initial outcomes. Product algorithm, storage-format and performance optimization are deferred to Stage 2. Improve benchmark preparation/reuse and correct harness defects now; do not silently change the measured product to make results pass. Pin the unoptimized product identity and distinguish harness changes from product changes.

A slow result, product failure or timeout is an initial finding, not permission to lower a gate, drop a case or start tuning. Keep outcome, harness validity, verification, resources, cleanup and coverage completeness separate. Failed/invalid cases cannot support performance claims. Unimplemented cases, missing mandatory observations and unexecuted slots remain incomplete.

Shared execution rules

  • Reuse fs-bench-pro, existing generators, runner helpers, custody, qualified pristine inputs, independent writable samples and reports. Add only needed family adapters.
  • Use 1/10/100/500 of the declared unit; no Cartesian size/count matrix. Each workload file is at most 500 MiB and aggregate logical content is strictly below 1 GiB at every intermediate state, including temporary files and Git internals. Physical Store/spool/cache budgets are separately reported.
  • Resolve the selected case/seed before preparation. Reuse compatible artifacts; prepare only required inputs. Measured creation/import/history must still execute all work.
  • Iterate one selected case and seed; ordinary warm-prepared 1–5 second command wall is a target to qualify, not a blanket guarantee. Required extended cases are explicitly selected and cannot be omitted from complete baseline coverage.
  • Separate performance and verification. Added benchmark hashes, full manifests, reopen and fault injection stay outside performance timing; intrinsic CAS/Git hashing remains measured.
  • Collect several metrics from one execution and regenerate reports from raw evidence without rerunning successful workloads. Retain all valid results and failures, with exact source, fixture, oracle, runtime and cache identities.
Planning specification snapshot — payload-create-read.md

Source file: docs/roadmap/0.1/0.1.3/payload-create-read.md. Local draft SHA-256: 70a8df8b57fc0574ab7c48ff3a4f76ab634a0bb73949a0b4f7c6bc10c2e71a2b. This snapshot is reviewable now; it is not a committed admission contract. The infrastructure issue must publish/freeze the source revision before implementation and collection.

Payload creation and random reads

Status: Current v0.1.3 planning specification; no release candidate or
measured result is implied.

Family ID: payload_create_read. This v0.1.3 implementation contract contains
8 new timed cases, 2 inherited timed anchors, and no standalone proofs.
New cases are specified here; their runner adapters are not implemented yet.

Purpose and boundary

Measure ordinary filesystem payload creation and bounded random reads through
real FUSE. These cases complement the inherited singular SDK edits. Whole-tree
reads belong to directory construction and traversal (docs/roadmap/0.1/0.1.3/directory-construction-traversal.md; planning file awaiting publication).

Use the shared testing rules (docs/roadmap/0.1/0.1.3/testing-rules.md; planning file awaiting publication) for seeds, sample isolation,
source seals, preparation reuse, resource limits, timing fields, and verification.
Each new sample has one Store, genesis Layer, Branch, Workspace, fresh workload
process, final Commit attempt, and clean End. Use public
Client::create_workspace_session, managed Workspace execution,
Client::commit_workspace_session, and Client::end_workspace_session.

Cases and fixtures

In the following table, expand N over exactly 1, 10, 100, 500. Braces denote
scenario-ID expansion, not implemented command-line syntax.

Scenario IDs Cases Initial state and measured work Commit outcome
payload-create-{N}m 4 Empty genesis; create one exact N MiB file through ordinary writes, then sync_all Created
payload-random-read-{N} 4 Prepared 500 MiB file; execute the first N deterministic 4 KiB reads UpToDate
cold-create-32m 1 inherited Released empty-Branch 32 MiB creation lifecycle Frozen outcome
read-32m 1 inherited Released complete 32 MiB sequential-read lifecycle Frozen outcome

Reuse exact sizes, payload bytes, SHA-256 values, canonical roots, and bounded
fixture_block generation from
sdk_edit_common.rs.
The 1/10/100 MiB payloads remain exact prefixes of the existing 500 MiB payload.
Prepared source bytes may be reused; each measured create must write every
result byte into its fresh empty Workspace. Never substitute a prepared
result Store or move creation into setup.

For each shared seed, derive one 500-request schedule using:

h = SHA256(seed_label || 0x00 || "payload-random-read" || 0x00 || index_le_u64)
offset = little_endian_u64(h[0..8]) mod (524288000 - 4096 + 1)

Requests use ordinary offset reads and preserve the listed order. The four
read cases use schedule prefixes against the same payload. The largest case
requests 2,048,000 bytes; it is a random-access measurement, not a full-file
throughput claim. The independent transcript digest covers each offset,
returned length, and returned bytes.

A workload contains at most one regular file of 524,288,000 bytes. Neither
curve creates a second payload copy in the tested namespace. Source caches
remain outside that namespace and have the separately reported preparation
budget in the shared rules. The inherited anchors retain their IDs, fixtures,
seeds, sample counts, timing fields, and verification meanings unchanged.

Timing and evidence

For new cases, measure Workspace Create, inner workload, ordinary sync where
applicable, Commit return, required visibility, End, and complete lifecycle
separately. Payload reads and writes occur inside the workload timer. Fixture
construction, Store preparation, source sealing, and independent verification
have separate walls and never enter operation latency distributions.

Record requested/completed bytes and requests, create throughput, random-read
transcript identity, FUSE calls and transferred bytes, CPU, memory, swap/OOM,
Store/object changes, and cleanup using the shared schema. Report read-only
Store growth separately from writes; reads must not create payload objects or
change the committed root merely because bytes were read.

The separate verifier reconnects to the Store and mounts a fresh FUSE Workspace.
It compares the complete path/type/size/mode/mtime/content manifest with the
independent expected manifest, authenticates content and canonical roots,
checks exact Branch head and Commit outcome, and proves cleanup. Random reads
also match the byte oracle at every scheduled offset. Creation must preserve
its exact payload after reconnect; read-only cases preserve the genesis state.

Execution and completion

There are three fresh performance samples per new case, one per shared seed:
24 new timed executions, with separate verification of every case. Inherited
anchors follow their own frozen sampling and are accounted once.

Reuse the existing benchmark binary, workload helper, runner selection,
custody/sample-clone mechanism, and reports. Extend only their family adapters.
The prospective development selector is one scenario and one seed, followed
by its focused verification; this selector is a requirement, not an available
command. Reuse validated inputs and prepared read Stores, never mutable sample
outputs. Start with payload-create-1m or payload-random-read-1.

The selected ordinary development target is provisionally 1–5 seconds where
baseline evidence supports it. Larger payloads, complete families, and full
verifiers use the longer lane with baseline-derived budgets. Completion requires
all eight cases, their independent proofs, exact size bounds, resource/cleanup
gates, and retained raw samples. No additional payload-size × request-count
matrix is introduced.

Activity

  1. self-assigned this
    on Sep 4, 2026
  2. yifanxuaaa commented on Sep 4, 2026

    @yifanxuaaa
    ContributorAuthor

    Performance-results checkpoint for #23: 24 independently validated active VM8 performance samples. The report validates 23 retained full proof(s) for this family at this checkpoint; further full checks are running. This comment does not claim global Phase1 terminal pass.

    Published report, exact rows, source identities and verification status, phase/counter evidence.

    VM8 performance source: 7948df2de269e5ffd47a232ffd8091ff83f8869f; fixed 8-CPU Docker VM, unchanged 2-CPU/2-GiB benchmark-container caps. No VM4/VM8 timing pooling. Every listed performance row passed the independent authenticity, custody, observation, resource and cleanup validation; workload admission still requires its separate full proof.

    Values below are medians across the prescribed three seeds. Product time is the declared cumulative public-operation time; preparation and complete sample wall are separate. Store growth is the observed physical Store-file delta, not a deduplication ratio or verified canonical byte count.

    Case n Product ms Preparation s Complete sample s Store delta MiB Full proofs in checkpoint
    payload-create-100m 3 475.692 0.473 1.356 119.125 3/3
    payload-create-10m 3 83.486 0.483 0.935 12.000 3/3
    payload-create-1m 3 27.125 0.494 0.899 1.250 2/3
    payload-create-500m 3 3744.340 0.534 4.866 596.250 3/3
    payload-random-read-1 3 28.944 0.969 1.384 0.000 3/3
    payload-random-read-10 3 77.718 0.863 1.317 0.000 3/3
    payload-random-read-100 3 587.663 0.928 1.928 0.000 3/3
    payload-random-read-500 3 2791.173 0.887 4.162 0.000 3/3

    All prior actual failures, source incompatibilities, invalidations and preparation interruptions remain in the linked report and raw evidence. The fast development verifier contributes zero full-verification credit. Completed family tickets will close only after their remaining mandatory full checks pass; #21 remains open for later phases.

  3. yifanxuaaa commented on Sep 4, 2026

    @yifanxuaaa
    ContributorAuthor

    Payload family validation: PASS. The sealed family completion receipt establishes all 8 active cases, 24 VM8 performance samples and 24 full VM8 verification slots, with zero suppressed, missing, invalid or failed family slots.

    The final missing proof, payload-create-1m seed 1, is attempt 32021d2ca8fe at source e32469e975e8e185ca525b02bb71d70bafa4e865. The existing report.validate_attempt accepted its complete canonical/native verification, mandatory observations, input custody, resource/deadline and cleanup evidence with no issues or violations. Its completed CLI invocation is bound in the receipt.

    Only that new proof was validated in this checkpoint. The other 47 family rows (24 performance samples and 23 full proofs) were reused from the freshly qualified, sealed report. All 24 performance-to-proof pairs have exact case/seed, input and VM8 environment matches, with the already-qualified explicit source joins. The receipt records each identity and attempt seal, the input report SHA-256, the new attempt seal and the validator identity. No performance, full proof or complete report was rerun.

    The implemented route remains public Workspace Create, the compiled ordinary create/read workload through Exec and FUSE, the prescribed Commit/visibility result and End. Random reads retain the fixed 500 MiB payload identity and frozen request schedule. Complete reopened bytes, metadata and untouched contents were checked; fast verification and the older VM4 payload proof receive no credit. The two older anchors retain their separate inherited historical disposition.

    Evidence: family contract; focused validation detail; checkpoint hash manifest; VM8 admission policy.

    This satisfies the family-specific closure evidence for #23. Other families and the consolidated #35 gate remain in progress; #21 stays open. Original failures and historical source/environment observations remain preserved.

  4. yifanxuaaa commented on Sep 4, 2026

    @yifanxuaaa
    ContributorAuthor

    Read-only pin repair performance results for #23 — 12 corrected qualified PASS; 0 corrected non-PASS outcome(s). The corrected passing samples have completed independent validation with zero issues or resource violations. It does not claim terminal pass.

    Corrected runtime source: 30d13deeec72b46ff7bc411f1ec08a46990541e1. Other rows retain their original qualified checkpoint at 7948df2de269e5ffd47a232ffd8091ff83f8869f with their original numbers and source. Exactly 45 historical slots across #23/#25/#29/#33 were affected. The correction produced 42 independently qualified PASS slots; directory-content-scan-100 seed 1 exceeded the cumulative 15-second limit and its seeds 2/3 were not run. That case is now suppressed for all Phase 1 seeds/sources: 15 disabled case IDs, 370 active performance slots (328 retained plus 42 corrected). No old/new timings are pooled.

    The changed product branch now acknowledges the existing read-only regular-file Pin before exposing the Open handle. Historical affected rows remain actual observations of their old source; they are superseded for the repaired candidate, not deleted or called failed. No speedup claim is made.

    Product ms, preparation s, complete sample s and physical Store-file delta MiB use the prior table definitions. Corrected medians use only the listed completed qualified PASS seeds; incomplete three-seed groups are explicitly partial. They are medians of independently qualified samples. The full-proof column is copied from the prior checkpoint and is not a refreshed current proof count. Current routine acceptance follows the authorized fast-verification amendment; a fast result remains fully_verified=false. Targeted reliability gates are unchanged.

    Case n Product ms Preparation s Complete sample s Store delta MiB Full proofs in prior checkpoint Source Disposition
    payload-create-100m 3 475.692 0.473 1.356 119.125 3/3 7948df2d Retained prior qualified checkpoint
    payload-create-10m 3 83.486 0.483 0.935 12.000 3/3 7948df2d Retained prior qualified checkpoint
    payload-create-1m 3 27.125 0.494 0.899 1.250 2/3 7948df2d Retained prior qualified checkpoint
    payload-create-500m 3 3744.340 0.534 4.866 596.250 3/3 7948df2d Retained prior qualified checkpoint
    payload-random-read-1 3 25.880 3.159 3.560 0.000 3/3 30d13dee Qualified PASS
    payload-random-read-10 3 82.473 3.165 3.632 0.000 3/3 30d13dee Qualified PASS
    payload-random-read-100 3 612.392 3.217 4.291 0.000 3/3 30d13dee Qualified PASS
    payload-random-read-500 3 2772.245 3.198 6.449 0.000 3/3 30d13dee Qualified PASS

    Historical affected rows (preserved exactly from the prior qualified table; excluded from corrected medians):

    Case n Product ms Preparation s Complete sample s Store delta MiB Full proofs in prior checkpoint
    payload-random-read-1 3 28.944 0.969 1.384 0.000 3/3
    payload-random-read-10 3 77.718 0.863 1.317 0.000 3/3
    payload-random-read-100 3 587.663 0.928 1.928 0.000 3/3
    payload-random-read-500 3 2791.173 0.887 4.162 0.000 3/3

    Exact corrected outcomes and historical supersession mapping:

    • payload-random-read-1 seed 1: payload-random-read-1-s1-performance-3f23f2e39e60 (independently qualified PASS), replaces timing selection payload-random-read-1-s1-performance-b97735dba516.
    • payload-random-read-1 seed 2: payload-random-read-1-s2-performance-7046aa7f78ac (independently qualified PASS), replaces timing selection payload-random-read-1-s2-performance-a206e30c9898.
    • payload-random-read-1 seed 3: payload-random-read-1-s3-performance-9bb840944fba (independently qualified PASS), replaces timing selection payload-random-read-1-s3-performance-2935726c4bcf.
    • payload-random-read-10 seed 1: payload-random-read-10-s1-performance-3ee3cb24cb08 (independently qualified PASS), replaces timing selection payload-random-read-10-s1-performance-f60414a783d1.
    • payload-random-read-10 seed 2: payload-random-read-10-s2-performance-27d7a1ae88c1 (independently qualified PASS), replaces timing selection payload-random-read-10-s2-performance-8d6a4d1180c5.
    • payload-random-read-10 seed 3: payload-random-read-10-s3-performance-877880105160 (independently qualified PASS), replaces timing selection payload-random-read-10-s3-performance-6015204ca8db.
    • payload-random-read-100 seed 1: payload-random-read-100-s1-performance-893d8ba69cda (independently qualified PASS), replaces timing selection payload-random-read-100-s1-performance-c8a09ba9a23e.
    • payload-random-read-100 seed 2: payload-random-read-100-s2-performance-13dbe1cfb356 (independently qualified PASS), replaces timing selection payload-random-read-100-s2-performance-2a587a8d49f8.
    • payload-random-read-100 seed 3: payload-random-read-100-s3-performance-cedaa50127d2 (independently qualified PASS), replaces timing selection payload-random-read-100-s3-performance-414d5847943e.
    • payload-random-read-500 seed 1: payload-random-read-500-s1-performance-3b7f0f55f52f (independently qualified PASS), replaces timing selection payload-random-read-500-s1-performance-4655f97d6000.
    • payload-random-read-500 seed 2: payload-random-read-500-s2-performance-58f5abb00269 (independently qualified PASS), replaces timing selection payload-random-read-500-s2-performance-096410aaed0c.
    • payload-random-read-500 seed 3: payload-random-read-500-s3-performance-821191ad1894 (independently qualified PASS), replaces timing selection payload-random-read-500-s3-performance-ff25dfbda978.

    All attempt paths are under benchmark-results/fs-bench-pro/phase1-v013/attempts/. Source, custody, observations, resources and cleanup were independently checked; matching routine correctness status is reported separately. Original failures and suppressions remain preserved; central #21 stays open.

    Published corrected timing checkpoint and per-case medians.

    Current payload correctness coverage remains24/24 independently qualified full proofs from the later payload-closeout checkpoint; the table’s historical-proof column is retained only for comparison.

  5. yifanxuaaa commented on Sep 4, 2026

    @yifanxuaaa
    ContributorAuthor

    Phase 1 is closed under the user's explicit withdrawal of all remaining verification tests. This is a scope withdrawal, NOT a claim that the original verification terminal criteria passed.

    The assistant designed an excessively expensive verification suite and spent too long expanding it after the user requested a much faster finish. That design is withdrawn and must be reassessed in Phase 2. No more verification work is scheduled.

    Final performance results:370 independently qualified active observations, with actual source identities and unoptimized timings. All15 suppressed case definitions, original failures and incomplete attempts remain preserved. Completed29 targeted proofs,48 routine full proofs and qualified fast evidence remain historical evidence; unrun verification is withdrawn/deferred, never relabeled passing.

    Explicit withdrawal and accountability record. Separate Phase 2 backlog. Central#21 stays open for Phase 2/release. No release tag was created.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

new featureA new user-facing capabilityv0.1.3LayerFS v0.1.3 checkpoint and delivery

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions