From 3e087d759aaf160663baf20809750ac8f4524770 Mon Sep 17 00:00:00 2001 From: Brummel Date: Wed, 20 May 2026 00:46:37 +0200 Subject: [PATCH] =?UTF-8?q?design/=20ledger:=20prose-bridges=20for=20in-fe?= =?UTF-8?q?nce=20=C2=A7-refs=20in=20data-model.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Five §"..." cross-refs survived the main sweep because they live inside jsonc Schema-comments — clause-5 fence-skip would treat any [label](path) there as literal text, not as a navigable link. Instead of touching the schema-comment style (it is self-documenting where it sits, against the field it qualifies), this commit adds prose paragraphs just outside the fence that turn the same cross-references into real links: - Before the Def jsonc block: pointer to memory-model.md (canonical-form rule for cross-module class/type names) and embedding-abi.md (exported fn surface). - Before the Type jsonc block: pointer to memory-model.md for Type::Con.name scoping and Type::Fn parameter-mode metadata. Also re-phrases an intra-file §"Str ABI" self-reference in str-abi.md to "the Str ABI table below" — file-only granularity makes a self-link sense-less; the reader wants intra-file direction, which prose carries fine without a link. Tests: design_index_pin (5/5) + docs_honesty_pin (5/5) stay green. --- design/contracts/data-model.md | 13 ++++++++++++- design/contracts/str-abi.md | 4 ++-- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/design/contracts/data-model.md b/design/contracts/data-model.md index 8617aaf..c15fdae 100644 --- a/design/contracts/data-model.md +++ b/design/contracts/data-model.md @@ -25,7 +25,13 @@ contract is what makes growing the schema cheap. ### Def `kind ∈ { "fn", "const", "type", "class", "instance" }`. All five -are real surface forms. +are real surface forms. Class and type cross-module references +(canonical-form rule, qualified `.` / +`.`) follow the scoping rule in +[memory model](memory-model.md); the `class`/`instance` schema +narrative — defaults, superclasses, diagnostics — lives in +[typeclasses](typeclasses.md). Exported `fn` defs interact with +[embedding ABI](embedding-abi.md). ```jsonc // fn (the unit that gets a content hash) @@ -201,6 +207,11 @@ Patterns are linear: each pattern variable may appear at most once. ### Type +The `Type::Con.name` canonical-form rule (bare for same-module / +primitives, qualified `.` for cross-module) lives +in [memory model](memory-model.md); `Type::Fn`'s parameter-mode +metadata is defined and gated there as well. + ```jsonc // Type-constructor application. `args` omitted when empty // (hash-stable when omitted, for non-parameterised cases like Int, Bool, ...). diff --git a/design/contracts/str-abi.md b/design/contracts/str-abi.md index bedd5a7..dc8daeb 100644 --- a/design/contracts/str-abi.md +++ b/design/contracts/str-abi.md @@ -5,8 +5,8 @@ The runtime ships a small family of operations that produce or transform heap-allocated `Str` values uniformly across static-Str and heap-Str inputs (the consumer ABI is identical between -realisations — see §"Str ABI"). All take their input(s) by `borrow` -and return an owned `Str`. Each is registered as a builtin in +realisations — see the Str ABI table below). All take their +input(s) by `borrow` and return an owned `Str`. Each is registered as a builtin in `crates/ailang-check/src/builtins.rs`, lowered inline in `crates/ailang-codegen/src/lib.rs::lower_app` to a `call ptr @ailang_`, and backed by a `runtime/str.c` C helper.