AILang/docs/specs/0067-fieldtest-series-step1.md

Fieldtest — series-step1 — 2026-06-02

Status: Draft — awaiting orchestrator triage Author: fieldtester (dispatched by fieldtest skill)

Scope

The Series a kernel-tier library extension shipped at 35a9bc6 (model-0007 reconciliation at 73fbb24). It is a bounded ring buffer with financial-style indexing (index 0 = newest), built as PURE AILang over RawBuf — zero Rust intercepts, zero (intrinsic) markers. The element type is restricted to {Int, Float} via param-in (Bool deferred, #61). It is auto-imported like a built-in (no (import series) needed). Public type-scoped API: (new Series (con T) lookback), Series.push : (own (Series a), own a) -> own (Series a), Series.at : (borrow (Series a), Int) -> own a (0 = newest), Series.len : (borrow (Series a)) -> Int (live count, saturates at lookback), Series.total_count : (borrow (Series a)) -> Int (monotone total pushes).

This field test probed five axes: construction/auto-import discovery, ring-buffer + financial-indexing ergonomics, len/total_count bookkeeping with warmup, param-in error quality, and operator-naming friction.

The build exercised was the HEAD working tree, invoked via cargo run -q --bin ail -- build --alloc=rc <fixture> (debug profile); each produced native binary was then run directly, and re-run under AILANG_RC_STATS=1 for drop soundness.

Examples

examples/fieldtest/series-step1_1_rolling_max.ail — rolling max over the last-3 window

• Streams 6 Ints into a size-3 Series and, after each push, prints the max of the live window by scanning Series.at s i for i in [0, Series.len s).
• Fits the ring-buffer/financial-indexing + warmup axes: it proves eviction (a large old value scrolled out of the window stops winning) and handles warmup by bounding the scan at the live count.
• Outcome: checked, built, ran. Stdout 4 4 7 7 7 3 — exactly expected, including the eviction proof (max drops from 7 to 3 when 7 is evicted). Leaks live=8 under AILANG_RC_STATS (see finding [bug]).

examples/fieldtest/series-step1_2_last_n_events.ail — last-N events ring, oldest-first dump

• Pushes 7 Ints into a size-3 Series, then dumps the live window oldest-first by walking Series.at from len-1 down to 0, and reports total_count (7) and len (3).
• Fits the wrap-boundary off-by-one axis (the buffer wrapped 2+ times before the dump) and the len-vs-total_count bookkeeping axis.
• Outcome: checked, built, ran. Stdout 50 60 70 7 3 — correct; financial indexing maps correctly after multiple wraps; total_count did not saturate, len did. Leak-clean (live=0).

examples/fieldtest/series-step1_3_warmup_rolling_sum.ail — Float warmup-gated rolling sum

• Streams 6 Floats into a size-4 Series; emits the rolling sum only once Series.len s == 4 (warmup suppressed for the first 3 pushes).
• Fits the Float-element + warmup/bookkeeping axes; pins the reading that "full window" is gated on the saturating len, not total_count.
• Outcome: checked, built, ran. Stdout 20.0 28.0 36.0 — correct, with warmup suppressed and correct eviction. Leaks live=8 (same bug).

examples/fieldtest/series-step1_4_paramin_str_reject.ail — param-in Str element (MUST FAIL)

• A single push of a Str into (con Series (con Str)). The only defect is the disallowed element type.
• Fits the param-in error-quality axis.
• Outcome: ail check rejects with exit code 1 and a high-quality diagnostic (see finding [working]). A (con Bool) probe produced the same clean diagnostic.

examples/fieldtest/series-step1_5_drop_leak_repro.ail — minimal drop-leak reproduction

• Smallest form of the leak: push two Ints into a size-3 Series via tail-app recursion whose base case returns Unit.
• Outcome: checked, built, ran. Stdout done; live=4 under AILANG_RC_STATS. This is the reduced repro for the [bug] below.

Findings

[working] Construction, auto-import, and financial indexing are correct and ergonomic

• Examples 1, 2, 3.
• All three reach for (new Series (con T) lookback) with no (import series) — auto-import works as the whitepaper promises. Series.push / Series.at / Series.len / Series.total_count resolve type-scoped at the call site with no qualifier. Financial indexing (0 = newest) is intuitive: walking [0, len) gives newest→ oldest, walking len-1 down to 0 gives oldest→newest, and the index maps correctly even after the buffer wraps 2+ times (example 2). All three programs produced exactly the predicted output on the first run.
• This is a clear win: the bounded-buffer mental model the LLM author reaches for maps directly onto the API, and eviction/warmup are handled by the len/at pair without any off-by-one surprise.
• Recommended downstream action: carry-on.

[working] param-in diagnostic is exactly what the ledger promised

• Example 4 (plus a (con Bool) probe).
• Verbatim: error: [param-not-in-restricted-set] main: type-arg Stris not in the restricted set for type-variableaofseries.Series (allowed: one of {Float, Int}). Exit code 1. The Bool element produced the identical shape with Bool substituted.
• Names the offending type, the type-variable, the fully-qualified type series.Series, and the allowed set — matching the ParamNotInRestrictedSet contract in model 0007 §param-in. Actionable and precise.
• Recommended downstream action: carry-on.

[bug] Owned Series threaded through a tail-recursive stream loop leaks the RawBuf slab

• Examples 1, 3, 5; also the committed reference examples/series_sma.ail (live=8).
• Under AILANG_RC_STATS=1, the canonical streaming pattern the whitepaper itself uses leaks heap allocations:
  • series_sma (committed reference): allocs=19 frees=11 live=8
  • series-step1_1_rolling_max: live=8
  • series-step1_3_warmup_rolling_sum: live=8
  • series-step1_5_drop_leak_repro (minimal): allocs=7 frees=3 live=4
• The trigger is an (own (con Series ...)) value threaded through tail-app recursion whose base case returns a non-Series type (Unit) and does not explicitly consume the owned Series. The intermediate push results and/or the final Series alive at the base-case arm are never dropped. A let s_new (Series.push s v) binding adds to the leak vs. passing the push directly as the tail-app argument (live=4 vs live=2 in the minimal probe).
• Not Series-specific. A control probe wrapping a plain heap IntList in a user Box ADT and threading it through the identical tail-recursion pattern also leaks (live=7). The root is general drop soundness for an owned heap value reaching a base case that neither returns nor consumes it; Series merely surfaces it heavily (RawBuf slab + wrapper) and on the whitepaper's headline pattern. The Series module source itself is pure AILang and behaves correctly — example 2 (Series returned from the recursion and dropped at the caller's scope close) is live=0.
• One-line repro: ail build --alloc=rc examples/fieldtest/series-step1_5_drop_leak_repro.ail -o /tmp/r && AILANG_RC_STATS=1 /tmp/r → ailang_rc_stats: allocs=7 frees=3 live=4.
• Recommended downstream action: debug (RED-first). Note for the debugger: probe whether this is the same own-param-at-non-consuming- base-case drop family seen in prior cutover work, not a Series codegen issue. The contradiction with model 0007's "dropping the Window frees the slab / leak-clean" claim should be resolved by fixing the drop, not by softening the doc.

[friction] ail describe does not resolve the canonical type-scoped Series.<op> form

• Discovery axis (probed via the CLI, not a fixture).
• ail describe --workspace examples/series_sma.ail Series.push and ... Series.at both fail with Error: no module Series in workspace. The same ops resolve via the module-scoped series.push or the bare push. describe --workspace ... Series prints only the Series TypeDef (with param-in), not its operations.
• This is friction, not a bug against a written contract: model 0007 §1 declares type-scoped access the canonical form for type-associated operations and names TypeScopedReceiverNotAType for a bad receiver — but describe treats Series.push as a module path and reports a module-not-found error even though Series IS a known type. A downstream LLM author who has just written (app Series.push s v) and wants to confirm its signature will type describe ... Series.push first (the canonical form) and hit a dead end, then has to know to fall back to series.push or bare push. Discovery of the op set for a type is also absent: neither describe Series nor builtins lists the five Series ops (builtins covers only the 20 primitive operations).
• Recommended downstream action: plan (tidy iteration) — make describe's name resolver try the type-scoped branch (mirroring the call-site resolver in model 0007 §1), and consider surfacing a type's home-module ops when describe-ing the type itself.

[spec_gap] Whitepaper §Series substrate writes a ctor-field mode that does not parse; correct field form for a Series-like wrapper is undocumented

• Surfaced while drafting (carried over from the raw-buf fieldtest examples/fieldtest/rbx_1_float_window_stats.ail, re-confirmed this cycle as still the live behaviour).
• Model 0007 §"Series — the library extension" shows the storage ctor field as (con RawBuf a) with a comment "no mode: modes live on fn params/ret, not on ADT fields" — which is correct and parses. But the two-tier §"Library extensions" prose and the §Series-substrate framing elsewhere lead an author to try (own (RawBuf a)) in a ctor field (a surface parse error) or a bare unqualified (con RawBuf (con T)) (a type-mismatch: RawBuf vs raw_buf.RawBuf) when writing their own Series-like wrapper ADT. The only form that checks for a user module is the fully-qualified (con raw_buf.RawBuf (con T)).
• The reading I picked: a downstream author wrapping a kernel base type in their own ADT field must fully-qualify it (raw_buf.RawBuf), even though the kernel-tier series module uses the bare a-parametrised (con RawBuf a) form (which works because series is itself kernel-tier and the element is a type variable, not a concrete bare ctor ref). Another equally plausible reading: bare (con RawBuf (con T)) should resolve via the same kernel auto-import that makes (con Series (con Float)) work bare at a call site — the asymmetry (bare Series type-position OK, bare RawBuf ctor-field not OK) is not stated anywhere in the public surface.
• Recommended downstream action: ratify / tighten the design ledger — document, in model 0007 or contract 0002, the rule for referencing a kernel base type from a user ADT ctor field (must fully-qualify; bare works only inside a kernel-tier module or in type-position via auto-import), so the asymmetry is no longer a guess.

Recommendation summary

Finding	Class	Action
Construction / auto-import / financial indexing correct	working	carry-on
param-in diagnostic quality	working	carry-on
Owned Series tail-recursion leaks RawBuf slab	bug	debug
describe does not resolve type-scoped Series.<op>	friction	plan
Whitepaper ctor-field mode / bare-RawBuf-in-field asymmetry	spec_gap	ratify / tighten ledger