Files

T

Brummel 9d2e752f07 iter kernel-extension-mechanics.tidy: architect drift items — present-state + plugin-migration aftermath

Audit Step 3 fix path. Architect drift review at milestone close
surfaced 8 items (3 high, 4 medium, 1 low). Resolved 7 inline as
mechanical text rewrites + 2 source-rustdoc cleanups; the 1 low
(cycle-avoidance pattern documentation in design ledger) is
deferred — architect flagged it "Note, do not push" because the
pattern is implementation mechanism, not language semantics,
and is already documented in the load-bearing place
(`crates/ailang-kernel-stub/src/lib.rs //!`).

CLAUDE.md (2 sites):
  - Lead paragraph: "this file carries [...] in-tree skill system"
    → reframe to "this file carries [...] orchestrator discipline
    (the skill system itself lives in the ~/dev/skills/ plugin
    and is wired in via .claude/dev-cycle-profile.yml)".
  - Code-layout table: new row for `crates/ailang-kernel-stub/`
    documenting the zero-dep leaf design, the parse-hop location
    in `ailang-surface`, and the planned retirement at raw-buf
    landing.

design/INDEX.md (2 sites):
  - Project-ecosystem "Skills" bullet: in-tree `skills/` path +
    `skills/README.md` reference → `~/dev/skills/` plugin +
    in-tree per-project profile. Also added `docwriter` and
    `boss` to the enumerated skill list (8 in total) for
    completeness.
  - kernel-extensions row 111: added stub-retirement plan to the
    annotation so the spine names the future state, not just the
    in-tree reader of `lib.rs //!`.

design/models/0007-kernel-extensions.md (3 sites):
  - § "Migration policy" subsection: 4 bullets transitioned
    forward → present-state per honesty-rule. References to
    `loader.rs:98-108` / `workspace.rs:308-311, 467, 2655` as
    if hardcoded paths still existed → described as past state
    that has been replaced by the generic flag-filter. Codegen-
    intercept-migration bullet kept forward-looking because the
    `try_emit_primitive_instance_body` migration is *actually*
    still pending (deferred to Series milestone per spec
    § Out-of-scope).
  - § "Feature-acceptance argument": "the bounded push-only
    mutation surface — gated by the `Series` effect" — internal
    contradiction with three earlier statements that "Series
    carries no separate algebraic effect; mutation is mode-
    tracked, not effect-tracked". Re-framed to "gated by
    uniqueness mode-tracking on the owned `Series` value (not by
    an algebraic effect; see §"Coexistence" below)".
  - § "Coexistence" "Algebraic effects" bullet: "Reused
    unchanged. The `Series` effect is a new name" — same
    contradiction. Re-framed to "Not extended by Series.
    Mutation discipline lives in the uniqueness/mode system; the
    algebraic-effects set is unchanged".

Source rustdoc (2 sites):
  - `crates/ailang-core/tests/design_index_pin.rs:117` comment
    "skills/**/SKILL.md" → "any in-tree project-discipline
    document (e.g. CLAUDE.md)" — the allowlist comment now
    matches what the test actually does (no allowlist enforced
    in code; any existing path passes).
  - `crates/ailang-core/tests/design_schema_drift.rs:419`
    rustdoc: "RED until `skills/implement` mini-mode adds it"
    → "RED until the `implement` skill (mini-mode dispatch)
    adds it" — same skill, post-plugin-migration framing.

Architect items not addressed in this tidy:
  - 0007 § "The plugin contract (consolidated)" forward-intent
    reference to `try_emit_primitive_instance_body` migration —
    architect flagged as edge-case-acceptable per the explicit
    STATUS carve-out (the migration IS still pending). No
    change.
  - Cycle-avoidance pattern documentation (low): deferred per
    architect recommendation.

Tests green (664/0); workspace_pin module-count assertion picked
up from a844de3 carries through.

2026-05-28 19:04:43 +02:00

7.6 KiB

Raw Blame History

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.

Project framing

Goal

AILang is a programming language for LLM authors. It compiles to LLVM IR. Performance: native, no GC for the MVP.

Optimised for:

Machine readability over human ergonomics. The source is structured.
Local reasoning. Every definition carries its full type and effects.
Provability. Pure core language, explicit effects, optional refinements.
Robustness against hallucinations. Symbols are hashable; tools can verify existence without spending context window.

Project ecosystem

AILang is not just a language but an ecosystem. The language on its own is only valuable when its surroundings make it usable, checkable, and extensible for its target user (LLM authors). The repo therefore contains several equally important components — none of them optional, all of them evolving in lockstep with the language:

Language core (crates/ailang-core, crates/ailang-check, crates/ailang-codegen): AST, type system, codegen.
Surface forms (crates/ailang-surface, crates/ailang-prose): the LLM-facing renderings of a module. ailang-surface is the lossless Form-A printer/parser — the canonical authoring surface, with a round-trip property parse ∘ print = id gating every release. ailang-prose is the lossy Form-B projection — human-readable prose for review and edit, with no parser; re-integration goes through the LLM-mediator round-trip documented in docs/PROSE_ROUNDTRIP.md.
CLI (crates/ail): toolchain for tooling consumers — manifest, describe, deps, check, build, parse, render, prose, merge-prose, etc., preferably with --json for machine consumption.
Examples (examples/): canonical .ail.json programs. They are specification anchors, not demos — the E2E suite hangs off them.
Skills (~/dev/skills/ plugin, wired in via .claude/dev-cycle-profile.yml): specialised disciplines (brainstorm, planner, implement, audit, debug, fieldtest, docwriter, boss) plus the agent rosters they dispatch. They form the project's development methodology; the plugin is versioned separately, the per-project profile is in-tree.
Design ledger (design/): design/INDEX.md (this file — the sole addressable spine for canonical state), design/contracts/ (test-linked invariants), design/models/ (onboarding whitepapers).
Docs (docs/): specs/ (per-milestone design specs), plans/ (per-iteration implementation plans). Project history lives in git log; the forward queue lives in the Gitea issue backlog (http://192.168.178.103:3000/Brummel/AILang/issues).
Tests: unit tests per crate plus E2E in crates/ail/tests/e2e.rs. Every new compiler path needs a test, otherwise the feature does not count as done.

Project language: English

All in-tree content is written in English: source code (identifiers, comments, string literals, CLI help), design documents, agent prompts, READMEs, commit messages, examples, and CLAUDE.md. The live conversation between user and me stays German for ergonomic reasons; everything that lands in git is English. This keeps diffs and tooling output uniform and matches the audience for AILang (LLM authors), for whom English is the default.

Contracts

id	consumer / lifetime	ratifying-test	link
feature-acceptance	brainstorm-gate / stable	CLAUDE.md	design/contracts/0004-feature-acceptance.md
authoring-surface	LLM author / stable	crates/ailang-surface/tests/round_trip.rs	design/contracts/0001-authoring-surface.md
roundtrip-invariant	every release / stable	crates/ailang-surface/tests/round_trip.rs	design/contracts/0009-roundtrip-invariant.md
language-constraints	LLM author / stable	crates/ailang-check/src/uniqueness.rs (in-source mod tests)	design/contracts/0015-language-constraints.md
memory-model	LLM author / stable	crates/ailang-check/src/uniqueness.rs (in-source mod tests)	design/contracts/0008-memory-model.md
data-model	LLM author / stable	crates/ailang-core/tests/design_schema_drift.rs	design/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	design/contracts/0006-frozen-value-layout.md + runtime/rc.c §layout
float-semantics	LLM author / stable	crates/ail/tests/eq_float_noinstance.rs	design/contracts/0005-float-semantics.md
typeclasses	LLM author / stable	crates/ail/tests/show_no_instance_e2e.rs	design/contracts/0013-typeclasses.md
method-dispatch	LLM author / stable	crates/ail/tests/show_no_instance_e2e.rs	design/contracts/0016-method-dispatch.md
prelude-classes	LLM author / stable	crates/ail/tests/show_no_instance_e2e.rs	design/contracts/0017-prelude-classes.md
str-abi	runtime ABI / stable	crates/ail/tests/e2e.rs (Str path)	design/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)	design/contracts/0012-tail-calls.md
honesty-rule	architect+grounding / stable	crates/ailang-core/tests/docs_honesty_pin.rs	design/contracts/0007-honesty-rule.md
embedding-abi	embedding host / stable	crates/ailang-codegen/tests/embed_record_layout_pin.rs	design/contracts/0003-embedding-abi.md
scope-boundaries	architect+author / stable	crates/ailang-core/tests/effect_doc_honesty_pin.rs	design/contracts/0010-scope-boundaries.md
verification	architect / stable	bench/architect_sweeps.sh	design/contracts/0014-verification.md

Models

id	consumer / lifetime	link
rc-uniqueness	onboarding / evolves	design/models/0004-rc-uniqueness.md
typeclasses	onboarding / evolves	design/models/0005-typeclasses.md
effects	onboarding / evolves	design/models/0002-effects.md
authoring-surface	onboarding / evolves	design/models/0001-authoring-surface.md
prose-projection	onboarding / evolves	design/models/0006-prose-projection.md
pipeline	onboarding / evolves	design/models/0003-pipeline.md
kernel-extensions	onboarding / evolves (mechanisms milestone closed 2026-05-28; ratified end-to-end by the `ailang-kernel-stub` fixture, planned for retirement when raw-buf lands a real second consumer; raw-buf and series milestones pending)	design/models/0007-kernel-extensions.md

7.6 KiB Raw Blame History