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`:

```markdown
# 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):

```markdown
# 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):

```rust
//! 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:

```scheme
; 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:

```rust
-   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`:

```sh
- 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`:

```rust
- 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*.