Skip to content

[v0.1.3][Stage 1][06] Build and baseline workspace change locality #28

Closed

Description

@yifanxuaaa

Latest Phase 1 scope amendment (2026-09-04)

The user authorized permanent Phase 1 scheduling suppressions under the committed 15-second policy. This supersedes the original full-inventory execution wording below. Keep every case implementation and historical outcome for Phase 2 testing/optimization; suppression is not deletion or a passing result.

The original 130 new timed definitions remain intact. The initial 14 suppressed scenario IDs remove 42 performance samples and their 42 associated verifiers from required Phase 1 scheduling, leaving 116 active new cases / 348 performance samples, plus 25 capped inherited samples. All 29 standalone proof recipes remain required. Any additional single performance sample exceeding 15 seconds of cumulative declared product time permanently suppresses that exact scenario across all seeds/repetitions and future Phase 1 sources. Preparation, standalone proofs and external cleanup are exempt. Still-active correctness, resource, custody and cleanup gates remain unchanged; #21 stays open.

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 workspace change locality before deciding product improvements.

Goal and family scope

Measure untouched Commit, one fixed move as background grows, distributed singular SDK edits, and dense whole-shard rewrites.

Inventory: 16 new timed cases, 48 prescribed initial performance sample slots, and 0 standalone proof recipes. The canonical planning file is docs/roadmap/0.1/0.1.3/workspace-change-locality.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/workspace-change-locality.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 — workspace-change-locality.md

Source file: docs/roadmap/0.1/0.1.3/workspace-change-locality.md. Local draft SHA-256: bb3d03ee9b69e72f85b283e0c0f4296fe545c343fc4504df777cff9d8ee7c539. 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.

Workspace change locality

Status: v0.1.3 implementation plan; no measurements or passing claim.
Family ID: workspace_change_locality. Sixteen timed cases; no separate
proofs. Shared testing rules (docs/roadmap/0.1/0.1.3/testing-rules.md; planning file awaiting publication) govern common setup, seeds,
custody, timing, verification, resource bounds, and admission.

Question and fixture

Measure total Workspace size and dirty-work size independently. A clean Commit,
one small namespace change, sparse owner SDK edits, and dense ordinary writes
exercise different paths. Each is a four-tier curve, not a Cartesian matrix.

Reuse workspace-shards-v1 (docs/roadmap/0.1/0.1.3/testing-rules.md#shared-workspace-fixture; planning file awaiting publication), including
its exact file placement and metadata. One shard has 200 regular files:
128*1 KiB + 64*8 KiB + 8*48 KiB = 1 MiB. The frozen layout includes the wide
directory, regular siblings, 128-component spine, and empty dest/. Do not
create a second almost-identical fixture or label these as the original
single-file hashes. Prepare only the selected input size; N-shard inputs are
nested prefixes of the 500-shard generator.

N Files in an N-shard tree Logical bytes in an N-shard tree
1 200 1,048,576
10 2,000 10,485,760
100 20,000 104,857,600
500 100,000 524,288,000

All files are at most 48 KiB; each case stays at or below 500 MiB of aggregate
logical file bytes throughout. Owner SDK edits preserve length. Dense writes
replace files in place without a coexisting tree copy. Receipts stay outside
the workload with separately reported storage.

Exact member expansion

Scenario ID Fixture Measured dirty work Expected Commit
workspace-clean-commit-1 1 shard None; untouched Workspace UpToDate
workspace-clean-commit-10 10 shards None; untouched Workspace UpToDate
workspace-clean-commit-100 100 shards None; untouched Workspace UpToDate
workspace-clean-commit-500 500 shards None; untouched Workspace UpToDate
workspace-fixed-move-1 1 shard Move one fixed 1 KiB file Created
workspace-fixed-move-10 10 shards Move the same fixed 1 KiB file Created
workspace-fixed-move-100 100 shards Move the same fixed 1 KiB file Created
workspace-fixed-move-500 500 shards Move the same fixed 1 KiB file Created
workspace-distributed-sdk-edit-1 Fixed 500 shards 1 singular SDK 4 KiB overwrite Created
workspace-distributed-sdk-edit-10 Fixed 500 shards 10 singular SDK 4 KiB overwrites Created
workspace-distributed-sdk-edit-100 Fixed 500 shards 100 singular SDK 4 KiB overwrites Created
workspace-distributed-sdk-edit-500 Fixed 500 shards 500 singular SDK 4 KiB overwrites Created
workspace-dense-rewrite-1 Fixed 500 shards Rewrite 200 files / 1 MiB Created
workspace-dense-rewrite-10 Fixed 500 shards Rewrite 2,000 files / 10 MiB Created
workspace-dense-rewrite-100 Fixed 500 shards Rewrite 20,000 files / 100 MiB Created
workspace-dense-rewrite-500 Fixed 500 shards Rewrite 100,000 files / 500 MiB Created

There are 16 timed cases and 48 performance samples, three per case, with
separate verification. No fault, metadata, or link subcases are hidden here.

Operations and attribution

Clean Commit: create the ready real-FUSE Workspace and immediately Commit,
without Exec, listing, stat, payload reads, or mutations. Measure Create,
Commit, and End separately. Require unchanged Branch/head/root, no Commit
insertion, no write transaction, and unchanged Store counts. Whole-tree scan
families instead visit namespace or payload; their clean Commit does not replace
this untouched control.

Fixed move: one fresh managed process moves the same prepared 1 KiB file,
regular/s000/f064.dat, to dest/moved.dat using one ordinary rename. Changed
file count, payload size, and endpoint directories remain constant while the
background grows. Complete the declared sync, close all handles, and exit
before Commit. Do not enumerate the tree merely to locate this known path.

Distributed SDK edits: select one eligible file with index j >= 128 in
each selected shard of the fixed 500-shard tree. The deterministic N-element
prefix spreads targets across directories; each target is edited once. Invoke
Client::edit_workspace_file_range N times, replacing exactly 4 KiB in place
with independently generated different bytes. No managed Exec remains active.
Report aggregate SDK edit wall and one Commit wall separately. The public batch
API is same-file only; do not invent a multi-file batch. This measures a dirty
file frontier across a Workspace; inherited SDK families own single-file size
and edit geometry.

Dense rewrite: one managed process rewrites all 200 files of each selected
shard through ordinary FUSE open/write/close calls. Preserve each logical length
and use independently generated new content. Select N prefixes of one frozen
500-shard order. This is a dense ordinary-filesystem workload, not 100,000 SDK
edit calls. Freeze exact open/truncate/write/sync behavior and count every call
in the workload. Finish all writes and exit before one Commit.

All curves use one Branch, one final unpromoted Commit attempt, and End. Cached
preparation may reuse an identical input Store but cannot precompute output.
Metadata normalization needed for the oracle is explicit measured work limited
to affected paths; the clean curve performs none. Report it separately without
removing it from the operation's wall.

Independent verification and meaningful gates

Replay transformations against the frozen input manifest outside performance.
Compare every reopened path, bytes, length, type, mode, timestamp, and topology.
The move changes one binding; SDK oracles splice explicit 4 KiB replacements;
dense oracles replace exactly the selected files. Check unchanged files and
subtree identities, not just changed-file hashes. The clean control preserves
the complete input root. Candidate-produced roots are not their own oracle.

Record total and dirty files/bytes separately, SDK calls, FUSE operation/byte
counts, metadata/payload reads, candidate and inserted/reused objects,
transaction maxima, all phase walls, RSS, spool/Store growth, and cleanup.
Sparse dirty work must be distinguishable from full-tree capture or hashing.
Dense work may scale with all selected files/bytes.

The selected-case 1–5 second goal after cached preparation is provisional.
Dense 100,000-file rewriting and full verification may need larger qualified
budgets. Freeze per-case target/hard walls before admission; do not claim the
entire 48-sample campaign is a few seconds or silently skip large tiers.

Source grounding and completion

  • sdk_edit_common.rs
    owns the released four labels and bounded generator infrastructure.
  • lifecycle.rs,
    Workspace::commit and Workspaces::edit_workspace_file_ranges, distinguish
    clean admission, owner edits, publication, and presentation.
  • changes.rs,
    try_build_localized_candidate, base_manifest, and final_manifest,
    motivates measuring whole-tree and dirty-frontier dependence.
  • file_io.rs owns ordinary
    dirty file state; client.rs
    defines the public singular SDK entrypoint.

Completion requires all 16 members, full-tree proofs, qualified fixture/source
identities, bounded samples, cleanup, and pre-admission budgets. Product changes
follow measured causes rather than a prescribed optimization.

Activity

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

    @yifanxuaaa
    ContributorAuthor

    Performance-results checkpoint for #28: 42 independently validated active VM8 performance samples. The report validates 0 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
    workspace-clean-commit-1 3 15.077 2.986 3.366 0.000 0/3
    workspace-clean-commit-10 3 15.095 2.963 3.346 0.000 0/3
    workspace-clean-commit-100 3 14.234 3.345 3.756 0.000 0/3
    workspace-clean-commit-500 3 14.697 4.410 4.798 0.000 0/3
    workspace-dense-rewrite-1 3 670.320 1.529 2.715 2.375 0/3
    workspace-dense-rewrite-10 3 6103.153 1.557 8.319 18.000 0/3
    workspace-distributed-sdk-edit-1 3 64.033 1.508 1.955 0.000 0/3
    workspace-distributed-sdk-edit-10 3 88.606 1.508 1.981 0.188 0/3
    workspace-distributed-sdk-edit-100 3 279.633 1.515 2.208 1.125 0/3
    workspace-distributed-sdk-edit-500 3 1095.142 1.503 3.071 4.875 0/3
    workspace-fixed-move-1 3 29.088 0.494 0.898 0.000 0/3
    workspace-fixed-move-10 3 31.054 0.494 0.919 0.062 0/3
    workspace-fixed-move-100 3 60.468 0.699 1.135 0.062 0/3
    workspace-fixed-move-500 3 244.972 1.552 2.206 0.062 0/3

    Explicit Phase1 suppressions (not passing coverage): workspace-dense-rewrite-100, workspace-dense-rewrite-500. Definitions, historical failures and incomplete attempts remain retained for Phase2.

    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

    The user has amended Phase 1 acceptance: qualified fast verification is sufficient for routine benchmark verification. The published amendment supersedes earlier comments requiring every routine exhaustive proof before closure. The reference qualification contract preserves independent expected states, affected-content/metadata/alias/absence checks, authenticated references and deterministic witnesses.

    The posted performance results remain valid at their original source/environment identities. Completed full proofs remain accepted and are reused. At the scope checkpoint,48 routine slots already had full proofs; the305 unrun routine exhaustive counterparts are now deferred to Phase2 while their qualified fast checks are implemented and collected. Fast evidence keeps its actual assurance and explicit skipped coverage; it will not be labelled fully_verified.

    Required targeted reliability checks, the CDC boundary proof, exact expected-error oracles, resource and cleanup gates still apply. Observed failures still require focused repair confirmation. The already-qualified600-second proof is retained rather than repeated. This amendment does not manufacture missing evidence or itself establish terminal pass.

    Remaining routine families will close after their accepted fast/full coverage and applicable gates pass. #21 remains open for later phases and release.

  4. yifanxuaaa commented on Sep 4, 2026

    @yifanxuaaa
    ContributorAuthor

    Rename-cache repair performance update for #28: 12 corrected performance samples independently qualified PASS, with zero validation issues or resource violations. These are performance results, not a declaration that every remaining routine verification or the global terminal gate is complete.

    Actual runtime source: e0922904e2bb607a138157755dab9613b441d5b9. All 12 fixed-move performance samples now use the corrected source. The other 30 active locality samples retain their previously qualified source and values. The family therefore has 42 active performance samples; dense-rewrite tiers 100 and 500 remain suppressed. Clean Commit and owner SDK edit routes retain their distinct operation contracts.

    The repair corrects optimistic Rename cache handling after the hard-link alias proof exposed a stale cached link count. The targeted repaired hard-link proof is independently qualified at this source; its original failed attempt remains preserved. This change required 33 replacement timings across #27/#28/#29. All 33 passed qualification once; the campaign keeps 337 other qualified timings at their original producing sources, for 370 active performance samples. There are still 15 suppressed case IDs, with no new suppression from this collection.

    Medians below use the three seeds of each exact corrected case. Different tiers, earlier source revisions and retained samples are not pooled. Pure-call time is the sum of the declared public product phases; preparation is reported separately. Store delta is the physical SQLite Store file-length delta, not a canonical-byte or logical-data measurement.

    Case n Pure calls (ms) Exec (ms) Commit (ms) Preparation (s) Store file delta (MiB) Source
    workspace-fixed-move-1 3 26.345 9.431 3.731 2.379 0.000 e0922904
    workspace-fixed-move-10 3 32.639 11.812 6.600 2.372 0.062 e0922904
    workspace-fixed-move-100 3 52.789 10.488 29.597 2.651 0.062 e0922904
    workspace-fixed-move-500 3 188.365 11.527 164.575 3.956 0.062 e0922904

    Evidence: 33-sample qualification checkpoint, exact corrected rows and attempt seals, per-case median data, and sealed repaired hard-link full proof.

    Retained evidence: source selections and compatibility predicates, prior qualified VM8 report, and the earlier read-only Pin replacement checkpoint. The older affected 33 timings remain historical observations and are excluded from the corrected medians; no speedup or old/new cost-equivalence claim is made.

    The fast-verification amendment permits qualified fast_iteration_verified assurance for routine Phase 1 cases while keeping skipped work explicit. It does not turn fast results into fully_verified. The 29 required targeted proofs are qualified through separate sealed receipts. Remaining routine acceptance, resource, cleanup and source joins still belong to the final report. Suppressed and failed outcomes retain their actual status. Central issue #21 stays open.

  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