docs(stdlib): add the CkLang stdlib spec files; reconcile plans #61

Manually merged
tvidal merged 4 commits from feat/061-docs-stdlib-add-the-cklang-stdlib-spec-files-r into master 2026-03-17 18:13:29 +01:00
Owner

docs(stdlib): add the CkLang stdlib spec files; reconcile plans

Along the way:

  • docs(types): declare the floor-facing types; sync the temporal roster
  • docs(spec): make the CkLang root spec internally consistent; unblock slices 1–8
  • docs(orchestrate): drop slice numbers; read plan.md as the entry doc

Touches 28 files: .claude/commands/orchestrate.md, Alloc.ck, CLAUDE.md, Floor.ck, LiteralDSL.ck, Operators.ck and 22 more.

docs(stdlib): add the CkLang stdlib spec files; reconcile plans Along the way: - docs(types): declare the floor-facing types; sync the temporal roster - docs(spec): make the CkLang root spec internally consistent; unblock slices 1–8 - docs(orchestrate): drop slice numbers; read plan.md as the entry doc Touches 28 files: `.claude/commands/orchestrate.md`, `Alloc.ck`, `CLAUDE.md`, `Floor.ck`, `LiteralDSL.ck`, `Operators.ck` and 22 more.
tvidal approved these changes 2026-03-17 15:11:40 +01:00
tvidal left a comment

Happy with this. I ran the suite against the branch and it is green, src/rust/crates/ck_docs_linkchecker/src/lib.rs included.

Happy with this. I ran the suite against the branch and it is green, `src/rust/crates/ck_docs_linkchecker/src/lib.rs` included.
@ -0,0 +282,4 @@
impl BitAnd<bit, bit, bit> { fn band(a: bit, b: bit) -> bit = Floor.band(a, b) }
trait BitOr<A, B, R> {
fn bor(a: A, b: B) -> R
Owner

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

`bor` reads, decides and writes in one function. The deciding part is the piece I would want to test on its own. Worth splitting?
@ -0,0 +83,4 @@
needs no primitive variant — the `ItemRef` change the old step planned is moot.)
- **Step 2 — route nominal receivers through the arity key.** With scalars now
`Ty::Nominal` (3b), `resolve_method_call` already reaches `coherence.traits_for`
for them (`ck_types/src/method_call.rs:325`); the old `_ => Vec::new()` arm that
Owner

The catch-all arm means a variant added later compiles and lands here without a word. Can the match on them name every variant so the compiler tells us?

The catch-all arm means a variant added later compiles and lands here without a word. Can the match on `them` name every variant so the compiler tells us?
@ -94,0 +95,4 @@
// history but never leading (see `plan.md` "Deferred / archived"). Their
// links point at the pre-restructure layout on purpose, so the archive is
// out of scope for the link gate — only live docs must stay linked.
let archived = docs_root.join("old");
Owner

I had to read archived twice. Nothing wrong with it, but one line of comment would save the next person the second read.

I had to read `archived` twice. Nothing wrong with it, but one line of comment would save the next person the second read.
Author
Owner

Comment added on archived in src/rust/crates/ck_docs_linkchecker/src/lib.rs. It was obvious when I wrote it and it will not be in a month.

Comment added on `archived` in `src/rust/crates/ck_docs_linkchecker/src/lib.rs`. It was obvious when I wrote it and it will not be in a month.
Author
Owner

Split. The decision in bor is a pure function now, with its own tests in Prelude.ck.

Split. The decision in `bor` is a pure function now, with its own tests in `Prelude.ck`.
Author
Owner

Named them all. A new variant is a compile error in slice_traits.md now, which is where we want to find out.

Named them all. A new variant is a compile error in `slice_traits.md` now, which is where we want to find out.
Introduce the always-linked stdlib as manifest CkLang spec drafts and align
the plan leaves to them.

New .ck spec files:
- Floor.ck      — the closed 1:1 machine floor + the one `tick` event-loop grain
- Types.ck      — aliases (Int=i64), base value types (String/List/Map/Set),
                  Option, the Error trait tier, and world-types (Color/Money/Geo)
                  with one uniform impl form and concrete per-tag impls
- Prelude.ck    — the operator-trait tier, one impl per concrete primitive
- Operators.ck  — the operator symbol / precedence table

Plan reconciliations (soll aligned to the .ck files):
- Eq -> Equals everywhere (Equals is the trait; Eq is not a CkLang trait)
- size_of is not a floor leaf (compile-time iconst); floor roster completed
  (negate/remainder/bitwise/shift/float families)
- Int/Float are `type` aliases (i64/f64 sugar), not distinct primitives
- retire "Preamble" -> "Types.ck" / the always-linked stdlib units
- move write(String)/openat(String) off the floor; keep byte-level leaves

Types.ck design rulings (owner):
- no blanket impls — Money expands to concrete per-currency impls; unlocked
  rosters (Length units, temporal reps) are honest stubs, not invented sweeps
- Literal is Form A (`impl Literal<T>`), never `impl … for T`
- closed `data Currency` tag (Money<USD>) is the currency-safety, not String<3>

Also carries pre-existing working-tree changes: the workspace `dead_code = "deny"`
gate in Cargo.toml and the removal of prompt.md.
Add the low-level types Floor.ck / Memory / Clock speak in, so the floor is a
fully type-checkable unit with no compiler-known atom beyond Unit/Nothing:

  - usize       alias to u64 (pointer/offset width, bootstrap target)
  - Region      record { offset, size } — a fenced span carrying its own bound
                (plan_values_02 §4's (position,length) shape, at the region tier)
  - Handle      usize position (Region base + byte offset); NOT generic — the
                element type rides Floor.load<T>/store<T>, not the handle
  - TickHandle  opaque one-word receipt from Floor.tick, for defer teardown

Function<Ret> is intentionally NOT declared: CkLang has no syntax yet for a
compile-time-only type with no runtime representation (pending owner decision on
the declaration form; the earlier `comptime: true` marker was an invented
Zig-ism and is removed).

Also carries the in-progress temporal roster already in the working tree:
Date/Time/DateTime + TimeSpan/DateSpan over the output-typed Sub<A,B,R> op form.
Consistency review of the plan*/slice*/*.ck spec plus the owner design
decisions taken this pass:

- Floor.ck is now dependency-free (the root): usize/Region/Handle/TickHandle
  declared in-file, syscalls typed i64, tick interval raw nanoseconds.
- Slice sequence reordered root-first (intrinsics → primitives → alloc → values
  → function-calls → traits → operators → prelude → actors) and renumbered
  across every slice file; add slice_alloc.md (Alloc.ck supersedes Memory.ck).
- `type String = String<64>` locked — bare String resolves by arity.
- Operators carry precedence only; associativity removed everywhere —
  same-precedence chains require explicit parentheses.
- &&/|| reconciled to if-body operators; hir::BinOp eliminated entirely.
- LiteralDSL.ck: the exotic-literal pattern DSL as a root unit (closed char
  classes + closed Form grammar set + the capture-typing rule); from_literal is
  a foldable sublanguage; claim vocabulary moved out of Types.ck.
- Fixed stale content: relational trait arity (<T>), ^ is bitwise xor, the
  memory-op leaf list, module naming (Memory/Sys -> Floor/Alloc), and removed
  all `impl ... for`/`-> Self` (one impl syntax).
- Actors (slice 9) explicitly deferred to the next phase.
- linkchecker: exclude the docs/old archive from the link gate.
$ARGUMENTS now names the entry document to read first (default plan.md), not a
numbered goal. Refer to slices by subject + dependency position; derive order
live from plan.md, whose numbering may change. Removes the stale "slices 1–7"
and "slice 3/slice 4" examples left over from the root-first renumber.
tvidal manually merged commit 3bc3598a83 into master 2026-03-17 18:13:29 +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!61
No description provided.