diff --git a/DESIGN.md b/DESIGN.md index 8497154d7c1..c34bbe71ec6 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -67,7 +67,7 @@ THE RULE IS ABOUT LAYERS, AND COST IS ONLY ITS SYMPTOM. A claim reaches too far When two structures answer the same semantic question and one is intended to disappear, the change is a **replacement migration**, not a refinement. §2 prices an intermediate representation destined to be discarded as redundant work, and §3 forbids X and Y both answering for one fact. Editing X from its leaves upward preserves its root while every intermediate state becomes observable and load-bearing, so the migration creates more authority before it removes any. The deeper cost is that a surviving X is an **attractor**: while it stands, every nearby question is answered in its vocabulary, so decisions keep being premised on an assumption already scheduled for death — and A3 grounds agreement only on what stays stable across time, which a dead assumption by definition does not. -So the default is **delete-first**: uproot the root as early as you can, then fix forward minimally with the new solution, solving each surfaced problem from first principles rather than restoring it to its old binding. In a fail-closed substrate **the deletion is the census** — every real dependent refuses loudly, so what breaks is exactly what was load-bearing. What cannot break loudly is covered by a declared, bounded §4b rung-drop, never by silence. Two carve-outs: a gap-intolerant boundary keeps the staged form — Y built in shadow, then one transition that switches the root and deletes X together — and where no Y can hold the boundary at all, X stays but stays **frozen**: no new investment, no new rows on its growth surfaces. +So the default is **delete-first**: uproot the root as early as you can, then fix forward minimally with the new solution, solving each surfaced problem from first principles rather than restoring it to its old binding. In a fail-closed substrate **the deletion is the census — but only over the population a run compiles**. Every real dependent refuses loudly, so what breaks is exactly what was load-bearing. Outside the required gate (`v2.workflow.required_floor required_gate_prefixes`) the substrate still refuses and nothing asks it to: a product-layer dependent can stop resolving, stay broken, and let every required lane report SUCCESS — so **for a root outside the gate, enumerate the consumers by name before you delete**. What cannot break loudly is covered by a declared, bounded §4b rung-drop, never by silence. Two carve-outs: a gap-intolerant boundary keeps the staged form — Y built in shadow, then one transition that switches the root and deletes X together — and where no Y can hold the boundary at all, X stays but stays **frozen**: no new investment, no new rows on its growth surfaces. **"Atomic" describes the authority transition, not the amount of implementation work.** Y has one coherent root, ordinary production never accumulates consumers that understand both representations, and X's authority ends in one motion. Y may freely reuse stable primitives, and X may serve from history as an offline differential oracle — but Y never falls back to X, resolves through it, or derives its answer from it. And the minimum Y is not the smallest thing that executes the happy path: it must preserve every required refusal, or it has erased a correctness distinction rather than completed the replacement. diff --git a/dag/gunbc/design_document.dag b/dag/gunbc/design_document.dag index c38efeeb0cc..35a804ce11d 100644 --- a/dag/gunbc/design_document.dag +++ b/dag/gunbc/design_document.dag @@ -10,6 +10,7 @@ import extdeps.languages.markdown { serialize_markdown_source } import gunbc.documentary_refs { documentary_ref_symbol_text, v1_maintenance_standing_ref, + required_gate_prefixes_ref, } import gunbc.design_argument { conformance_domains, ConformanceDomain, conformance_home_list } import gunbc.roadmap.roadmap_review_criteria { review_home_text } @@ -75,7 +76,9 @@ fn section_3_blocks() -> List { p(text: "The failure the pairing catches is not hypothetical and it is quiet. A designed fixture can keep passing after the world it was designed against moves, by reaching the same verdict through a DIFFERENT mechanism than the one the claim exists to exercise — so the claim is green, its assertion is true, and the wall it was built to be is gone. That is why the inhabitance claim must assert the ROUTE and not only the answer."), p(text: "THE RULE IS ABOUT LAYERS, AND COST IS ONLY ITS SYMPTOM. A claim reaches too far the moment its subject stops being ONE interface, and the reach is usually transitive rather than written: a fold that assembles a report from fifteen producers gives any claim over it the union of their subjects. The sharpest form is a claim that re-executes ANOTHER MODULE'S CLAIM FUNCTIONS — each of those already has its own subject and its own discriminating red, so re-running them asserts nothing new and pays for all of it again, which is §2's duplicated work wearing a test's clothes. Its enabling condition is a LAYER INVERSION worth refusing on its own: a production module that imports `test.claim.*` has made every consumer of that module a transitive consumer of those claims. RECEIPT (gunbc#11457): `gunbc.demo.semantic_system_readout` imported five witness modules and called thirteen of their claim functions; one claim over its fold measured 1,212,647 eval steps and 3,743ms against a 302ms enrolment margin, and TWO REVIEWERS APPROVED IT, one citing it as satisfying the pairing obligation. So the budget refusal is the tell that fires, not the rule that was broken — a cheap claim reaching the same way is the same defect undetected, and the remedy is to supply the values and keep ONE inhabitance claim for the real path, never to buy the reach with a debt row."), h3(text: "§3 standing rule — replacement migrations cut over at the root"), p(text: "When two structures answer the same semantic question and one is intended to disappear, the change is a **replacement migration**, not a refinement. §2 prices an intermediate representation destined to be discarded as redundant work, and §3 forbids X and Y both answering for one fact. Editing X from its leaves upward preserves its root while every intermediate state becomes observable and load-bearing, so the migration creates more authority before it removes any. The deeper cost is that a surviving X is an **attractor**: while it stands, every nearby question is answered in its vocabulary, so decisions keep being premised on an assumption already scheduled for death — and A3 grounds agreement only on what stays stable across time, which a dead assumption by definition does not."), - p(text: "So the default is **delete-first**: uproot the root as early as you can, then fix forward minimally with the new solution, solving each surfaced problem from first principles rather than restoring it to its old binding. In a fail-closed substrate **the deletion is the census** — every real dependent refuses loudly, so what breaks is exactly what was load-bearing. What cannot break loudly is covered by a declared, bounded §4b rung-drop, never by silence. Two carve-outs: a gap-intolerant boundary keeps the staged form — Y built in shadow, then one transition that switches the root and deletes X together — and where no Y can hold the boundary at all, X stays but stays **frozen**: no new investment, no new rows on its growth surfaces."), + p(text: concat("So the default is **delete-first**: uproot the root as early as you can, then fix forward minimally with the new solution, solving each surfaced problem from first principles rather than restoring it to its old binding. In a fail-closed substrate **the deletion is the census — but only over the population a run compiles**. Every real dependent refuses loudly, so what breaks is exactly what was load-bearing. Outside the required gate (", + concat(documentary_ref_symbol_text(reference: required_gate_prefixes_ref), + ") the substrate still refuses and nothing asks it to: a product-layer dependent can stop resolving, stay broken, and let every required lane report SUCCESS — so **for a root outside the gate, enumerate the consumers by name before you delete**. What cannot break loudly is covered by a declared, bounded §4b rung-drop, never by silence. Two carve-outs: a gap-intolerant boundary keeps the staged form — Y built in shadow, then one transition that switches the root and deletes X together — and where no Y can hold the boundary at all, X stays but stays **frozen**: no new investment, no new rows on its growth surfaces."))), p(text: "**\"Atomic\" describes the authority transition, not the amount of implementation work.** Y has one coherent root, ordinary production never accumulates consumers that understand both representations, and X's authority ends in one motion. Y may freely reuse stable primitives, and X may serve from history as an offline differential oracle — but Y never falls back to X, resolves through it, or derives its answer from it. And the minimum Y is not the smallest thing that executes the happy path: it must preserve every required refusal, or it has erased a correctness distinction rather than completed the replacement."), p(text: concat("The frozen-X carve-out is the wrong state for a production-critical X whose replacement was paused indefinitely, which is the v1 seed's situation. v1 is therefore reclassified — semantics frozen, maintenance active — under a PURPOSE admission test: a change is admitted when it serves the v2 self-host program, and v1 stays closed to growth for its own sake. The authority is ", concat(documentary_ref_symbol_text(reference: v1_maintenance_standing_ref), diff --git a/dag/gunbc/documentary_refs.dag b/dag/gunbc/documentary_refs.dag index 99f156d1881..f975d1cbbdb 100644 --- a/dag/gunbc/documentary_refs.dag +++ b/dag/gunbc/documentary_refs.dag @@ -2,7 +2,6 @@ module gunbc.documentary_refs import std.types { String } import std.decl_ref { DeclarationRef, decl_ref } -import gunbc.doc_graph_roots { hand_authored_doc_declaration_refs } // THE SYSTEMS A GENERATED DOCUMENT NAMES, CARRIED AS TYPED REFERENCES RATHER THAN SPELLED IN PROSE. // gunbc.doc_graph_roots already does exactly this for HAND-AUTHORED documents: HandAuthoredDocBind @@ -37,21 +36,12 @@ import gunbc.doc_graph_roots { hand_authored_doc_declaration_refs } data v1_maintenance_standing_ref: DeclarationRef = decl_ref(module_path: "gunbc.v1_maintenance_standing", decl_name: "v1_seed_standing") +data required_gate_prefixes_ref: DeclarationRef = decl_ref(module_path: "v2.workflow.required_floor", decl_name: "required_gate_prefixes") + fn documentary_ref_symbol_text(reference: DeclarationRef) -> String { concat("`", reference.module_path as String, " ", reference.decl_name as String, "`") } fn generated_document_declaration_refs() -> List { - [v1_maintenance_standing_ref] -} - -// ONE POPULATION, TWO SOURCES, AND THE UNION IS THE POINT. The cited-symbol lens already had a -// denominator; it counted hand-authored binds only, so a generated document could name a system -// that no longer existed and stay green while a hand-authored document naming the same system -// reddened. Widening the denominator rather than adding a second resolution algorithm keeps -// v2.std.decl_ref_resolution the single authority for what resolving a reference means -- a second -// algorithm agreeing today is a fork that disagrees later. - -fn all_documentary_declaration_refs() -> List { - concat(hand_authored_doc_declaration_refs(), generated_document_declaration_refs()) + [v1_maintenance_standing_ref, required_gate_prefixes_ref] } diff --git a/dag/test/claim/documentary_refs_witness_test.dag b/dag/test/claim/documentary_refs_witness_test.dag index 4dff7de0270..72b304b0b35 100644 --- a/dag/test/claim/documentary_refs_witness_test.dag +++ b/dag/test/claim/documentary_refs_witness_test.dag @@ -1,19 +1,17 @@ module test.claim.documentary_refs_witness import std.types { Bool, String } -import v2.std.algebra { length, contains } import std.decl_ref { DeclarationRef, WholeDeclaration } import v2.lens.module_graph { ModuleDeclarationFact } import v2.std.decl_index { DeclFact, FnItem, TypeItem } import v2.lens.enforcement.receipts { enforcement_red_probe_body_leaf } import v2.std.decl_ref_resolution { cited_declaration_ref_refusal_count } import gunbc.documentary_refs { - all_documentary_declaration_refs, documentary_ref_symbol_text, generated_document_declaration_refs, v1_maintenance_standing_ref, + required_gate_prefixes_ref, } -import gunbc.doc_graph_roots { hand_authored_doc_declaration_refs } import gunbc.design_document { expected_design_md } // THE PERTURBATIONS ARE THE POINT, AND EACH RUNS AGAINST THE SAME RESOLVER PRODUCTION USES. @@ -30,6 +28,7 @@ fn fixture_modules() -> List { ModuleDeclarationFact { module: "v2.compiler.resolve", path: "src/v2/compiler/03_resolve.dag" }, ModuleDeclarationFact { module: "gunbc.roadmap_authority", path: "dag/gunbc/roadmap/roadmap_authority.dag" }, ModuleDeclarationFact { module: "gunbc.v1_maintenance_standing", path: "dag/gunbc/v1/v1_maintenance_standing.dag" }, + ModuleDeclarationFact { module: "v2.workflow.required_floor", path: "src/v2/workflow/required_floor.dag" }, ] } @@ -43,10 +42,18 @@ fn fixture_fact(qualified_name: String, name: String, path: String) -> DeclFact } } -// The four declarations the generated document names, present exactly once each. This is the +// The declarations the generated document names, present exactly once each, one per row of +// generated_document_declaration_refs(). This is the // control that proves the refusals below are caused by the perturbation rather than by a fixture // that never resolved anything. - +// +// THE `v2.` PREFIX IS ABSENT FROM THE required_gate_prefixes FACT ON PURPOSE AND IS NOT A TYPO. A +// DeclFact carries the LOGICAL qualified name: v2.std.decl_index logical_qualified_name_from_module +// strips a leading `v2.` when it builds the name the resolver matches on, while +// module_path_declared compares the module row against the FULL path. So fixture_modules() says +// `v2.workflow.required_floor` and the fact says `workflow.required_floor.required_gate_prefixes`, +// and both are correct. The asymmetry was invisible until that row, because the only other fact +// here names a `gunbc.` module with nothing to strip. fn intact_facts() -> List { [ fixture_fact( @@ -54,6 +61,11 @@ fn intact_facts() -> List { name: "v1_seed_standing", path: "dag/gunbc/v1/v1_maintenance_standing.dag", ), + fixture_fact( + qualified_name: "workflow.required_floor.required_gate_prefixes", + name: "required_gate_prefixes", + path: "src/v2/workflow/required_floor.dag", + ), ] } @@ -120,32 +132,6 @@ test fn documentary_refs_ambiguous_system_refuses() -> Bool { test fn documentary_refs_generated_document_renders_the_rows() -> Bool { let md = expected_design_md() string_contains(s: md, pattern: documentary_ref_symbol_text(reference: v1_maintenance_standing_ref)) + && string_contains(s: md, pattern: documentary_ref_symbol_text(reference: required_gate_prefixes_ref)) } -// The widened denominator is asserted directly, because a union that silently dropped one side -// would leave exactly the exemption this change removes: the generated refs must all be present in -// the combined population, and the combined population must be larger than the hand-authored one -// alone. - -// A NEGATIVE PROSE CHECK STOOD HERE AND WAS DELETED RATHER THAN REPAIRED. It asserted the generated -// document no longer contains the substring 'six-step', to show the superseded numbered sequence is -// gone. It failed -- and it failed CORRECTLY, because the replacement sentence explains that the -// paragraph previously carried a numbered six-step copy, so the words survive while the copy does -// not. The check could not tell a restatement from an explanation of its removal. -// -// THAT IS THE WHOLE ARGUMENT AGAINST THIS SHAPE, and it is already on record: -// gunbc.roadmap_authority witness_authority_contains_no_mutable_execution_ledger blacklists -// substrings in a status field and is structurally unable to catch a stale claim spelled without -// them. Repairing the needle would have produced a check that passes for this one spelling and -// decides nothing in general -- validation standing where nothing decidable was available. The -// positive claim survives instead, in documentary_refs_generated_document_renders_the_rows: the -// roadmap authority is cited by rendering its typed row, which is a fact a mechanism can actually -// decide. - -test fn documentary_refs_population_is_the_union() -> Bool { - let all_refs = all_documentary_declaration_refs() - let hand = hand_authored_doc_declaration_refs() - let generated = generated_document_declaration_refs() - length(xs: all_refs) == length(xs: hand) + length(xs: generated) - && length(xs: generated) == 1 -}