AILang/docs/specs/0045-design-md-rolesplit.md

DESIGN.md → design/ role-split — Design Spec

Date: 2026-05-19 Status: Draft — awaiting user spec review Authors: Brummel (orchestrator) + Claude

Goal

docs/DESIGN.md is one 3020-line file doing three different jobs for three different consumers with three different lifetimes. The line count is the symptom of role-conflation, not of mess: the just-closed docs-honesty-lint milestone ran a full honesty pass and DESIGN.md stayed 3020 lines, because honesty-lint operates within a job and its own audit-trail invariant mandates retaining the bulky decision-record prose (DESIGN.md Decision 6, lines 241–243: "records the why … for the audit trail"). You cannot clean your way out of conflation; the conflation is the structural defect.

Replace docs/DESIGN.md with a design/ directory split on the consumer/lifetime axis — design/contracts/ (the hot, test-linked invariant set), design/models/ (one whitepaper per model) — with design/INDEX.md as the sole addressable spine. Decision-record prose moves to docs/journals/. The split is a clean cut: docs/DESIGN.md is deleted; every named reference is repointed in one build-atomic milestone.

The three conflated jobs and their distinct consumers:

• Contract — prescriptive, test-linked invariants (Decision 6's binding Form-A constraints, the Roundtrip Invariant, the borrow/own binding rules, the frozen value layout). Consumer: architect (mandatory full read at every milestone close), grounding-check (every spec), the honesty sweep. Wants: structured, addressable, test-linked, small, hot. The only job on the per-milestone hot path.
• Model exposition — whitepaper-shaped narratives (RC + Uniqueness, typeclasses, effects, the authoring-surface rationale). Consumer: onboarding (fresh-context LLM, fieldtester). Irreducible — the code cannot speak the gestalt.
• Decision-record / relitigating-guard — why X was chosen, why Y/Z were rejected (region inference, tracing GC, …). Consumer: a future brainstorm, so it does not re-propose a settled-and- rejected idea. This already has a home — docs/journals/.

Underlying principle: the code is authoritative for what it does; the spec's irreducible job is what is promised plus a pointer to the green test that ratifies it.

Architecture

design/
  INDEX.md                 sole addressable spine — a typed two-table ledger
  contracts/               prose-authoritative invariants (the architect hot path)
    feature-acceptance.md  authoring-surface.md  roundtrip-invariant.md
    memory-model.md        typeclasses.md        float-semantics.md
    frozen-value-layout.md honesty-rule.md       tail-calls.md
    data-model.md          embedding-abi.md      verification.md
  models/                  one whitepaper per model (onboarding path)
    rc-uniqueness.md  typeclasses.md  effects.md  authoring-surface.md  pipeline.md

docs/journals/2026-05-19-design-decision-records.md   relitigation-guard archive
docs/DESIGN.md                                        DELETED (clean cut)

Five structural commitments:

1. Polymorphic INDEX link. An INDEX row's link is either a design/ file or an authoritative source path. Where code is the single source of truth (mangling, env construction, qualified-cross-module-ref resolution), there is no prose contract file — the row points at the source //! header and names the ratifying test, killing the prose-vs-code second truth. frozen-value-layout is the deliberate dual-link exception (a one-way human commitment and a codegen contract → both a prose file and a source pointer). The polymorphic disposition is fixed per-contract in the Components disposition table below.

2. ###-subsection is the unit of relocation. No sentence- surgery. Each ### subsection of DESIGN.md moves whole to contracts/, models/, or the decision-record journal. The MIXED ## Decisions (6/9/10/11) decompose at their existing ### seam, which recon confirmed resolves cleanly.

3. Build-atomic, not just semantically atomic. crates/ailang-core/tests/design_schema_drift.rs:22 uses include_str!("../../../docs/DESIGN.md") — a compile-time path. The instant docs/DESIGN.md is deleted the workspace does not compile until that include_str! is retargeted. The content move + the 4-executable retarget + the 2-diagnostic/2-E2E retarget + the new pin test land in one commit; the tree is never half-moved. This is a fail-closed property, not a hazard.

4. The honesty-rule self-repointing resolves the internal contradiction. Two distinct self-referential passages, with different pin status (grounding-check verified):

   • ### What this document is — and the honesty rule it holds itself to (DESIGN.md:56–82) is pinned: docs_honesty_pin.rs:70 pins "the honesty rule it holds itself to" and :72 pins "whether the document asserts something exists, works, or changed that does not" (both inside design_md_present_tense_anchors_present). This becomes contracts/0007-honesty-rule.md, rewritten so the rule states the new home (rationale → docs/journals/); those two pins are retargeted to the new file and the new wording in the same atomic change.
   • Decision 6's :242 sentence — "The rest of this section records the why of Decision 6 for the audit trail; the constraints listed below describe the surface as shipped." — is pinned by no test anywhere (grounding-check grepped crates/*/tests/, in-source crates/*/src/, effect_doc_honesty_pin.rs: zero matches). It is itself decision-record self-assertion describing the old conflated structure. The milestone retires it: its "why of Decision 6" content moves to the decision-record journal; the meta-sentence that asserts DESIGN.md retains audit-trail prose is not carried forward and needs no successor pin — code never protected it, and should not, because that sentence is exactly the audit-trail self-claim the split removes from the contract surface.

   The internal contradiction (a doc asserting of itself that it "records the why for the audit trail" while the milestone moves the why out) is closed by the milestone: the asserting sentence is retired, and the only honesty self-claim that survives — "rationale lives in docs/journals/" — is the rewritten honesty-rule.md, which the retargeted :70,72 pins protect.

5. Clean cut, no stub, no redirect. docs/DESIGN.md is deleted. No transitional pointer file (a "see elsewhere" file is itself history-pointing — a doc-honesty violation in the milestone that exists to enforce doc honesty). Matches the no-deprecation-window precedent (mut/var/assign removal) and the current-state-mirror discipline.

Concrete code shapes

1. The delivered artifacts (this is an infra milestone — these are the headline)

design/INDEX.md — the typed two-table ledger. link is polymorphic; ratifying-test is mandatory for kind=contract:

# AILang Design — Index

The sole addressable entry point. Every contract and model is
reached from here. A contract is a prescriptive, test-linked
invariant; a model is a whitepaper narrative. `ratifying-test` names
the green test that proves a contract still holds. `link` is
polymorphic: a `design/` file, or the authoritative source `//!`
header when the code is the single source of truth.

## Contracts
| id | consumer / lifetime | ratifying-test | link |
|----|---------------------|----------------|------|
| feature-acceptance   | brainstorm-gate / stable      | skills/brainstorm/SKILL.md Step 4         | contracts/0004-feature-acceptance.md |
| authoring-surface    | LLM author / stable           | crates/ailang-surface round_trip.rs       | contracts/0001-authoring-surface.md |
| roundtrip-invariant  | every release / stable        | crates/ailang-surface round_trip.rs       | contracts/0009-roundtrip-invariant.md |
| memory-model         | LLM author / stable           | crates/ailang-check/src/uniqueness.rs (in-source mod tests) | contracts/0008-memory-model.md |
| data-model           | LLM author / stable           | crates/ailang-core/tests/design_schema_drift.rs | contracts/0002-data-model.md |
| mangling             | codegen / stable              | crates/ail/tests/eq_ord_e2e.rs            | crates/ailang-codegen/src/lib.rs //! |
| env-construction     | codegen / stable              | crates/ailang-check/tests/duplicate_ctor_pin.rs | crates/ailang-codegen/src/lib.rs //! |
| qualified-xref       | codegen / stable              | crates/ail/tests/codegen_import_map_fallback_pin.rs | crates/ail/src/main.rs //! |
| frozen-value-layout  | embedding ABI / one-way-frozen| crates/ailang-codegen/tests/embed_record_layout_pin.rs | contracts/0006-frozen-value-layout.md + runtime/rc.c §layout |
| float-semantics      | LLM author / stable           | crates/ail/tests/eq_float_noinstance.rs   | contracts/0005-float-semantics.md |
| typeclasses          | LLM author / stable           | crates/ail/tests/show_no_instance_e2e.rs  | contracts/0013-typeclasses.md |
| str-abi              | runtime ABI / stable          | crates/ail/tests/e2e.rs (Str path)        | contracts/0011-str-abi.md + runtime/str.c §heap-Str |
| tail-calls           | codegen / stable              | crates/ailang-check/src/lib.rs (in-source tail_call_in_non_tail_position_is_rejected) | contracts/0012-tail-calls.md |
| honesty-rule         | architect+grounding / stable  | crates/ailang-core/tests/docs_honesty_pin.rs | contracts/0007-honesty-rule.md |
| embedding-abi        | embedding host / stable       | crates/ailang-codegen/tests/embed_record_layout_pin.rs | contracts/0003-embedding-abi.md |
| scope-boundaries     | architect+author / stable     | crates/ailang-core/tests/effect_doc_honesty_pin.rs | contracts/0010-scope-boundaries.md |
| verification         | architect / stable            | bench/architect_sweeps.sh                 | contracts/0014-verification.md |

## Models
| id | consumer / lifetime | link |
|----|---------------------|------|
| rc-uniqueness     | onboarding / evolves | models/0004-rc-uniqueness.md |
| typeclasses       | onboarding / evolves | models/0005-typeclasses.md |
| effects           | onboarding / evolves | models/0002-effects.md |
| authoring-surface | onboarding / evolves | models/0001-authoring-surface.md |
| pipeline          | onboarding / evolves | models/0003-pipeline.md |

The ratifying-test column above is now Boss-resolved to exact recon-verified paths (plan-recon confirmed each file exists; the design_index_pin.rs clause-2 check, widened to accept crates/**/src/*.rs in-source #[cfg(test)] mod tests, requires every token to resolve to a real file). The full per-### relocation map and the adjudication rationale for the three ledger additions (qualified-xref, str-abi, scope-boundaries) are in the Appendix — Boss-adjudicated relocation map at the end of this spec; that appendix is the authoritative, placeholder-free map the planner consumes.

A sample contract file — design/contracts/0005-float-semantics.md (content moved verbatim from DESIGN.md:2700–2838, header re-levelled to file root, all decision-record/why-prose stripped to the journal):

# Float semantics

Float is the IEEE-754 double-precision primitive. Float has **no
`Eq` and no `Ord` instance by design**: IEEE-754 ordering is partial
(NaN is unordered), so a total `Eq`/`Ord` would be a lie about the
type. … [present-tense contract prose only] …

`float_to_str` is type-installed; codegen is reserved and not yet
shipped.

Ratified by: `crates/ail/tests/eq_float_noinstance.rs`.

The anti-regrowth guard — crates/ailang-core/tests/design_index_pin.rs (the concrete must-fail artifact for an infra milestone — its correct behaviour is to go RED the instant the structure re-conflates):

//! Structural pin for the design/ ledger. Sibling of
//! docs_honesty_pin.rs. Fails RED the instant the design/ split
//! re-conflates contract + rationale + narrative, an INDEX row
//! dangles, a contract loses its ratifying test, or docs/DESIGN.md
//! is resurrected.

// helper: workspace root = CARGO_MANIFEST_DIR/../.. ; norm() =
// split_whitespace().join(" ") — line-wrap-independent, identical
// shape to docs_honesty_pin.rs.

#[test]
fn design_md_is_gone() {
    // clause 4 — clean-cut pin
    assert!(!root().join("docs/DESIGN.md").exists(),
        "docs/DESIGN.md was resurrected; the split is clean-cut");
}

#[test]
fn every_index_link_resolves() {
    // clause 1 — parse design/INDEX.md tables; for each row, the
    // `link` target (design/ file OR source path; the dual-link
    // row's first segment before " + ") exists on disk.
}

#[test]
fn every_contract_names_a_resolvable_ratifying_test() {
    // clause 2 — every kind=contract row's ratifying-test token
    // resolves to a real file under crates/**/tests, crates/**/src
    // (in-source `#[cfg(test)] mod tests` are first-class ratifiers
    // in this project — see Boss adjudication OQ1/OQ2), bench/, or
    // skills/**/SKILL.md.
}

#[test]
fn contracts_carry_no_decision_record_prose() {
    // clause 3 — the conflation tripwire. For each
    // design/contracts/*.md, norm() the body and assert it contains
    // none of: "we rejected", "an earlier draft", "Why not other",
    // "was retired in iter", "rollback plan", "previously all".
}

2. The one real code change — compiler diagnostic, before → after

This is the clause-1 / clause-3 evidence. The pre-existing fixture the diagnostic E2E runs (unchanged), the program an LLM author writes that must fail to typecheck:

; examples/eq_float_noinstance.ail
(module eq_float_noinstance
  (fn main
    (type (fn-type (params) (ret (con Unit)) (effects IO)))
    (params)
    (body (app print (if (app eq 1.0 2.0) 1 0)))))

crates/ailang-check/src/lib.rs:873 (the Float branch):

- orderability per IEEE-754); see DESIGN.md §\"Float semantics\".",
+ orderability per IEEE-754); see design/contracts/0005-float-semantics.md.",

crates/ailang-check/src/lib.rs:888 (the Show branch):

- the prelude; see DESIGN.md §\"Prelude (built-in) \
- classes\". User types declare their own \
+ the prelude; see design/contracts/0013-typeclasses.md. \
+ User types declare their own \

crates/ail/tests/eq_float_noinstance.rs:40 — the assertion currently passes on "Float semantics" || "DESIGN"; both substrings vanish, so it updates in lockstep:

-   no_inst.message.contains("Float semantics") || no_inst.message.contains("DESIGN"),
-   "expected NoInstance message to cross-reference DESIGN.md §Float semantics, got: {:?}",
+   no_inst.message.contains("design/contracts/0005-float-semantics.md"),
+   "expected NoInstance message to cross-reference the float-semantics contract, got: {:?}",

crates/ail/tests/show_no_instance_e2e.rs:48 — analogous: the asserted substring becomes "design/contracts/0013-typeclasses.md".

3. The four executable retargets (before → after)

bench/architect_sweeps.sh:22-28:

- DESIGN="docs/DESIGN.md"
- [[ ! -f "$DESIGN" ]] && { echo "could not find $DESIGN"; exit 2; }
+ INDEX="design/INDEX.md"
+ [[ ! -f "$INDEX" ]] && { echo "could not find $INDEX"; exit 2; }

Each run_sweep greps the design/contracts/*.md + design/models/*.md set instead of the single file; exit-code contract preserved (0 clean / 1 anchor-found / 2 spine-not-found). Sweep 5 (honesty) scans all design/ prose; the verbatim regexes are unchanged.

crates/ailang-core/tests/design_schema_drift.rs:22:

- const DESIGN_MD: &str = include_str!("../../../docs/DESIGN.md");
+ const DATA_MODEL: &str = include_str!("../../../design/contracts/0002-data-model.md");

The data_model_section() slicer (## Data model … \n## Pipeline) and data_model_section_is_bounded are removed: the whole file is now the data-model contract, so the section-extraction premise vanishes — a simplification the split enables. Every section.contains(anchor) assertion runs against the whole DATA_MODEL string.

crates/ailang-core/tests/docs_honesty_pin.rs and effect_doc_honesty_pin.rs: the read("docs/DESIGN.md") calls split into reads of the specific design/ files where each pinned sentence now lives. The present/absent pin strings are unchanged except the two honesty-rule anchors at docs_honesty_pin.rs:70,72 ("the honesty rule it holds itself to" / "whether the document asserts something exists, works, or changed that does not"), which are updated to the rewritten contracts/0007-honesty-rule.md wording in lockstep with that file. The Decision-6 :242 audit-trail sentence is pinned by no test (verified) and is retired to the decision-record journal, not retargeted — there is nothing to repoint, by design.

4. Agent reading-list rewrite (representative before → after)

skills/audit/agents/ailang-architect.md:30:

- 2. `docs/DESIGN.md` — the canonical specification. Drift is measured against
+ 2. `design/INDEX.md` — the typed contract ledger and sole spine.
+    Walk the Contracts table; drift is measured against each row's
+    `link` target (a `design/contracts/` file or the source `//!`
+    it names). `design/models/` is context, not a drift surface.

The other ~11 reading-list bullets (grounding-check, fieldtester, debugger, bencher, tester, implementer, implement-orchestrator, spec-reviewer, quality-reviewer, plan-recon, docwriter) are rewritten to their role: grounding-check and architect read contracts/; fieldtester reads INDEX.md + models/ (no-edit limit preserved, repointed); bencher reads models/0004-rc-uniqueness.md (Decision-9/Boehm narrative); the rest point at design/INDEX.md as the spine.

Components

The per-contract disposition (fixes the polymorphic link, planner does not re-decide it):

Contract	Disposition	Rationale
feature-acceptance	prose file	gate text, prose-authoritative
authoring-surface	prose file	binding Form-A constraints, prose-stated
roundtrip-invariant	prose file	the invariant statement is prose
memory-model	prose file	Decision 10 ### Language-design constraints (binding) + ### Schema additions + ### Codegen contract; binding, prose-stated
data-model	prose file	the wire schema an author must produce is a promise (prose-authoritative); design_schema_drift.rs include_str!s it
float-semantics	prose file	author-facing; the diagnostic points here
typeclasses	prose file	coherence/dispatch rules + prelude classes; the Show diagnostic points here
tail-calls	prose file	the propagation rule is prose-stated, check-ratified
frozen-value-layout	prose file + source link	one-way human commitment AND codegen contract — deliberate dual-link
honesty-rule	prose file	rewritten; resolves the internal contradiction
embedding-abi	prose file	the M3-frozen ABI contract, author + host facing
verification	prose file	the cross-cycle verification contract
mangling	source link only	codegen behaviour; prose would duplicate code; eq_ord_e2e.rs ratifies
env-construction	source link only	codegen behaviour; duplicate_ctor_pin.rs ratifies

Models (always prose whitepapers): rc-uniqueness (Decision 10 narrative + Decision 9 Boehm rationale), typeclasses (resolution / monomorphisation narrative), effects (Decision 3 narrative), authoring-surface (notation rationale, candidate notations, empirical addendum), pipeline (Pipeline + CLI).

Decision-record archive — docs/journals/2026-05-19-design-decision-records.md: the ### Why not other memory models, ### What this Decision deliberately does not do (×N), ### Empirical addendum, ### First choice and rollback plan, and every "considered and rejected" passage, moved whole at ### granularity. The journals INDEX.md gets the one-line pointer per project convention.

Data flow

• Architect, milestone close: reads design/INDEX.md → walks the Contracts table → for each row reads the link target → measures drift against it. architect_sweeps.sh scans the design/ prose set; exit codes unchanged.
• grounding-check, per spec: reads design/INDEX.md → the contract rows the spec's assumptions touch → composes.
• LLM author, NoInstance: the diagnostic names design/contracts/0005-float-semantics.md (or …/typeclasses.md) → opens exactly that contract → self-corrects.
• Future brainstorm tempted to re-propose region inference: the "why rejected" prose is in docs/journals/2026-05-19-design-decision-records.md, reachable from the journals INDEX — not in any contract file.
• design_index_pin.rs, every cargo test: parses INDEX.md → asserts all links resolve, all contracts name a resolvable ratifying-test, no contract carries decision-record prose, docs/DESIGN.md is absent.

Error handling

All failure modes fail closed:

• INDEX row → missing target ⇒ design_index_pin.rs every_index_link_resolves RED.
• A contracts/ file regrows "we rejected"/"Why not other"/… ⇒ contracts_carry_no_decision_record_prose RED (the conflation tripwire — the milestone's reason to exist, enforced in code).
• docs/DESIGN.md resurrected ⇒ design_md_is_gone RED.
• A contract names a ratifying-test that does not resolve ⇒ every_contract_names_a_resolvable_ratifying_test RED.
• architect_sweeps.sh cannot find design/INDEX.md ⇒ exit 2 (preserved "infra missing" semantics, repointed).
• Content move lands without the include_str! retarget ⇒ cargo build fails. This is the build-atomic fail-closed property; the planner sequences the single landing build-green.
• Recon-undercount countermeasure (acceptance gate). The milestone's acceptance includes a tree-wide grep -rIn 'DESIGN\.md' over all file types (bench/ skills/ crates/ runtime/ ail-embed/ examples/ docs/ CLAUDE.md) returning only the append-only history docs (docs/journals/, docs/specs/, docs/plans/, docs/roadmap.md, docs/WhatsNew.md, docs/journal-archive.md) — zero live references in code, scripts, agent files, or comments. Recon proved the carrier's file-type list (*.md *.rs *.py *.sh *.toml) silently misses .c/.h/.ail; the gate is unfiltered (grep -rIn, no --include) and any claimed-absent path is ls-verified. This is the fourth-recurrence recon-undercount class made an explicit gate.

Testing strategy

• RED-first spine: design_index_pin.rs (the 4 clauses above) is written first; RED until design/ exists, is consistent, and docs/DESIGN.md is gone; GREEN when the split is complete and faithful.
• Retarget, not rewrite: design_schema_drift.rs, docs_honesty_pin.rs, effect_doc_honesty_pin.rs keep their property (the schema/honesty invariant stays documented); only the path/anchor moves. design_schema_drift.rs additionally simplifies (the ## Data model/## Pipeline slicer is removed — the file boundary now bounds the section).
• Lockstep E2Es: eq_float_noinstance.rs, show_no_instance_e2e.rs updated with the diagnostic strings; they continue to assert the author-affordance (a correct, resolvable pointer).
• Whole-suite GREEN: cargo test workspace-wide must be green post-split (the include_str! retarget + all path moves consistent). Build-atomicity makes a half-move a compile failure, not a silent-wrong state.
• Bench unaffected: recon confirmed the bench harness (bench/check.py, compile_check.py, cross_lang.py, run.sh) has zero DESIGN.md references; only architect_sweeps.sh (audit-time, not bench-time) opens it. Generated IR is byte-identical (no codegen change — the diagnostic string is not in the IR). Any bench firing is the tracked P2 noise and is causally exonerable by byte-identical-IR.
• Audit, mandatory at milestone close: architect drift review against the new design/ (the architect's own reading list is one of the rewritten artifacts — the audit validates the structure it now reads); bencher causal exoneration as usual.
• No fieldtest: zero authoring-surface change. The diagnostic-string change is a doc-pointer, not a language or authoring-surface change. (Recorded explicitly so the post-audit step is not skipped by omission but by reasoned exclusion.)

Acceptance criteria

1. docs/DESIGN.md does not exist; design/INDEX.md, design/contracts/*.md, design/models/*.md, and docs/journals/2026-05-19-design-decision-records.md exist and are internally consistent.
2. Every ### subsection of the former DESIGN.md is accounted for in exactly one destination (contract / model / decision-record); no content is silently dropped.
3. design/INDEX.md Contracts table: every link resolves, every row names a resolvable ratifying-test. Models table: every link resolves.
4. crates/ailang-core/tests/design_index_pin.rs is GREEN with all four clauses; it was demonstrably RED before the split landed.
5. design_schema_drift.rs, docs_honesty_pin.rs, effect_doc_honesty_pin.rs are GREEN against the new files; their protected properties are unchanged.
6. The compiler emits design/contracts/0005-float-semantics.md / design/contracts/0013-typeclasses.md in the two NoInstance diagnostics; eq_float_noinstance.rs and show_no_instance_e2e.rs assert the new pointer and are GREEN.
7. cargo test workspace-wide is GREEN; cargo build is clean.
8. Tree-wide grep -rIn 'DESIGN\.md' (no --include) returns matches only in the append-only history docs; zero live references in code, scripts, agent files, SKILL bodies, CLAUDE.md, skills/README.md, or comments.
9. bench/architect_sweeps.sh runs against design/, exits 0 on the clean tree, and its exit-2 path triggers on a missing design/INDEX.md.
10. The ~12 agent reading lists, the 5 SKILL.md bodies, CLAUDE.md, and skills/README.md name the new spine; no agent contract still instructs reading a file that does not exist.
11. The milestone landed in a build-atomic shape (no commit leaves the workspace non-compiling).
12. Every ##/### of the former DESIGN.md maps to exactly one destination in the Appendix table; the three ledger additions (qualified-xref, str-abi, scope-boundaries) have INDEX rows and resolvable ratifiers; the crates/ailang-codegen/src/lib.rs:103 "Iter 13b" dangling cite is rewritten to drop the unresolvable reference (keeping it would itself violate the honesty rule).

Appendix — Boss-adjudicated relocation map (authoritative, placeholder-free)

This appendix supersedes any ambiguity in §Components. It is the map the planner consumes. Every ##/### of DESIGN.md (3020 lines; no ## Decision 7 — numbering gap, not drift) has exactly one destination. D = docs/journals/2026-05-19-design-decision-records.md (decision-record archive). IX = design/INDEX.md preamble.

Bucketing principle. Contract = prescriptive + obeyed/checked by an author, the architect, or a green test (binding, schema, enforcement, honesty-pinned, present-tense scope claim). Model = explanatory narrative; reading it is optional for correctness; no test pins it. Decision-record = why-X-chosen / why-Y-rejected / "deliberately does not do" / rollback / empirical addendum / how-the-doc-reached-its-wording.

## / ###	Lines	Destination
## Goal	6–18	IX preamble
## Project ecosystem (intro)	19–55	IX preamble
### What this document is — honesty rule	56–82	contracts/0007-honesty-rule.md (rewritten; pins docs_honesty_pin.rs:70,72)
## Project language: English	83–92	IX preamble
## Feature-acceptance criterion	93–164	contracts/0004-feature-acceptance.md
## Decision 1: source = data	165–176	D
## Decision 2: content-addressed	177–189	D
## Decision 3: pure core + effects	190–204	models/0002-effects.md (pins effect_doc_honesty_pin.rs present-anchors — pin reads this file)
## Decision 4: HM + refinements	205–213	D
## Decision 5: emit LLVM IR as text	214–229	D
## Decision 6 intro	230–240	contracts/0001-authoring-surface.md
(Decision 6 :241–243 audit-trail sentence)	241–243	D (retired, no successor pin — §Architecture-4)
### Why this is opening up	245–267	D
### Architectural pin: data structure is SoT	268–297	contracts/0001-authoring-surface.md
### Constraints (hard, in priority order)	298–331	contracts/0001-authoring-surface.md
### Candidate notations	332–471	models/0001-authoring-surface.md
### First choice and rollback plan	472–486	D
### Implementation outline	487–519	D
### What this Decision deliberately does not do	520–536	D
### Form refinements during implementation	537–589	D
### Form (B) — human prose projection	590–674	models/0001-authoring-surface.md (the Form-B placeholder present-anchor in docs_honesty_pin.rs re-points here)
### Empirical addendum	675–730	D
## Decision 8: explicit verified tail calls	731–787	contracts/0012-tail-calls.md
## Decision 9 intro	788–852	models/0004-rc-uniqueness.md
### Per-fn arena via stack alloca	853–913	models/0004-rc-uniqueness.md
## Decision 10 intro	914–977	models/0004-rc-uniqueness.md
### Why not other memory models	978–1014	D
### The LLM-aware sharpening	1015–1122	models/0004-rc-uniqueness.md
### Language-design constraints (binding)	1123–1150	contracts/0008-memory-model.md
### Schema additions	1151–1312	contracts/0008-memory-model.md
### Advisory diagnostics	1313–1351	contracts/0008-memory-model.md
### Why advisory + suppress instead of inference	1352–1377	D
### Inference algorithm	1378–1393	models/0004-rc-uniqueness.md
### Codegen contract	1394–1412	contracts/0008-memory-model.md
### Mode metadata is load-bearing for codegen	1413–1509	contracts/0008-memory-model.md
### Adjacent extensions for mutability (out of scope)	1510–1519	D
### What this Decision deliberately does not do	1520–1535	D
## Decision 11 intro	1536–1577	models/0005-typeclasses.md
### Form-A schema (JSON authoring surface)	1578–1639	contracts/0013-typeclasses.md
### Resolution and monomorphisation	1640–1752	models/0005-typeclasses.md
### Cross-module references in synthesised bodies	1753–1823	contracts/0013-typeclasses.md (pins codegen_import_map_fallback_pin.rs:2, polyfn_dot_qualified_branch_pin.rs:2)
### Defaults and superclasses	1824–1855	contracts/0013-typeclasses.md
### Diagnostic categories	1856–1917	contracts/0013-typeclasses.md
### Method dispatch	1918–1964	contracts/0013-typeclasses.md
### What the typeclass design explicitly does NOT support	1965–2000	D
### Prelude (built-in) classes	2001–2042	contracts/0013-typeclasses.md (pins show_no_instance_e2e.rs:47; Show diagnostic target)
### Heap-Str primitives	2043–2088	contracts/0011-str-abi.md (ledger addition — see below)
### What this decision does NOT commit to	2089–2112	D
## Roundtrip Invariant (+ 3 ###s 2152–2208)	2113–2208	contracts/0009-roundtrip-invariant.md (whole block kept together — pins round_trip.rs:10,72)
## Mangling scheme	2209–2218	source-link only (no prose file): behaviour → dropped (code is SoT); any "why" sentence → D
## Convention: qualified cross-module references	2219–2236	source-link only qualified-xref (ledger addition): behaviour → dropped; rationale → D
## Env construction	2237–2265	source-link only (no prose file): behaviour → dropped (code is SoT); any "why" sentence → D
## Embedding ABI intro	2266–2333	contracts/0003-embedding-abi.md (pins docs_honesty_pin.rs:135)
### Frozen value layout (M3 — one-way commitment)	2334–2376	contracts/0006-frozen-value-layout.md + source-link runtime/rc.c §layout (dual; pins embed_record_layout_pin.rs:1)
## Data model (+ 4 ###s)	2377–2615	contracts/0002-data-model.md (whole; design_schema_drift.rs include_str!s it)
## Pipeline	2616–2662	models/0003-pipeline.md
## CLI	2663–2686	models/0003-pipeline.md
## Verification and correctness (across cycles)	2687–2699	contracts/0014-verification.md
## Float semantics	2700–2838	contracts/0005-float-semantics.md (the inline **Str ABI.** para at 2802 is moved to contracts/0011-str-abi.md — the one sentence-level exception, justified below)
## What is not (yet) supported	2839–3020	contracts/0010-scope-boundaries.md (ledger addition — present-tense, honesty-pinned by effect_doc_honesty_pin.rs:28)

Ledger additions — rationale (the brainstorm's 12-list under-counted)

Plan-recon's exhaustive live-xref sweep proved three genuine, distinct, currently-referenced contracts the 12-row first pass missed. Forcing them into ill-fitting existing files would re-create the conflation this milestone exists to end; the ledger's purpose is per-contract addressability, so a genuine distinct contract earns a row.

• qualified-xref (13th, source-link only). ## Convention: qualified cross-module references is code-SoT per §Architecture commitment 1 ("qualified-cross-module-ref resolution"). No prose file; INDEX row links the resolution //!; ratifier codegen_import_map_fallback_pin.rs. crates/ail/src/main.rs:1393 retargets to this row.
• str-abi (14th, prose + source-link). ### Heap-Str primitives (2043–2088) + the inline **Str ABI.** para (2802) are one runtime-ABI contract, SoT runtime/str.c. Three live xrefs name §"Str ABI"/§"Heap-Str primitives" (runtime/str.c:172,198, crates/ail/tests/e2e.rs:2843) — they would dangle with no destination. The 2802 para is the single sanctioned sentence-level move (it is one inline bold-paragraph, not a ###; leaving it in float-semantics.md would mis-file a Str contract under Float). Recorded as the explicit, bounded exception to §Architecture commitment 2.
• scope-boundaries (15th, prose). ## What is not (yet) supported is present-tense scope assertion, honesty-pinned by effect_doc_honesty_pin.rs:28 (absent-string "the built-in IO and Diverge ops"). A present-tense "what the language does not do, now" claim is a contract (a checked promise), not a decision-record; the pin already reads it, so its ratifier is effect_doc_honesty_pin.rs.

Net ledger: 15 contracts (12 spec + 3 additions), 5 models, one decision-record journal. The design_index_pin.rs clause-2 resolution set is widened to accept crates/**/src/*.rs so the in-source memory-model (uniqueness.rs) and tail-calls (lib.rs tail_call_in_non_tail_position_is_rejected) ratifiers resolve honestly rather than being mapped to a wrong tests/-level file.

OQ7 — the dangling "Iter 13b" cite

crates/ailang-codegen/src/lib.rs:103 cites "Iter 13b notes in DESIGN.md" — that prose was relocated out of DESIGN.md long ago; no forward target exists in the tree. Per the honesty rule a reference to non-existent content is itself a violation. The comment is rewritten to drop the cite (state the behaviour directly; no design/ or journal pointer, because the referenced notes no longer exist anywhere — inventing a pointer would be fiction). This is the one reference in bucket (e) that is deleted, not retargeted.