iter prep.3-kernel-tier-modules (DONE 9/9): kernel-tier modules + param-in + stub crate — closes #33
Terminal iteration of the kernel-extension-mechanics milestone. Ships
the four language-level mechanisms named in the spec's § Goal:
Module.kernel + TypeDef.param-in schema, their Form-A surface,
flag-driven kernel-tier auto-injection, and generic param-in checker
enforcement with a new diagnostic.
Schema (Tasks 1+2). Module gains a `kernel: bool` field
(skip_serializing_if = is_false), TypeDef gains a
`param_in: BTreeMap<String, BTreeSet<String>>` field
(skip-if-empty, kebab-renamed to "param-in"). Both fields are
strictly additive — every pre-existing fixture's canonical-JSON hash
is bit-stable except `prelude.ail`, which intentionally gains
`(kernel)`. The struct-literal sweep covered ~104 Module sites and
~35 TypeDef sites across the workspace; the additive serde-default
covers JSON deserialise paths, only Rust struct literals broke.
Form-A surface (Tasks 3+4). `(kernel)` is a bare module-header
attribute; `(param-in (a Int Float) (b Str))` is one outer
TypeDef-body clause carrying one or more inner var-lists (OQ1
decision — mirrors `(ctors …)`, one parser arm, deterministic
BTreeMap iteration). Both round-trip Form-A → JSON → Form-A
bit-identical.
Workspace-load migration (Task 5). The hardcoded `&["prelude"]`
literal at loader.rs:108 became a `modules.values().filter(|m|
m.kernel)` derivation; `parse_prelude()` injection stays because
the prelude has no on-disk manifest in user workspaces. Prelude
now carries `(kernel)` in its source, so the new filter picks it
up automatically. Code-path migration only — observable behaviour
is identical (prelude_free_fns.rs stays green). prelude hash
re-pinned (af372f28c726f29f) with Honesty-Rule provenance comment.
WorkspaceLoadError::ReservedModuleName diagnostic prose
repurposed: any built-in kernel module name is reserved
(currently prelude + kernel_stub), not specifically prelude. CLI
mapping at main.rs updated in lockstep.
Stub crate (Task 6). New `crates/ailang-kernel-stub/` is a
zero-dependency leaf crate carrying only `pub const STUB_AIL:
&str` with the Form-A source of the kernel_stub module (one
parametric TypeDef with param-in, one ctor). The parse hop —
`parse_kernel_stub()` — lives in ailang-surface next to
parse_prelude, keeping the crate-dependency graph acyclic
(`ailang-surface → ailang-kernel-stub → ailang-core`, no
back-edge). The stub is injected unconditionally in all builds as
the ratifying fixture for the kernel-extension mechanism; future
base extensions may add more or retire the stub. Drift-pinned by
`kernel_stub_module_round_trips`.
Checker (Task 7). New `CheckError::ParamNotInRestrictedSet`
variant + code() + ctx() arms + enforcement in
`check_type_well_formed`'s Type::Con arm — generic, data-driven
from the TypeDef, mentions no specific extension type. Two
in-source tests pin both the rejection (`Str` outside `{Int,
Float}`) and the acceptance (`Int` inside) paths.
Workspace-load integration tests (Task 8). New
`workspace_kernel.rs` integration-test crate with three tests:
auto-import without explicit `(import …)` declaration, two
kernel-tier modules co-load, explicit-import-overrides-auto-
import precedence preserved. Loader is import-tree-only so the
auto-import tests use a bridge module that brings the kernel
module into the workspace via the import graph — docstring
captures the reachability nuance for future readers.
Doc-state transitions (Task 9). INDEX.md kernel-extensions row
annotation transitions from "design accepted 2026-05-28; impl in
progress" to "mechanisms milestone closed 2026-05-28; raw-buf and
series milestones pending". Whitepaper STATUS + auto-import +
param-in sections transitioned forward→present for shipped
mechanisms; forward-tense survives only in sections describing
the still-pending raw-buf/series milestones (per Honesty-Rule).
data-model contract gains anchor blocks for both new schema
fields.
Side-effect: every binary's IR snapshot now contains ~52 lines
for `drop_kernel_stub_StubT` because the stub is auto-injected
into every workspace load. Snapshots refreshed; e2e expects 4
modules per workspace (prelude + kernel_stub + entry + zero or
more user modules) instead of the previous 3.
Plan defects scrubbed in the implementation (folded back into
the planner template via the planner's self-review checklist
next time): Task 4 sample test src used fictional
`(ctors (MkT a))` list form (project grammar is per-`(ctor MkT
a)`); Task 6 original wiring would have created a cycle
ailang-surface → ailang-kernel-stub → ailang-surface (inverted —
stub crate is zero-dep, parse hop lives in surface); Task 7 in-
source tests referenced a fictional `check_type_in_module`
helper (used the existing Workspace + check_workspace
convention); Task 8 first integration test expected loader to
auto-load kernel modules from disk (loader is import-tree-only;
tests use a bridge module).
Concern-5 fix folded in pre-commit: workspace.rs ReservedModuleName
doc-prose initially said "in test/dev builds" for kernel_stub —
but stub is unconditionally injected in all builds. Doc copy
tightened to present-state per Honesty-Rule.
Stats: 0 spec-review-loops, 0 quality-review-loops, 2 sweep-script
retries on Task 2 (brace-depth bug on nested vec![Ctor{…}],
recovered via per-file checkout + rewritten anchor-on-existing-
field sweep), 1 e2e-snapshot refresh on Task 6.
This commit is contained in:
+1
-1
@@ -108,4 +108,4 @@ is the default.
|
||||
| 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 (design accepted 2026-05-28; impl in progress) | design/models/0007-kernel-extensions.md |
|
||||
| kernel-extensions | onboarding / evolves (mechanisms milestone closed 2026-05-28; raw-buf and series milestones pending) | design/models/0007-kernel-extensions.md |
|
||||
|
||||
@@ -17,6 +17,7 @@ contract is what makes growing the schema cheap.
|
||||
{
|
||||
"schema": "ailang/v0",
|
||||
"name": "<id>",
|
||||
"kernel": true, // optional; omitted when false (hash-stable when omitted). Kernel-tier modules are auto-imported by every consumer. See prep.3 of the kernel-extension-mechanics milestone.
|
||||
"imports": [{ "module": "<id>", "as": "<id>" }],
|
||||
"defs": [Def...]
|
||||
}
|
||||
@@ -62,7 +63,8 @@ narrative — defaults, superclasses, diagnostics — lives in
|
||||
...
|
||||
],
|
||||
"doc": "<optional string>",
|
||||
"drop-iterative": true // opt-in; omitted when false (hash-stable when omitted)
|
||||
"drop-iterative": true, // opt-in; omitted when false (hash-stable when omitted)
|
||||
"param-in": { "<var>": ["<TypeName>", ...] } // closed-set restriction per type variable; omitted when empty (hash-stable when omitted). See prep.3 of the kernel-extension-mechanics milestone.
|
||||
}
|
||||
|
||||
// class (typeclass declaration; narrative in contracts/0013-typeclasses.md)
|
||||
|
||||
@@ -1,14 +1,18 @@
|
||||
# Kernel extensions — plugin-style domain types whitepaper
|
||||
|
||||
**STATUS.** Design accepted 2026-05-28. Implementation in progress
|
||||
across two Gitea milestones: `kernel-extension-mechanics` (the
|
||||
language-level mechanisms) and `series` (the first concrete
|
||||
consumer). This whitepaper describes the design as a coherent
|
||||
whole; the per-milestone specs in `docs/specs/` carry the
|
||||
implementation-level detail. As each milestone closes, sections of
|
||||
this whitepaper transition from forward-looking design to
|
||||
present-state description, per the
|
||||
[honesty-rule](../contracts/0007-honesty-rule.md).
|
||||
**STATUS.** Mechanisms milestone closed 2026-05-28
|
||||
(`kernel-extension-mechanics`; iterations prep.1, prep.2, prep.3
|
||||
landed). The four language-level mechanisms — type-scoped
|
||||
namespacing, `Term::New`, kernel-tier modules + auto-import, and
|
||||
`param-in` — are shipped and ratified by the stub kernel crate
|
||||
(`crates/ailang-kernel-stub/`). The base-extension and library-
|
||||
extension milestones (`raw-buf`, `series`) are pending. This
|
||||
whitepaper describes the design as a coherent whole; the
|
||||
per-milestone specs in `docs/specs/` carry the implementation-
|
||||
level detail. Sections describing the now-shipped mechanisms read
|
||||
in present-state per the
|
||||
[honesty-rule](../contracts/0007-honesty-rule.md); sections about
|
||||
the still-pending milestones keep their forward-looking framing.
|
||||
|
||||
## The problem
|
||||
|
||||
@@ -211,25 +215,25 @@ type lives outside core, but at the call site it feels like a
|
||||
primitive. Bare `Series` in `(con Series (con Float))` without
|
||||
seeing `(import series)` somewhere is the ergonomic property.
|
||||
|
||||
**Single mechanism.** Auto-injection is *not* a new behaviour
|
||||
introduced by this design — it exists today, hardcoded to one
|
||||
module name. `crates/ailang-surface/src/loader.rs:98-108`
|
||||
unconditionally injects `parse_prelude()` and threads
|
||||
`&["prelude"]` into `workspace::build_workspace` as the
|
||||
implicit-imports list. Prelude's 12 free fns (see
|
||||
`examples/prelude.ail:85-148`) are already callable bare in
|
||||
every consumer module by virtue of this hardcoded path,
|
||||
ratified by `crates/ail/tests/prelude_free_fns.rs`.
|
||||
**Single mechanism.** Auto-injection is a single load-time hop,
|
||||
generalised from a hardcoded single-name path (prelude only,
|
||||
pre-prep.3) to a flag-driven multi-module mechanism (since
|
||||
prep.3 of `kernel-extension-mechanics`). The loader at
|
||||
`crates/ailang-surface/src/loader.rs::load_workspace` injects
|
||||
`parse_prelude()` and `parse_kernel_stub()` programmatically,
|
||||
then derives the implicit-imports list from
|
||||
`modules.values().filter(|m| m.kernel)`. Every module in the
|
||||
workspace's modules map that carries `kernel: true` enters the
|
||||
auto-import set; consumers see those modules' top-level types
|
||||
bare without an `(import …)` declaration.
|
||||
|
||||
The kernel-tier flag *generalises* this existing single-name
|
||||
auto-injection into a flag-driven multi-module mechanism. After
|
||||
the kernel-extensions design lands, prelude carries `kernel:
|
||||
true` and the implicit-imports list is derived from the set of
|
||||
all kernel-flagged modules. Consumer-observable behaviour for
|
||||
prelude is unchanged; the code path is rewritten from
|
||||
"hardcoded one name" to "flag-filtered all modules". Other
|
||||
kernel-tier modules (the stub, future Series, future Matrix)
|
||||
become auto-injected through the same path.
|
||||
Prelude carries `kernel: true` in `examples/prelude.ail`. Its 12
|
||||
free fns (see `examples/prelude.ail:85-148`) remain callable bare
|
||||
in every consumer module — ratified by
|
||||
`crates/ail/tests/prelude_free_fns.rs` across the code-path
|
||||
migration. The ratifying stub kernel module
|
||||
(`crates/ailang-kernel-stub/`) and any future kernel-tier
|
||||
consumers (Series, Matrix) auto-import through the same filter.
|
||||
|
||||
Class-method dispatch (a separate mechanism — see
|
||||
[method dispatch](../contracts/0016-method-dispatch.md)) is
|
||||
|
||||
Reference in New Issue
Block a user