docs(model): reconcile 0007 Series with the shipped step-1 reality

The `series` library extension shipped (35a9bc6); model 0007's
Series section was an aspirational sketch with systematic defects
that no longer match the live tool. Bring it to present-state per
the honesty-rule:

- STATUS: the library-extension milestone now reads step-1 shipped
  (primitive Series over {Int, Float}, Bool deferred), with SoA
  step-2 (#62) still pending. INDEX.md row updated to match.
- The `series` code listing is replaced with the shipped source
  (crates/ailang-kernel/src/series/source.ail, doc-strings elided),
  cited as the source of truth. Every defect the sketch carried is
  corrected in the shipped form it now shows: param-in (a Int Float)
  not (... Bool); `(new RawBuf lookback)` with no type-arg; bare `a`
  for the element type variable (not `(con a)`); forall-bound op
  signatures; `lt` not `<`; and the at-index formula with the
  correct sign on i — which already matched the section's own prose
  (`head - 1 - i + 2*lookback`), so the sketch was internally
  inconsistent and the prose was right.
- The SMA worked example uses `ge` (not the non-existent `>=`) and
  emits each average followed by a newline, matching the committed
  pin fixture so the doc and the test agree.
- The "four constructs not in today's AILang" framing is now
  present-state: the mechanisms shipped via raw_buf, Series itself
  via the step-1 library extension.

Both edited module blocks parse against the live tool.

refs #61
This commit is contained in:
2026-06-02 13:12:01 +02:00
parent 35a9bc67b1
commit 73fbb240be
2 changed files with 40 additions and 28 deletions
+1 -1
View File
@@ -110,4 +110,4 @@ is the default.
| authoring-surface | onboarding / evolves | design/models/0001-authoring-surface.md | | authoring-surface | onboarding / evolves | design/models/0001-authoring-surface.md |
| prose-projection | onboarding / evolves | design/models/0006-prose-projection.md | | prose-projection | onboarding / evolves | design/models/0006-prose-projection.md |
| pipeline | onboarding / evolves | design/models/0003-pipeline.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/src/raw_buf` base extension; series milestone pending) | design/models/0007-kernel-extensions.md | | kernel-extensions | onboarding / evolves (mechanisms milestone closed 2026-05-28; ratified end-to-end by the `ailang-kernel/src/raw_buf` base extension; series library extension step-1 shipped via `ailang-kernel/src/series`, SoA step-2 #62 pending) | design/models/0007-kernel-extensions.md |
+39 -27
View File
@@ -6,8 +6,11 @@ landed). The four language-level mechanisms — type-scoped
namespacing, `Term::New`, kernel-tier modules + auto-import, and namespacing, `Term::New`, kernel-tier modules + auto-import, and
`param-in` — are shipped and ratified by the `raw_buf` base `param-in` — are shipped and ratified by the `raw_buf` base
extension (`crates/ailang-kernel/src/raw_buf/`). The base-extension extension (`crates/ailang-kernel/src/raw_buf/`). The base-extension
milestone (`raw-buf`) has shipped; the library-extension milestone milestone (`raw-buf`) has shipped. The library-extension milestone
(`series`) is pending. This (`series`) has shipped its step-1 primitive Series over `{Int, Float}`
(`crates/ailang-kernel/src/series/`, the first pure-AILang library
extension; `param-in` defers `Bool`); step 2 — struct-of-arrays
record elements (#62) — is pending. This
whitepaper describes the design as a coherent whole; the whitepaper describes the design as a coherent whole; the
per-milestone specs in `docs/specs/` carry the implementation- per-milestone specs in `docs/specs/` carry the implementation-
level detail. Sections describing the now-shipped mechanisms read level detail. Sections describing the now-shipped mechanisms read
@@ -74,10 +77,12 @@ moving average over a stream of float values, window size 3":
(ret (own (con Unit))) (effects IO))) (ret (own (con Unit))) (effects IO)))
(params s n) (params s n)
(body (body
(if (app >= (app Series.total_count s) n) (if (app ge (app Series.total_count s) n)
(app print (app / (seq
(app sum_window_step s n 0 0.0) (app print (app /
(app int_to_float n))) (app sum_window_step s n 0 0.0)
(app int_to_float n)))
(do io/print_str "\n"))
(do io/print_str "")))) (do io/print_str ""))))
(fn run_stream (fn run_stream
@@ -108,8 +113,10 @@ moving average over a stream of float values, window size 3":
(term-ctor FloatList FNil)))))))))))) (term-ctor FloatList FNil))))))))))))
``` ```
Four constructs in this program are not in today's AILang. Each Four constructs in this program rest on the four mechanisms this
maps onto one of the four mechanisms this whitepaper defines: whitepaper defines — all now shipped (the mechanisms via the
`raw_buf` base extension, `Series` itself via the step-1 library
extension):
- `Series` appears in type position with no module qualifier - `Series` appears in type position with no module qualifier
(`(con Series (con Float))`) — *kernel-tier modules*. (`(con Series (con Float))`) — *kernel-tier modules*.
@@ -437,33 +444,38 @@ handles allocation, drop, and copy-on-share.
`Series a` is a bounded ring buffer with financial-style indexing `Series a` is a bounded ring buffer with financial-style indexing
(index 0 = newest). It is a plain AILang ADT in a kernel-tier (index 0 = newest). It is a plain AILang ADT in a kernel-tier
`.ail` module: `.ail` module. Source of truth:
`crates/ailang-kernel/src/series/source.ail` — the listing below
is that module with the per-item `(doc …)` strings elided for
readability:
``` ```
(module series (kernel) (module series
(kernel)
(data Series (vars a) (data Series (vars a)
(param-in (a Int Float Bool)) (param-in (a Int Float)) ; Bool deferred (#61)
(ctor S (con RawBuf a) ; the storage (no mode: modes live on (ctor S (con RawBuf a) ; the storage (no mode: modes live on
; fn params/ret, not on ADT fields) ; fn params/ret, not on ADT fields)
(con Int) ; lookback (con Int) ; lookback
(con Int) ; head index (con Int) ; head index
(con Int) ; current count (con Int) ; current count
(con Int))) ; total pushes ever (con Int))) ; total pushes ever
(fn new (fn new
(type (fn-type (type (forall (vars a) (fn-type
(params (own (con Int))) (params (own (con Int)))
(ret (own (con Series a))))) (ret (own (con Series a))))))
(params lookback) (params lookback)
(body (body
(term-ctor Series S (term-ctor Series S
(new RawBuf (con a) lookback) lookback 0 0 0))) ; element solved from the (con RawBuf a) ctor field — no type-arg
(new RawBuf lookback) lookback 0 0 0)))
(fn push (fn push
(type (fn-type (type (forall (vars a) (fn-type
(params (own (con Series a)) (own (con a))) (params (own (con Series a)) (own a))
(ret (own (con Series a))))) (ret (own (con Series a))))))
(params s v) (params s v)
(body (body
(match s (match s
@@ -472,31 +484,31 @@ handles allocation, drop, and copy-on-share.
(app RawBuf.set buf head v) (app RawBuf.set buf head v)
lookback lookback
(app % (app + head 1) lookback) (app % (app + head 1) lookback)
(if (app < count lookback) (app + count 1) count) (if (app lt count lookback) (app + count 1) count)
(app + total 1)))))) (app + total 1))))))
(fn at (fn at
(type (fn-type (type (forall (vars a) (fn-type
(params (borrow (con Series a)) (own (con Int))) (params (borrow (con Series a)) (own (con Int)))
(ret (own (con a))))) (ret (own a)))))
(params s i) (params s i)
(body (body
(match s (match s
(case (pat-ctor S buf lookback head count total) (case (pat-ctor S buf lookback head count total)
(app RawBuf.get buf (app RawBuf.get buf
(app % (app + (app - head 1) (app + (app * lookback 2) i)) lookback)))))) (app % (app + (app - (app - head 1) i) (app * lookback 2)) lookback))))))
(fn len (fn len
(type (fn-type (type (forall (vars a) (fn-type
(params (borrow (con Series a))) (params (borrow (con Series a)))
(ret (own (con Int))))) (ret (own (con Int))))))
(params s) (params s)
(body (match s (case (pat-ctor S buf lookback head count total) count)))) (body (match s (case (pat-ctor S buf lookback head count total) count))))
(fn total_count (fn total_count
(type (fn-type (type (forall (vars a) (fn-type
(params (borrow (con Series a))) (params (borrow (con Series a)))
(ret (own (con Int))))) (ret (own (con Int))))))
(params s) (params s)
(body (match s (case (pat-ctor S buf lookback head count total) total))))) (body (match s (case (pat-ctor S buf lookback head count total) total)))))
``` ```