From b10d5eee8835558df32dd9e71ddcefe6a2306900 Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Sun, 9 Aug 2026 18:38:04 +0200 Subject: [PATCH] Declare a raised index-run ceiling without naming a cause `run_conditions.index_run_ceiling` offered one value for a raise, and it named a reason: `raised_because_index_sealing_unimplemented`. The emitter never established that reason. It derives the declaration by comparing the configured ceiling with the store default, and a comparison of two numbers cannot know why they differ -- so the bundle asserted a cause on the strength of a subtraction. That was accurate while the unimplemented seal was the only reason to raise the ceiling. Sealing landed, the raise was dropped, and the value became a false explanation waiting for the next run that raises the ceiling for any other purpose -- which the schema would have called valid. `raised_above_store_default` is added and is what the emitter now writes. It states the fact the comparison establishes and stops there. The old spelling is retained and deprecated rather than removed. `schema_version` is `const: 1`, so there is no later version to move archived bundles to, and this repository has never held a bundle to check against; the reference machine may hold ones that declare it. Invalidating evidence already produced is worse than carrying a spelling nothing emits. Deprecated does not mean unchecked, and that was the trap. The `allOf` rule flooring a declared raise at 65 accepts either spelling, so a bundle using the old one is still cross-checked against the recorded ceiling. Had the rule kept keying on the new string alone, the deprecated value would have skipped the cross-check entirely and been valid while recording 64. `both_raised_spellings_are_accepted_and_bound_the_same_way` asserts, for each spelling, that it validates and that it is refused when it records the store default; narrowing the rule to the new value alone fails it. The protocol crate's `submit_path_bundle` keeps the deprecated spelling deliberately, as the standing proof that an archived bundle validates. Recorded as contract review 2026-08-09-B. The scope doc's carry-forward closed on the grounds that the enum was untouched -- true then, superseded now -- so it carries an amendment rather than a rewrite, and its "truthful values today" table now points at the corrections recorded elsewhere in the same document. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01JGdH5V43XWnj1PdHqiPktQ --- bench/result-schema.json | 10 +++-- .../tests/phase0_benchmark_contracts.rs | 45 +++++++++++++++++++ crates/levcs-store/src/bin/store-bench.rs | 19 +++++--- doc/instance-throughput-rewrite-plan.md | 36 +++++++++++++++ doc/phase1-storage-spine-scope.md | 17 +++++-- 5 files changed, 116 insertions(+), 11 deletions(-) diff --git a/bench/result-schema.json b/bench/result-schema.json index 57ac257..13830e1 100644 --- a/bench/result-schema.json +++ b/bench/result-schema.json @@ -560,9 +560,10 @@ "index_run_ceiling": { "enum": [ "store_default", + "raised_above_store_default", "raised_because_index_sealing_unimplemented" ], - "description": "Whether StoreOptions::max_index_runs was left at the store default (64) or raised so the run could reach its measured seconds despite unimplemented index-delta sealing. Cross-checked against resources.configured_ceilings.max_index_runs by the two \"index run ceiling\" rules in allOf: \"store_default\" bounds the recorded value at 64 and the raised value floors it at 65, so a bundle that declares one and records the other is invalid. The recorded value must be the value the run configured, never a constant restated here." + "description": "Whether StoreOptions::max_index_runs was left at the store default (64) or raised above it. Cross-checked against resources.configured_ceilings.max_index_runs by the two \"index run ceiling\" rules in allOf: \"store_default\" bounds the recorded value at 64 and either raised value floors it at 65, so a bundle that declares one and records the other is invalid. The recorded value must be the value the run configured, never a constant restated here. DEPRECATED: \"raised_because_index_sealing_unimplemented\" is accepted only so archived v1 bundles stay valid; index-delta sealing is implemented and the emitter no longer produces it. It states a cause the emitter never verified — the declaration is derived by comparing the configured ceiling with the store default, so it named a reason for a fact it only observed. Emit \"raised_above_store_default\", which is that fact and nothing more. Contract review 2026-08-09-B." }, "receipt_reconciliation": { "enum": [ @@ -782,7 +783,7 @@ "max_index_runs": { "type": "integer", "minimum": 1, - "description": "The StoreOptions::max_index_runs the run actually configured, read back from the options the store opened with — never the store default restated here, and never omitted. Bounded against run_conditions.index_run_ceiling by the two \"index run ceiling\" rules in allOf, so a defaulted or contradicted value is invalid rather than merely unverified. It is a ceiling this workload genuinely reaches: index-delta sealing being unimplemented makes it the limit submit refuses at." + "description": "The StoreOptions::max_index_runs the run actually configured, read back from the options the store opened with — never the store default restated here, and never omitted. Bounded against run_conditions.index_run_ceiling by the two \"index run ceiling\" rules in allOf, so a defaulted or contradicted value is invalid rather than merely unverified. It is a ceiling this workload genuinely reaches: the run seals against it, and its fan-out trigger is what imposes the steady state a P2 number has to be measured in." } }, "additionalProperties": { @@ -1574,7 +1575,10 @@ "run_conditions": { "properties": { "index_run_ceiling": { - "const": "raised_because_index_sealing_unimplemented" + "enum": [ + "raised_above_store_default", + "raised_because_index_sealing_unimplemented" + ] } }, "required": [ diff --git a/crates/levcs-protocol/tests/phase0_benchmark_contracts.rs b/crates/levcs-protocol/tests/phase0_benchmark_contracts.rs index c32f9dc..672d37a 100644 --- a/crates/levcs-protocol/tests/phase0_benchmark_contracts.rs +++ b/crates/levcs-protocol/tests/phase0_benchmark_contracts.rs @@ -944,6 +944,11 @@ fn submit_path_bundle() -> serde_json::Value { "mutation_path": "store_engine_submit", "checkpointing": "unimplemented", "index_maintenance": "deltas_retained_in_memory", + // Deliberately the deprecated spelling: this fixture is the standing + // proof that an archived v1 bundle still validates. The emitter + // writes `raised_above_store_default` now, and + // `both_raised_spellings_are_accepted_and_bound_the_same_way` + // covers the pair. Contract review 2026-08-09-B. "index_run_ceiling": "raised_because_index_sealing_unimplemented", "receipt_reconciliation": "acceptance_of_any_committed_status", "objects_new_source": "summed_from_receipts", @@ -1513,3 +1518,43 @@ fn the_instance_gates_are_not_loosened_by_the_storage_path_split() { ); } } + +/// Both spellings of a raised ceiling are accepted, and both are bound the same +/// way. +/// +/// The deprecated one is kept only so an archived v1 bundle stays valid -- +/// `schema_version` is `const: 1`, so there is no later version to move it to, +/// and this repository has never held a bundle to check against. What must not +/// happen is the deprecation becoming a second, weaker rule: a bundle that +/// declares the old string still has to record a ceiling above the default, or +/// "deprecated" would have quietly turned into "unchecked". +/// +/// The new spelling states only what the emitter observes. It compares the +/// configured ceiling with the store default and cannot know why they differ, +/// so it may not name a cause -- which is exactly what the old string did, for +/// a cause that is no longer true. Contract review 2026-08-09-B. +#[test] +fn both_raised_spellings_are_accepted_and_bound_the_same_way() { + for spelling in [ + "raised_above_store_default", + "raised_because_index_sealing_unimplemented", + ] { + let mut bundle = submit_path_bundle(); + bundle["run_conditions"]["index_run_ceiling"] = serde_json::json!(spelling); + assert_valid( + &bundle, + &format!("{spelling} must be an accepted declaration of a raised ceiling"), + ); + + // The floor still applies. Recording the store default under either + // spelling is a bundle whose declaration and measurement disagree. + bundle["resources"]["configured_ceilings"]["max_index_runs"] = serde_json::json!(64); + assert_invalid( + &bundle, + &format!( + "{spelling} recording the store default must be refused; a deprecated \ + spelling is still cross-checked" + ), + ); + } +} diff --git a/crates/levcs-store/src/bin/store-bench.rs b/crates/levcs-store/src/bin/store-bench.rs index c3683f8..0e2a82d 100644 --- a/crates/levcs-store/src/bin/store-bench.rs +++ b/crates/levcs-store/src/bin/store-bench.rs @@ -1176,7 +1176,14 @@ impl RunConditions { if observations.configured_max_index_runs == observations.default_max_index_runs { "store_default" } else if observations.configured_max_index_runs > observations.default_max_index_runs { - "raised_because_index_sealing_unimplemented" + // The fact, and only the fact. This branch is reached by + // comparing two numbers and knows nothing about *why* the + // ceiling was raised, so it may not name a reason. + // `raised_because_index_sealing_unimplemented` did, and the + // reason it named is no longer true; the schema keeps accepting + // it for archived bundles and this emitter never writes it + // again. Contract review 2026-08-09-B. + "raised_above_store_default" } else { return Err(format!( "refusing to emit a bundle: the run configured max_index_runs = {} below \ @@ -5149,12 +5156,14 @@ sys.exit(1 if errors else 0) assert_eq!(submit.initialization_path, "store_engine_open"); assert_eq!(submit.mutation_path, "store_engine_submit"); assert_eq!( - submit.index_run_ceiling, "raised_because_index_sealing_unimplemented", + submit.index_run_ceiling, "raised_above_store_default", "this fixture configures max_index_runs above the store default, and the \ declaration must follow from that comparison rather than from the path. \ The measured submit run no longer raises it -- see \ `a_run_at_the_store_default_declares_store_default` -- so this is the \ - only remaining cover for the raised branch" + only remaining cover for the raised branch. It must be the reason-free \ + value: this branch compares two numbers and cannot know why they differ \ + (contract review 2026-08-09-B)" ); assert_eq!(submit.index_maintenance, "deltas_retained_in_memory"); assert_eq!( @@ -6063,7 +6072,7 @@ sys.exit(1 if errors else 0) refuses( &submit, submit.replace( - "\"index_run_ceiling\": \"raised_because_index_sealing_unimplemented\"", + "\"index_run_ceiling\": \"raised_above_store_default\"", "\"index_run_ceiling\": \"store_default\"", ), "declaring the store default while recording a raised ceiling must be \ @@ -6074,7 +6083,7 @@ sys.exit(1 if errors else 0) &bundle, bundle.replace( "\"index_run_ceiling\": \"store_default\"", - "\"index_run_ceiling\": \"raised_because_index_sealing_unimplemented\"", + "\"index_run_ceiling\": \"raised_above_store_default\"", ), "declaring a raise while recording the default must be rejected in the \ other direction", diff --git a/doc/instance-throughput-rewrite-plan.md b/doc/instance-throughput-rewrite-plan.md index ffb9a74..743194b 100644 --- a/doc/instance-throughput-rewrite-plan.md +++ b/doc/instance-throughput-rewrite-plan.md @@ -1839,6 +1839,42 @@ The integration suite's `cleanup_is_deferred_and_names_its_deliverable` is repla deleted — the distinction it stood for, that "nothing to do" and "cannot answer yet" are different results, is now asserted the other way round at the public surface. +##### Contract review 2026-08-09-B + +`bench/result-schema.json` — `run_conditions.index_run_ceiling`. Requested after index-delta +sealing landed, because the enum's only raised value names a cause that is no longer true and +that nothing ever verified. One value is added, none is removed. + +**The declaration was never a claim about *why*.** `store-bench.rs` derives it by comparing the +configured ceiling with the store default; that comparison cannot know what motivated a raise. +It nevertheless emitted `raised_because_index_sealing_unimplemented`, so the bundle asserted a +cause on the strength of a subtraction. That was accurate while the only reason to raise the +ceiling was the unimplemented seal. It is not accurate now, and a future run raising the ceiling +for any other reason — deliberately measuring fan-out, say — would have emitted a false +explanation that the schema called valid. + +**`raised_above_store_default` is added and is what the emitter now writes.** It states the fact +the comparison establishes and stops there. + +**The old value is retained and deprecated, not removed.** `schema_version` is `const: 1`, so +there is no later version to move archived bundles to, and this repository has never held a +bundle to check against — the reference machine may hold ones that declare it. Removing it would +invalidate evidence already produced, which is a worse outcome than carrying a spelling nothing +emits. It is retained **solely so archived v1 bundles validate, and is not a current causal +claim**; the enum's description says so. + +**Deprecated does not mean unchecked.** The `allOf` rule that floors a declared raise at 65 +accepts either spelling, so a bundle using the old string is still cross-checked against +`resources.configured_ceilings.max_index_runs`. +`both_raised_spellings_are_accepted_and_bound_the_same_way` asserts both halves — that each +validates, and that each is refused when it records the store default. Verified by mutation: +narrowing the rule to the new spelling alone makes the deprecated one silently unchecked and +fails that test. + +The `configured_ceilings.max_index_runs` description carried the same causal claim and now +records what is true — the run seals against that ceiling, and its fan-out trigger is what +imposes the steady state a P2 number must be measured in. + ##### Contract review 2026-08-09-A B1 deliverable 3 — `adopt_projection` through submit. Requested by B1 on starting the wiring, diff --git a/doc/phase1-storage-spine-scope.md b/doc/phase1-storage-spine-scope.md index c2cba45..c3fb117 100644 --- a/doc/phase1-storage-spine-scope.md +++ b/doc/phase1-storage-spine-scope.md @@ -2035,9 +2035,9 @@ and `scripts/verify-store-recovery.sh --cycles 2` reports `bundle=schema-valid` |---|---|---| | `initialization_path` | `store_engine_open` (see **f**) | `shard_drive_create` | | `mutation_path` | `store_engine_submit` | `journal_drive` | - | `checkpointing` | `unimplemented` | `unimplemented` | + | `checkpointing` | `enabled_not_reached` (see §7) | `unimplemented` | | `index_maintenance` | `deltas_retained_in_memory` | `no_index_in_path` | - | `index_run_ceiling` | `raised_because_index_sealing_unimplemented` | `store_default` | + | `index_run_ceiling` | `store_default` (see the carry-forward below) | `store_default` | | `receipt_reconciliation` | `acceptance_of_any_committed_status` | `no_receipts_in_path` | | `objects_new_source` | `summed_from_receipts` | `derived_from_transaction_count` | | `commit_id_uniqueness` | `checked_globally_across_ack_records` (after **d**) | `not_checked` | @@ -2103,7 +2103,9 @@ before: 1. **The emitted `run_conditions.index_run_ceiling` names a reason that is no longer true.** The derivation is correct — it compares the configured ceiling to the store default and reports a raise, so it cannot drift from what the run configured — but the only enum value - the schema offers for a raise is `raised_because_index_sealing_unimplemented`. + the schema offers for a raise is `raised_because_index_sealing_unimplemented`. (Amended + 2026-08-09-B: the schema now also offers `raised_above_store_default`, which is what a + comparison can honestly report.) 2. **The raise now suppresses a behaviour the store has.** At a ceiling of a million, the fan-out trigger never fires, so every seal in a measured run is triggered by entry pressure. `index_maintenance = runs_sealed` is therefore true and narrower than it reads, and a P2 run @@ -2124,6 +2126,15 @@ and they were not equivalent: assumed.** The store is opened at its own default and `ENGINE_MAX_INDEX_RUNS` is retired; the schema enum is untouched, so no contract review was needed. +**Amended 2026-08-09 by contract review 2026-08-09-B, for the other reason.** Finding 1 above +was closed by no longer *emitting* the raised value, which left the value itself still naming a +lapsed cause — harmless while nothing raised the ceiling, and a false explanation the moment +anything did, since the emitter derives the declaration from a comparison and cannot know why +two numbers differ. `raised_above_store_default` is added and is what the emitter writes; +`raised_because_index_sealing_unimplemented` is retained, deprecated, and still cross-checked, +solely so archived v1 bundles validate. That is an enum amendment, so it *was* a contract +review — requested rather than emitted, per item 4. + The demonstration is the part that mattered, because the whole question was whether a run survives the ceiling it had been raised to escape. A 45-second submit-path run at `max_index_runs = 64` published **5,192 groups** — 81× the ceiling — with no `NotImplemented`