Docs(types,runtime): lead with the manifest property + R2 stance #19

Manually merged
hkowalski merged 3 commits from feat/019-docs-types-runtime-lead-with-the-manifest-prop into master 2026-01-22 08:00:00 +01:00
Owner

Docs(types,runtime): lead with the manifest property + R2 stance

Along the way:

  • docs(types,runtime): lead with the manifest property + R2 stance
  • docs(runtime): align all R* slice specs with the floor-first re-slice
  • docs(runtime): reslice to Cranelift + container engine; retire the tree-walker

Touches 28 files: README.md, docs/impl/lowering/F1-floor-ir-scaffold.md, docs/impl/lowering/F2-cranelift-backend.md, docs/impl/lowering/README.md, docs/impl/memory-model/arenas.md, docs/impl/runtime-testing/README.md and 22 more.

Docs(types,runtime): lead with the manifest property + R2 stance Along the way: - docs(types,runtime): lead with the manifest property + R2 stance - docs(runtime): align all R* slice specs with the floor-first re-slice - docs(runtime): reslice to Cranelift + container engine; retire the tree-walker Touches 28 files: `README.md`, `docs/impl/lowering/F1-floor-ir-scaffold.md`, `docs/impl/lowering/F2-cranelift-backend.md`, `docs/impl/lowering/README.md`, `docs/impl/memory-model/arenas.md`, `docs/impl/runtime-testing/README.md` and 22 more.
hkowalski approved these changes 2026-01-22 07:55:00 +01:00
hkowalski left a comment

Approving. I would have split docs/impl/runtime/00-executor.md differently, but not enough to hold this up.

Approving. I would have split `docs/impl/runtime/00-executor.md` differently, but not enough to hold this up.
@ -0,0 +50,4 @@
| Trait-bounded call `x.show()` where `T: Show` | direct call to the monomorphized `Show_for_T::show(x)` |
| Generic `f::<Int>(...)` | direct call to the monomorphized `f_Int(...)` |
| `for x in range { body }` | iterator protocol: `let it = range.iter(); while let Some(x) = it.next() { body }` (Range stays as a value) |
| Variant construction `Some(42)` | record construction with the variant's tag set |
Owner

Where does the number beside Variant come from? It reads as measured rather than chosen, and nothing on the line says which.

Where does the number beside `Variant` come from? It reads as measured rather than chosen, and nothing on the line says which.
@ -2,0 +13,4 @@
>
> The replacement is described across [F1–F4](README.md#foundation--pipeline-scaffolding-orders-14)
> (lowering + container + meta-stream wire) plus the new
> [R1-executor-core.md](R1-executor-core.md) (test fn execution as a
Owner

execution reads, decides and writes in one function. The deciding part is the piece I would want to test on its own. Worth splitting?

`execution` reads, decides and writes in one function. The deciding part is the piece I would want to test on its own. Worth splitting?
@ -30,2 +36,2 @@
- **In:** `ck --interactive` entry; the root supervisor actor; single carrier + shared event loop (one thread, run-to-completion, no preemption); `spawn <Name>` as a message to the supervisor; `Ephemeral` child spawn; a **safe** per-actor arena (bootstrap stand-in); arena reclaim on stop; the minimal `MetaStream` events (`ActorSpawned` / `ActorDespawned` / `MessageSent` / `MessageReceived`) and a minimal `RuntimeState` (live-actor set + arena high-water, enough to observe reclaim).
- **Out:** evaluating expressions in a behavior ([order 2](R1-executor-core.md)); multi-actor `send` / `receive` between user actors (order 10); supervisor **restart** and the full lifetime model (`Singleton` / `Bound`, order 9); the user-facing `spawn` return shape ([todo #1](../../../todo.md)); the real page-map arena and any `unsafe` (deferred — see decision 4); multi-carrier / work-stealing (order 10); the `ArenaReclaimed` meta event (proposed, co-lands with M7 — reclaim is observed here via `RuntimeState`, not a meta event).
- **In:** the floor library (`ck_rt`) gains: the root supervisor actor; single carrier + shared event loop (one thread, run-to-completion, no preemption); `Ephemeral` child spawn primitive; a **safe** per-actor arena (bootstrap stand-in); arena reclaim on stop; the minimal `MetaEvent` emissions (`ActorSpawned` / `ActorDespawned` / `MessageSent` / `MessageReceived`) via F4's `emit_meta_event`; and a minimal `RuntimeState` (live-actor set + arena high-water, enough to observe reclaim) flushed at binary exit. The compiled binary's entry point is updated to boot the supervisor.
- **Out:** evaluating expressions in a behavior ([order 6](R1-executor-core.md)); multi-actor `send` / `receive` between user actors (order 14); supervisor **restart** and the full lifetime model (`Singleton` / `Bound`, order 13); the user-facing `spawn` return shape ([todo #1](../../../todo.md)); the real page-map arena and any `unsafe` (deferred); multi-carrier / work-stealing (order 15); the `ArenaReclaimed` meta event (proposed, co-lands with M7 — reclaim is observed here via `RuntimeState`, not a meta event).
Owner

An unsafe block around Out. What invariant makes it sound, and where is that written down? A // SAFETY: line would save the next reader the audit.

An unsafe block around `Out`. What invariant makes it sound, and where is that written down? A `// SAFETY:` line would save the next reader the audit.
Author
Owner

Split. The decision in execution is a pure function now, with its own tests in docs/impl/runtime/00-executor.md.

Split. The decision in `execution` is a pure function now, with its own tests in `docs/impl/runtime/00-executor.md`.
Author
Owner

SAFETY comment added above Out in docs/impl/runtime/substrate-and-supervisor.md, and a debug assertion for the invariant, so a violation fails a test rather than a user.

SAFETY comment added above `Out` in `docs/impl/runtime/substrate-and-supervisor.md`, and a debug assertion for the invariant, so a violation fails a test rather than a user.
Author
Owner

Measured. It is a named constant in docs/impl/lowering/README.md now, with a line saying how.

Measured. It is a named constant in `docs/impl/lowering/README.md` now, with a line saying how.
Two updates from a design conversation that surfaced load-bearing
context not yet in the canonical docs:

1. The type-system docs lead with mechanisms (no subtyping,
   synthesis-only, universal turbofish) but never name the *property*
   those mechanisms exist to enforce: every type is visible in the
   source. That property is the AI-first + Go-speed commitments
   expressed at the type level — it is the reason all the mechanisms
   are shaped the way they are. Added section in type-system/README.md
   ("The property the type system exists to deliver") and reworked the
   opening of inference.md to frame "synthesis-only" as the *how* in
   service of the *why*.

   Uses the PL-theory term "manifest" (types are written, not implicit)
   with a parenthetical disambiguating it from "structural typing"
   (shape-equality — distinct, and not what CkLang is; CkLang is
   nominal).

2. R2's spec previously had a placeholder open-questions section. The
   things that read as "open" close on principles already in the docs
   (meta-substrate is observation-only, uniform rules, runtime trusts
   the front-end) — so they aren't questions. Replaced with one
   positively-framed "Locked stance" line: match is first-arm-wins;
   exhaustiveness is TY7's contract; an unreachable arm at eval raises
   Panic::raise(Unreachable). Also fixed an HM-flavored phrase in the
   front-end prerequisite (arms "unify" → arms widen by tag membership)
   and recorded TY7 as a hard prerequisite for match.

Docs-only. Link checker: 0 broken anchors. cargo check: 0 warnings.
The floor-first re-slice (2026-05-27) renumbered the phase taxonomy:
A=substrate (order 1), B=R1, C=R2-R5, D=R6-R7, E=R8-R10, F=R11-R12.
The README was updated to match; the per-slice spec files were not.
This commit aligns each spec's metadata table and body references to
the README's canonical phase strings.

Per-file changes:

- R1: Status row dropped the "(not yet on master)" qualifier — master
  got R1 via the runtime->master merge.
- R2-R5: Phase A->C, added Order row (3/4/5/6), body Phase A->C; R5's
  body also lost "closes Phase A" (->Phase C) and "Phase B onward"
  (->Phase D onward). R2 metadata Front-end prerequisite cell now
  matches the body (mentions TY7).
- R6: Phase B->D, added Order 7.
- R7: Phase C->D, added Order 8, body Phase C->D.
- R8: Phase row "(order 10)" -> "(orders 9-10)" to match README's full
  phase string.
- R9: Phase D->E, added Order 9. Also fixed a stale dependency: R9
  now correctly says it depends on the substrate (order 1) — R9
  thickens the supervisor that order 1 introduced; it does not depend
  on R8 (order 10, which lands later).
- R10: Phase D->E, added Order 10 (co-lands with R8), Depends-on
  fixed (R9 -> R8: R10 is the optimizer over R8's naive classifier),
  body "Phase A-D fixtures" -> "the whole prior corpus" (the cleaner
  phase-independent phrasing the README itself uses), body "Phase E:
  R11-R12" -> "Phase F".
- R11: Phase E->F, added Order 11, body "Phase A deferred" -> "Phase
  C deferred" (the deferral was always C's, just misnamed before).
- R12: Phase E->F, added Order 12.

Docs-only. Link checker: 0 broken anchors.
Two architectural reframes from a design conversation, landing as one
re-slice of the runtime cascade:

1. RETIRE THE TREE-WALKER. The bootstrap interpreter (ck_eval) is being
   removed. CkLang's design choices (manifest typing, no GC, no general
   subtyping, no HM, no dynamic dispatch, monomorphization, closed
   existentials, bounded collections) make direct lowering simpler than
   interpretation for this language — the hard things compilation
   usually defers don't exist here. The HIR's semantics are now the
   formal reference; the lowering is the only engine. R11 (as-if
   optimizer) is checked against "the simplest lowering's meta stream,"
   not a separate interpreter.

2. CONTAINER EXECUTION VIA CRANELIFT. The new pipeline:
   HIR -> Floor IR -> Cranelift IR -> object file -> linked binary ->
   Alpine container -> meta-stream observation.
   - Cranelift (user lock) for codegen; multi-target falls out.
   - "Floor IR" (the user's "almost-floor HIR") is the intermediate;
     desugars defer into cleanup-wrapping, expands match to decision
     trees, gives closures explicit captures, monomorphizes trait calls.
   - "ck" container (user lock) is long-lived per session, Alpine to
     start, single bind-mount carries binary in + meta-stream file out.
     `--container <name>` flag for multi-container later.
   - Per-type generated MetaEvent serialization (no protobuf complexity)
     per the bounded-collections static-schema rule.

Doc split per user directive "lowering belongs to lowering, running
belongs to running":
- new docs/impl/lowering/ — Floor IR + Cranelift backend
- docs/impl/runtime/ — container scaffold + floor library + actor
  semantics + as-if optimizer + replay

New cascade (17 slices = 4 foundation + 13 semantic, was 12):
  F1 Floor IR scaffold
  F2 Cranelift backend
  F3 Container scaffold
  F4 Meta-stream wire format
  R1 Substrate (was order 1)
  R1' Test fn execution as compiled binary (was R1 tree-walker, retired)
  R2 Bindings & control flow
  R3 Calls & recursion (+ NEW: recursion-depth bounds locked
     2026-05-28 - every recursive function declares max depth, compiler
     uses it for arena stack-frame sizing; spelling open. Third member
     of the bounded-everything family alongside bounded collections.)
  R4 Unhappy path (defer desugared in Floor IR)
  R5 Raise path (system unwinder + Cranelift unwind tables)
  R6 Mocked effects
  R7 Native leaf
  R9 Lifetimes & supervision
  R8 Multi-actor messaging
  R10 As-if optimizer
  R11 OOM upcall
  R12 Deterministic replay

What landed in this commit:
- README.md: top-level synthesis (writes modern, runs 1960s, observes
  2030s) — the load-bearing framing per project_synthesis_framing.
- docs/impl/lowering/{README,F1,F2}.md: new directory.
- docs/impl/runtime/{F3,F4}.md: new foundation slices.
- docs/impl/runtime/README.md: rewritten cascade table + phase
  narrative for the new model.
- docs/impl/runtime/substrate-and-supervisor.md + R1-executor-core.md:
  reframed under the new engine (substrate now at order 5; R1 = test
  fn execution as compiled binary, order 6).
- docs/impl/runtime/R2-R12: cascade metadata (Phase / Order rows)
  aligned with the 17-slice cascade; light language updates for the
  engine swap. The user said "we will refine them later" — these
  are the alignment pass, not deep rewrites.
- docs/impl/runtime/00-executor.md: marked RETIRED at the top; body
  preserved as historical record of the c1fd68d landing.
- docs/types.md: bounded-collection rule documented
  (List<Int>(12) — every collection carries max size).
- docs/impl/memory-model/arenas.md: arena sizing pass now documented
  as inferred from the bounded-collection rule + recursion bounds.
- docs/impl/runtime-testing/*: anchor fixes for the new runtime
  README's section structure.

What did NOT land in this commit (deliberately):
- Old `ck_eval` crate removal — that's code change, lands when F1+F2
  are implemented and supersede it.
- The 34 docs that reference bare `List<T>` in examples — a separate
  sweep, the user is aware.
- The recursion-bound spelling (annotation site + syntax) — principle
  locked, spelling open per project_recursion_bounds.
- Sub-doc renames (file names kept stable; per user "I do not care
  about your JIRA").

Quality gates: link checker 0 broken anchors. No code touched.
hkowalski manually merged commit cd6d4375ff into master 2026-01-22 08:00:00 +01:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
northgale/cklang-bootstrap!19
No description provided.