#Jennifer - Milestones

Development is split into milestones. Each milestone produces a working interpreter that runs a strictly larger subset of the language.

Note on compaction. Older milestone entries are periodically compacted - condensed to a short summary (and sometimes grouped) - to keep this file readable and its length in check. The compacted text records what shipped, not the full implementation design. For the detailed design, rationale, and step-by-step evolution of any milestone, dig into the git history (the commits for that milestone) - that is the authoritative record of how it was built.

#M1 - End-to-end MVP

Smallest vertical slice that proves the pipeline (source → tokens → preprocessed tokens → AST → result):

• Types: int, string
• def x as int init 5;, $var references, method defs (zero-arg, top level), import "file.j";, use io;, single-arg printf
• Arithmetic + - * / % on ints; comments # and /* */
• Source-context caret in error messages
• Golden-file integration test and TinyGo build verified

Exit criterion: ./jennifer run examples/hello.j prints 42.

#M2 - Types, constants, scoping, control flow

Rounds out the "ordinary" feature set:

• New types float, null, bool with literals 3.14, null, true, false
• Uninitialized def x as T; gives T's zero value
• def const NAME as TYPE init VALUE; (reassignment is an error)
• Nested block scoping; inner scopes cannot redeclare visible names
• Assignment statement $x = EXPR;
• Comparison < > <= >= ==, + for string concat, int↔float promotion
• Escape parsing in '...' strings (previously only "...")
• Control flow: if/elseif/else, while, for, all requiring bool conditions (no implicit truthiness)

#M3 - Methods with parameters and return values

• func name(a as int, b as string) { ... } with typed parameters, by-value argument passing, call-site arity + type checks
• return; and return EXPR;; recursion works
• sprintf and format verbs %d %f %s %t %v %% for both printf and sprintf
• The omnibus stdlib retired in favor of topic-based libraries; io is the first.

#M4 - Polish & ergonomics

• Logical operators and, or, not (word-based, short-circuit)
• Unary minus
• Python-3 division: / always returns float; new div keyword for floor division (// is taken by line comments)
• Floats always display with a decimal (5.0, not 5) so the type stays visible
• New libraries (all use-gated): convert, math, strings
• Interpreter gained RegisterConst so libraries can expose constants (PI, E).

#M5 - Interpreter improvements

• Cross-file error sources - errors raised inside an imported .j display the line from the imported file. See technical/interpreter.md > Errors and positions.
• REPL - jennifer repl, persistent globals/methods/imports across inputs, multi-line input via brace balancing, expression results printed. See technical/cli_repl.md > REPL.
• REPL line editor - cursor keys, Home/End, word motions, Ctrl+W / Ctrl+U / Ctrl+K, in-memory history (Up/Down), Ctrl+C cancel. Non-TTY stdin falls back to plain line reading. See technical/cli_repl.md > Line editor.
• Auto-loaded core library - new library kind, pre-imported at startup; writing use core; is a runtime error. Contents: JENNIFER_VERSION (a git describe-derived build-version constant) and len (polymorphic over strings now; lists/maps in M6). len moved here from strings. (M15.4 later promoted len to a language built-in and deleted core; see M15.4 for the migration.) Version injection details at technical/cli.md.
• Formatter - jennifer fmt re-emits canonical source per user-guide/style-guide.md. Token-level walker so file imports and user-written parentheses survive. See technical/cli_fmt.md > Formatter.
• Inspection subcommands - jennifer tokens <file> dumps the lexer output; jennifer ast <file> dumps the preprocessed AST as JSON. See technical/cli_inspect.md > Inspection.
• Underscore-in-constants - constant names became [A-Z]+(_[A-Z]+)*, enabling MAX_RETRIES and the JENNIFER_VERSION rename. See technical/lexer.md > Identifier rule.
• Documentation overhaul - docs/technical.md split into docs/technical/<topic>.md; docs/lib_*.md moved to docs/libraries/; new docs/user-guide/style-guide.md.

#M6 - Lists and maps

Two new compound types - list and map - plus the strings library functions deferred until compound types existed.

• Syntax: def xs as list of int init [1, 2, 3];, def m as map of string to int init {"a": 1};. Index read/write $xs[i], $m["k"], chains $g[i][j]. Iteration via for (def x in $coll) { ... } (new keyword in). New tokens [ ] : and keywords list, map, of, to, in.
• Semantics: value-typed (copy on assignment and on function-parameter binding; no aliasing); const is deep ($NUMS[0] = ... is a runtime error if NUMS is const); out-of-bounds list reads/writes and missing map keys are positioned runtime errors; map iteration is insertion-order deterministic.
• Type system: parser.Type became a recursive struct (Element, KeyType, ValType *Type slots), so nesting like list of list of int falls out without depth cap. 3+ levels is a documented code smell.
• Stdlib: core.len extended to lists and maps; core.has(m, key) for membership tests; strings.split, strings.chars, strings.join finished.
• Tooling: formatter handles [...] / {...} per user-guide/style-guide.md (no inner padding, space after ,/:, block-vs-map disambiguation via a small brace stack); AST JSON emitter handles ListLit, MapLit, IndexExpr, IndexAssignStmt, ForEachStmt.

See user-guide/types-and-values.md > Lists and maps for the user-facing tour, and technical/grammar.md / technical/interpreter.md for the implementation contract.

#M7 - printf modifiers, stdin input, comment/division swap

A breaking syntax change to free up // for integer division and to allow shebangs, the long-promised format-verb modifier system, and the first stdin-reading builtins.

• Comments and integer division (BREAKING). Line comments moved from // to #, freeing // for floor division (Python 3 shape). div keyword removed. A Jennifer file can now begin with #!/usr/bin/env -S jennifer run.
• (s)printf format-verb modifiers. Each format verb except %v accepts a pipe-separated, order-independent flag list: %verb[|key=value]*. Modifiers shape presentation only - data transformations (case=upper on strings, markdown rendering, etc.) are explicitly out of scope; libraries do that work. Verbs gained: pad/max/align/mode (%s); pad/fill/align/base/ sign/group/sep (%d); prec/trim/sci/pad/align/ sign (%f); case (%t); shared null=empty|null|literal(...) across all four typed verbs. %v deliberately takes none.
• Format-string breaking change. | immediately after a verb now starts a modifier list. Pre-M7 strings with | as a literal separator ("%d|%d") need either a different separator or the || escape (parallels %%).
• io stdin input. New builtins readLine(), readLine(prompt), eof() - one-line-at-a-time reads with an explicit EOF predicate (while (not eof()) { ... }). Refuses inside the REPL since the line editor owns stdin.
• Internals. Builtin signature changed from func(out io.Writer, args) to func(ctx BuiltinCtx, args) so stdin and the REPL flag are plumbed symmetrically with stdout. Mechanical refactor across the ~30 existing builtins.

See:

• libraries/io.md - full modifier and input reference.
• technical/lexer.md and technical/grammar.md - the comment / division syntax change.
• technical/rejected.md - what the modifier system deliberately doesn't do (data transformations, %a aggregate, null=sql/null=skip) and why the literal-pipe lookahead alternative was turned down.
• technical/interpreter.md > Builtins and libraries - the BuiltinCtx signature.

#M8 - System library namespacing

A hybrid namespace model so domain libraries can ship without polluting the bare-name pool, plus the first real namespaced library (os) so the machinery has a non-synthetic exercise.

• Hybrid model. Essential libraries (io, convert, math, strings, auto-loaded core) stay flat - their builtins are bare names. Domain libraries register through a new namespaced API (RegisterNamespaced / RegisterNamespacedConst) and are addressed by prefix.name(...) / prefix.NAME. The library's name doubles as the namespace prefix.
• Qualified calls and constants. New AST nodes QualifiedCallExpr and QualifiedConstRefExpr; parsed as IDENT "." IDENT (then ( decides). Lookup is keyed by (namespace, name) and gated by use lib;.
• use NAME as ALIAS; aliasing. Optional as clause on use. Rename-not-addition: after use bio as b; only b. resolves, bio.foo() errors with a "did you mean b?" hint; the canonical name bio is freed for ordinary identifier use. Matches Python's import foo as bar. Aliasing is rejected for flat libraries (use math as m; errors as meaningless).
• Namespace prefix is a reserved identifier. After bare use bio;, func bio() {} errors with shadows imported namespace 'bio'. After use bio as b;, only b is reserved.
• No migration. The change is purely additive; all five flat essentials continue to work unchanged.
• Demo library os (minimal slice). First namespaced library: os.platform() -> string, os.getEnv(name) -> string, os.JENNIFER_LF, os.JENNIFER_OS. Two functions plus two constants - enough to exercise namespaced zero-arg calls, namespaced calls with arguments, namespaced constants, and aliasing end-to-end. Expands in M15.1.

See:

• libraries/os.md - the shipping demo library.
• libraries/index.md - flat vs namespaced policy and the rule for library authors.
• user-guide/imports.md > Namespaced libraries and aliasing - user-facing reference for use NAME [as ALIAS]; and qualified calls.
• user-guide/style-guide.md > Namespaced calls - spacing convention around ..
• technical/grammar.md - EBNF for qualifiedCall / qualifiedConstRef and the use ... as ... shape; AST table entries for the new nodes.
• technical/interpreter.md > Namespaced libraries (M8) - registration API, nsPrefixes / nsAliasedAway resolution tables, no-shadowing rule for namespace prefixes.

#M9 - Collection operations

Two new namespaced libraries cover the M6-deferred list/map manipulation helpers, a small append sugar shortens the common write pattern, and two follow-on breaking changes tidy up the flat-vs-namespaced split.

• lists library (use lists;, namespaced). lists.push, lists.pop, lists.first, lists.last, lists.head, lists.tail, lists.reverse, lists.sort, lists.contains, lists.concat, lists.slice. Non-mutating - every function returns a new list. sort accepts numeric, string, or bool elements (mixed int/float promotes; other mixes error); comparator-based sort is deferred until methods are first-class.
• maps library (use maps;, namespaced). maps.keys, maps.values, maps.has, maps.delete, maps.merge. Same shape. maps.delete of a missing key errors (strict at boundaries, matching $m[missing]); maps.merge layers the second arg over the first.
• Sugar: $xs[] = item; - write-only target meaning "just past the end of the list". Equivalent to $xs = lists.push($xs, item);. Reads of $xs[] and chained forms ($xs[0][]) are parse errors; non-list targets error at runtime. New AST node AppendStmt.
• BREAKING: has() moved from core to maps as maps.has(m, key). Bare has(...) callers now need use maps; and the qualified form. has was the only non-polymorphic name in core; len stays because it genuinely spans string / list / map.
• BREAKING: strings library moved from flat to namespaced. upper(s) → strings.upper(s), contains(s, sub) → strings.contains(s, sub), etc. across all 15 functions. use strings; itself is unchanged. The M8 library-author rule named exactly these collision-prone verbs (contains, split, replace, join); acting on it now keeps callers off the wrong shape before more libraries arrive. After M9 the remaining flat libraries are io, convert, math, and auto-loaded core.

See:

• libraries/lists.md / libraries/maps.md - function reference for each new library.
• libraries/strings.md - now namespaced (M9 migration note at top).
• libraries/index.md - updated flat-vs-namespaced catalog and the library-author rule.
• user-guide/imports.md and user-guide/types-and-values.md > The $xs[] append sugar - user-facing reference.
• technical/grammar.md - EBNF and AST entry for AppendStmt.

#M10 - Namespace-first library architecture

A pre-language-completion API-shape correction: every library is now namespaced, with bare-name globals reserved as a narrow core-only exception. Small implementation surface, large API shape; pre-1.0 is the window for this kind of change.

• BREAKING: io, math, convert migrate to namespaced-only. printf(x) → io.printf(x), sqrt(x) → math.sqrt(x), etc. The "io is special, keep it flat" alternative was considered and rejected at kickoff to keep a uniform "every call carries its library name" rule. strings, lists, maps, os were already namespaced (M9/M8).
• BREAKING: convert's four conversion callees are renamed to convert.toInt, convert.toFloat, convert.toString, convert.toBool so they don't collide with the type keywords (int, float, string, bool); convert.typeOf keeps its name. The to-prefix also reads as English ("convert to int") at the call site.
• BREAKING: file-splice keyword import → include. include "x.j"; is the textual splice; the import keyword is reserved for the M17 module system and produces a migration-hint error today. Mixing-mistake diagnostics updated.
• BREAKING for embedders: registration API renamed. Register / RegisterConst → RegisterGlobal / RegisterGlobalConst, making their role explicit ("expose this name globally"). The namespaced API (RegisterNamespaced / RegisterNamespacedConst) keeps its name and is the recommended default. Per-library storage (globalFnsByLib, globalConstsByLib) so two libraries with the same global name can no longer silently overwrite each other at Install time; the resolution map is populated by processImports when a library activates.
• math absorbs the planned non-crypto random helpers: math.rand(), math.randInt(lo, hi), math.randSeed(n). Three functions don't justify their own library under the new threshold (next bullet); pseudo-random fits math's pure-numeric charter. The crypto-grade variant still ships in M20.1 crypto. The originally planned M14.2 random library is removed.
• core is the only library publishing bare-name globals. len and JENNIFER_VERSION only - no core.len / core.JENNIFER_VERSION qualified form, because shipping the same name two ways violates stance #1. core is the auto-loaded escape hatch, and its asymmetric exposure is the whole point.
• Three globals-publishing rules in processImports, all forward-looking (inert today since core is the only globals-publishing library and can't be used):
  1. Duplicate use of a globals-publishing library is rejected (library 'X' already in scope); REPL no-ops a repeat.
  2. use X as Y; where X has globals but no namespaced names is rejected as meaningless.
  3. Two active libraries publishing the same global name are rejected at the second use (library "B" collides with already-active library "A" on global "VER"). The pre-M10 flat-only-alias-meaningless check is removed for the general case but kept as rule 2.
• Library-author guidance updated. The docs/libraries/index.md "flat vs namespaced" framing is retired; the new policy is "every library is namespaced; only core ships globals via RegisterGlobal." The "deserves its own library" threshold is raised from M8's "3+" to "5+ functions or constants": anything smaller folds into the most-related existing library. The non-crypto random helpers (3 functions) are the first case the new rule caught.

See:

• libraries/io.md, libraries/math.md, libraries/convert.md - migrated library references.
• libraries/index.md - retired flat-vs-namespaced framing; new library-author policy and 5+ threshold.
• user-guide/imports.md - use and include keyword reference; namespaced-call and aliasing rules.
• user-guide/types-and-values.md - convert.toInt / convert.toFloat example placement in the "explicit conversions" section.
• technical/rejected.md - "Methods on structs" (M14.3 trigger; recorded here in M10's wake because M10's review touched the same call-shape question) and other related rejected alternatives.

No new language features land here - that's M11.

#M11 - Control-flow completion

Closes the biggest daily-use gap in the language and rounds out the printf modifier table at the same time. Five new keywords (break, continue, repeat, until, exit) and two new printf features.

• break; / continue; in every loop kind (while/for/for-each/repeat). Innermost loop only; misuse outside a loop or across a method-call boundary is a positioned runtime error. continue in C-style for still runs the step before re-checking the condition (matches C/Go).
• repeat { } until (cond); post-test loop. New keywords repeat and until; do { } while ... considered and rejected because the inverted condition is the whole point of switching to until.
• exit; / exit EXPR; terminate the whole program (exit code 0 / EXPR-as-int). Distinct from return (method-scoped): skips every caller frame and remaining top-level statement. Implemented as an ExitSignal sentinel error the CLI translates into the OS exit status.
• Bundled: printf %s|align=center rounds out the align set. Rejected on every other typed verb (centred numbers break columnar output).
• Bundled: printf %a aggregate verb for lists and maps (deferred from M7; unblocked by M6 + M9). Modifiers: sep, kv, open, close, depth=N, null=skip. The modifier-list parser was extended with a "..." quoted-value form (%a|sep=", ") so values can contain spaces / reserved characters; standard \n \r \t \\ \" escapes.
• Post-dot name relaxation. Reserved words read as identifiers in the name slot of a qualified call (strings.repeat, lists.break if anyone wrote one), preserving the strings.repeat library function after repeat was reserved as a loop keyword.

See:

• user-guide/control-flow.md - repeat/until, break/continue scope rules, exit vs return.
• libraries/io.md - %a modifier table, %s|align=center example, quoted modifier values.
• technical/rejected.md - %a|json=* / %a|xml=* / %a|yaml=* (serialisation modifiers stayed rejected even after %a itself shipped) and the do { } while shape for the post-test loop.

#M12 - Bytes and bit operators

Adds the buffer-shaped primitive and the bit-twiddling vocabulary the standard library needs for hashing, encoding, crypto, and network code in later milestones.

• New primitive type bytes - mutable byte sequence; value semantics on assignment / parameter binding; deep-const. Reads yield int in [0, 255]; writes accept the same range and reject anything else. Append via the existing M9 $b[] = byte; sugar. len($b) returns the byte count.
• New convert.bytesFromString(s, codec) and convert.stringFromBytes(b, codec) - bytes ↔ string codecs. Only "utf-8" today (further codecs ship in M15.7 encoding). Invalid UTF-8 input is an error - no silent replacement characters.
• Bit operators on int: & | ^ ~ << >>. Python-style precedence (comparison < | < ^ < & < shifts < + -), so $x & 0xff == 0 parses as ($x & 0xff) == 0. ~ is bitwise NOT. Shifts are arithmetic; negative count rejected; count >= 64 saturates to 0 / -1. ^ ships as a primitive operator (CPU primitive with unique algebraic properties - same justification - has against being composable from + and unary -).
• Non-decimal integer literals: hex 0xff, octal 0o755, binary 0b1010_0110. _ accepted between digits in any base (including decimal 1_000_000 and float mantissas). Never adjacent to the prefix or another _. Lexer-only change.
• Resolves M7-deferred stdin builtins: io.readBytes(n) -> bytes (exact n; partial at EOF then io.eof() becomes true) and io.readChars(n) -> string (n runes, UTF-8 decoded). Both compose with M7's io.eof() unchanged.

See:

• user-guide/types-and-values.md - bytes type, value semantics, index-write rules.
• libraries/convert.md - codec functions, UTF-8 strictness.
• libraries/io.md - io.readBytes, io.readChars.
• user-guide/control-flow.md - bit-operator precedence table.
• user-guide/syntax.md - non-decimal literals + digit separator.

#M13-M13.2 - structs and catchable errors

The composite-data milestone, batched in dependency order: M13.1 ships the struct mechanism, M13.2 the recoverable-error story built on it (the canonical error value is a struct), together unblocking composite library returns. Design detail: git history, the user-guide (types-and-values, control-flow) and technical/interpreter.md docs, and examples/structs.j / examples/trycatch.j (plus the matching showcase.j sections).

#M14 - Lexer comment + blank-line preservation

Closes the two M5-deferred items (fmt drops comments, fmt drops blank lines). No language change - the runtime still never sees comments.

• Lexer emits trivia tokens (TOKEN_COMMENT_LINE, TOKEN_COMMENT_BLOCK, TOKEN_COMMENT_SHEBANG, TOKEN_BLANK_LINE). Shebang on line 1 col 1 is its own kind; runs of blank lines collapse to one.
• Preprocessor and parser strip trivia at entry; jennifer fmt walks the raw lexer stream and re-emits trivia via a dedicated emitTrivia path that doesn't disturb the surrounding state machine.
• Block comments nest via depth counter; unterminated comments error at the outermost /*.
• Token-level over AST-level: the original spec proposed AST-attached LeadingComments / TrailingComment slots and a jennifer ast --with-comments flag - dropped in favour of the simpler token-level path. Add them back if a future doc generator needs structured per-statement attachment.

See:

• user-guide/style-guide.md - Comments section (block comments nest; inline-comment spacing exception).
• technical/lexer.md - trivia emission, shebang detection, nesting depth counter.
• technical/cli_fmt.md - fmt's trivia re-emission.

#M15 - foundational libraries + first public release

Nine sub-milestones - two language (M15.2, M15.4), the rest library / tooling / release - that built out the foundational stdlib and shipped the first public release. Design detail: git history and the linked per-library docs. Two API patterns established here recur across later libraries:

• Codec-table shape - the algorithm / format / codec is a string argument (hash.compute(b, algo), crc.compute(b, algo), encoding.encode(s, codec), encoding.toText(b, format)), collapsing parallel verbs into one (stance #1) and sidestepping the letters-only identifier rule that rejects hash.md5(...).
• Integer-handle struct for opaque resources - a namespaced struct with a single id as int indexing a Go-side map (os.Process, hash.Stream, crc.Stream).

#M16 - I/O libraries and developer tooling

System libraries that touch the OS or do significant compute, opened by the spawn concurrency primitive (M16.0) the I/O libraries build on, then a lint / profile / test developer-tooling trio and a run of self-contained data libraries. Design detail: git history and the linked per-library / per-tool docs.

#M17 - module system for Jennifer-coded libraries

Jennifer-coded libraries get their own namespace, scope, and explicit exports via a real module boundary (import "x.j" as x;, a parser

• interpreter feature) beside the textual include "x.j"; splice (a preprocessor

operation for composing one module from several files). Settled cross-cutting decisions (turned-down alternatives in rejected.md): each module is its own resolution context (own use set, namespace + export tables); the module top level is declarations-only (no mutable state, so spawn capture is unaffected); the one global Error stands (modules add distinctly-named error structs, never redefine it); private by default, a leading export publishes (no public / private keyword); multi-file modules assemble via include behind one entry file (no directory-as-module); a module needs a filesystem (an FS-less jennifer-tiny host fails with the ordinary search-path error). Design detail: git history, imports.md, interpreter.md.

#M18 - Jennifer-coded modules

Built atop the existing system libraries. Each one ships as a Jennifer module under modules/ (the directory introduced in M17); none of them are compiled into the interpreter binary. Sub-milestones in priority order.

Forty sub-milestones (with their nested parts) shipped as pure-Jennifer modules/ (except where noted as a Go system library), each with the standard discipline: a 100%-passing *_test.j overlay, a cmd/jennifer/*_test.go integration test, a docs/modules/*.md reference, an examples/modules/*_demo.j, and catalog / README / JENNIFER.md entries. Per-function detail lives in docs/modules/; this table is the milestone-number index (numbers were assigned in rough priority order).

Enabling changes these modules pulled into the system side (each documented under its library):

• net.setDeadline - a read/write deadline for socket timeouts (M18.13; later extended to UDP sockets for ntp, M18.27).
• io.eprintf - the stdout-printf twin that writes to stderr (a new Interpreter.Err / BuiltinCtx.Err writer), the stderr sink log builds on (M18.22).
• toml and httpd - two new Go system libraries (a char-by-char TOML parser and a net/http server engine both belong in Go, not a .j module); M18.8 / M18.9.1.
• meta.callMain / meta.definedMain - resolve a method against the entry program (retagging module-own struct args across the boundary), the capability the web framework dispatches handlers through (M18.9.2).
• hash.hmac (RFC 2104) and the sha512 digest - the HMAC primitive totp / webhook build on (and that jwt / SigV4 will reuse).

#M19 - cross-cutting tooling

The catch-all bucket for interpreter / tooling work belonging to neither the M18 .j modules nor the M20 Go system libraries: M19.1-M19.5 a correctness / performance hardening pass over the core + libraries; M19.6 the coverage tool; M19.7 the @scope/package vendored-module resolver; M19.8 the one-time org / vanity-path relocation; M19.9 the audit-driven hardening pass. No reflect, no TinyGo-cleanliness break. Design detail: git history and the linked docs.

#M20 - system libraries

Go system libraries (cryptographic primitives, plus formats too heavy or too reflect-bound for a Jennifer-coded .j module - the json pattern, M16.9), plus two cleanup keywords (defer / errdefer) and Unix-signal support that the libraries needed. Ten sub-milestones, each shipped with the standard discipline: a cmd/jennifer / *_test.go suite, a docs/libraries/*.md reference, cheatsheet + JENNIFER.md entries, and a runnable example. Per-function detail lives in docs/libraries/; this table is the milestone-number index.

Cross-cutting additions these pulled into the language / system side (each documented under its library):

• defer / errdefer (M20.7) - the deterministic-cleanup keywords; the finally rejection and the printf-for-translation rejection (M20.4) are recorded in rejected.md.
• fs.sync (M20.7) - fsync a write / append handle to the device, distinct from close's reach-the-OS: durability you check, versus cleanup you defer.
• sha384 / sha512 (M20.10) - the SHA-2 digests filled out across hash.compute / hmac / streaming; MD5 / SHA-1 stay checksum-only.
• The nesting cap (internal/limits.MaxNestingDepth) shared by the language parser and the json / toml / xml decoders - build-tag split so it stays below jennifer-tiny's fixed-stack crash point (see technical/tinygo.md).
• The SIGUSR1 diagnostics checkpoint hook (M20.6) - the loop-iteration / call checkpoint the deferred cooperative loop-cancellation follow-on (interruptible loops, REPL Ctrl-C, terminating-signal terminal restore) builds on.

#M21 - general backlog

The catch-all bucket: milestones that fit no other track - not a Jennifer-coded module (M18), not interpreter / tooling work (M19), not a Go system library (M20), and not a beyond-1.0.0 idea (those live in the horizon collection). Anything worth recording with no natural home landed here, and graduated out once a cluster grew big enough to earn its own bucket. Thirteen sub-milestones across Jennifer-coded modules, security hardening, interpreter / language work, byte throughput, and Windows packaging. Each shipped module carries the standard discipline (a 100%-passing *_test.j overlay, a cmd/jennifer/*_test.go integration test, docs/modules/*.md + catalog + JENNIFER.md entries, a runnable demo); per-item detail lives in those docs - this table is the milestone-number index.

Cross-cutting threads:

• The crypto asymmetric surface grew here, not in M20: M21.3 added rsaSign / rsaVerify / ecdsaSign / ecdsaVerify (PEM; PKCS#1 v1.5 / JOSE R||S) for JWT interop, and M21.4 added rsaGenerateKey / ecGenerateKey / jwkPublic / csr for ACME - all build-tag split off the TinyGo build (crypto/x509 is absent there), so the asymmetric verbs are default-binary only while the symmetric primitives and Ed25519 stay on both.
• A 64 MiB received-data cap became the standard DoS guard across the network clients (http / redis / pop / imap / mqtt / websocket, in M21.2 / M21.7 / M21.9), so an attacker-declared length or an unbounded stream fails catchably instead of OOMing.
• Not all of M21 is modules. M21.8 / M21.11 / M21.12 are interpreter and language work (the call-depth guard, range syntax, the allocation model), M21.10 is the throughput library, and M21.13 is packaging - which is exactly why this bucket is the general catch-all rather than an M18 module run.
• The sql list-spread (M21.5) - toDriverArgs spreading a single list argument into the placeholder sequence - is the one small language-adjacent enabler this track pulled in, for runtime-shaped parameterized queries.

#M22 - additional libraries and language refinements

Post-backlog work belonging to neither the M20 system-library set nor the M21 catch-all: focused standard-library and .j-module additions or enhancements, plus small language cleanups, each landing when the need was concrete. Eighteen sub-milestones. Each shipped with the standard discipline (a library adds a Go package + internal/stdlib.InstallAll line + docs/libraries/ reference + cheatsheet rows; a .j module ships a 100%-passing *_test.j overlay + a cmd/jennifer/*_test.go integration test + docs/modules/ doc + catalog + JENNIFER.md bullet + a demo; a language feature updates the spec + grammar EBNF/PEG + the editor highlighters). Per-item surface detail lives in those docs; this table is the milestone-number index.

#M23 - module improvements

Done. M22 lifted a handful of modules (imap, http); M23 generalized that across the module ecosystem. A survey of all 63 .j modules found the gaps cluster into cross-cutting themes rather than scattering per module, so the work was organized by theme - a shared pattern (a receive loop, a persistent connection, a backend selector) built once and applied to every module that needs it. Fifteen sub-milestones. Each shipped the standard per-module discipline (a 100%-passing *_test.j overlay, a cmd/jennifer/*_test.go integration test where a live server applies, docs/modules/ + catalog + JENNIFER.md entries, a demo, both binaries build); per-item surface detail lives in those docs, and the biggest sub-milestones keep their own reference docs. This table is the milestone-number index. Deliberate non-goals: password hashing (needs x/crypto) and fully-typed orm rows (awaits struct reflection).

Cross-cutting threads:

• Not all of M23 is modules. M23.9 (fmt), M23.10 (os.run stdin), and M23.14 (raw single-quoted strings) are tooling / interpreter / language work; the rest is the module ecosystem.
• Build once, apply everywhere was the payoff of organizing by theme: a shared receive-loop shape (M23.1) and a shared backend selector (the kv library + kvstore enum, M23.5), each built once and threaded through every module that needs it.
• match / enum (M22.4 / M22.5) landed across the ecosystem in M23.12, and the largest sub-milestone - M23.15's orm + the new sqlmigrate - is a full batteries-included ORM in its own right.

#M24 - language, concurrency, and libraries

Done. The first batch of horizon drafts graduated into a scheduled track, then grew into the broadest single milestone: a CLI ergonomic, the language's biggest expressiveness feature (first-class functions), a concurrency-coordination layer, a numeric / ML library stack, two ASN.1 protocol clients, and a run of library / language refinements. Twenty-three sub-milestones. Each shipped with the standard discipline - spec + grammar EBNF/PEG + editor highlighters where a language feature lands; a Go package + internal/stdlib.InstallAll line + docs/libraries/ reference + cheatsheet where a library lands; a 100%-passing *_test.j overlay + cmd/jennifer/*_test.go + docs/modules/ + catalog + JENNIFER.md + demo where a .j module lands; both binaries build; the full test close-out. Per-item surface detail lives in those docs - this table is the milestone-number index.

Cross-cutting threads:

• Graduated horizon drafts. M24 drained the first scheduled batch from the horizon collection: DRAFT#26 (M24.1 --env), DRAFT#18 (M24.2 first-class functions), DRAFT#21 (M24.3 concurrency coordination), DRAFT#5 (M24.4 stats), and DRAFT#13 (M24.21 Markdown -> PDF), plus the string-interpolation entry (M24.19).
• A numeric / statistical stack landed together: stats (M24.4) + linalg (M24.6) + ml (M24.5) + the math special functions (M24.10) + the distributions / inference layer folded back into stats (M24.11) - each strict (an undefined result is a catchable error, never a NaN) and bounded by a materialised-value cap.
• An ASN.1 protocol stack: the hand-rolled asn1 byte layer (M24.7) enabled the snmp (M24.8) and ldap (M24.9) clients-and-servers, each factoring its codec pure so the overlay round-trips without a socket.
• Consistency across the format modules. The html rebrand + parser (M24.17) and the markdown reader (M24.18) gave both modules the same build-and-parse Node model as xml / json, which M24.21's toPdf then consumed.
• Not all of M24 is libraries. M24.2 (first-class functions), M24.3 (cancellation / channels), M24.12 (scientific-notation literals), and M24.19 (string interpolation) are language / interpreter work; M24.1 is a CLI flag; M24.16 / M24.20 are a cross-suite hardening pass and a read-time guard.

#M25 - read-only-parameter borrow (compound copy elision)

Parameter binding deep-copies compound arguments (list, map, struct) to uphold value semantics. When the callee never writes the parameter - no $p = ..., $p[i] = ..., $p[] = ..., $p.f = ... anywhere in its body - that copy is pure waste: a read-only alias to the caller's backing is observationally identical to a copy, so the parameter can be bound by alias. This is the standard value-semantic-language optimization (the "borrow" half of copy-on-write), narrower and more clearly sound than the shared-marker COW that was tried and reverted as inert (see technical/rejected.md): it never detaches-on-write, because a borrowed parameter is by construction never written. No .j changes and no new syntax - a pure interpreter optimization. Split into the borrow itself (M25.1) and the escape analysis that widens where it is sound (M25.2). Independent of the horizon bytecode-VM direction but composes with it.

#M25.1 - borrow in modules and globals-free scripts

Done. The borrow, enabled in the two contexts where it is sound without a whole-program analysis.

• The soundness subtlety. "Never writes the parameter" alone is not sufficient: if the argument aliases a mutable global and the body mutates that global, a borrowed read observes the mutation where a copy would not (def g ...; func f(p) { $g[0] = 9; return $p[0]; } f($g)). The synchronous call model rules out the caller changing the backing mid-call, but not the callee changing it through a global alias. Borrow is therefore enabled only where no mutable global can exist to alias: (a) a module, whose top level is declarations-only (and whose cross-boundary arguments are copies anyway); and (b) a single-file script that declares no mutable top-level def - checked once by hasMutableTopLevelGlobal, so a script's own read-only helpers benefit without being moved into a module. A script with a mutable global keeps the copying bind (M25.2 is what lifts that).
• Mechanism. Extends the existing scalar copy-elision in bindParamValue to compound Kinds - the "mutation-safety proof" that elision path was documented as requiring. Resolve runs markBorrowableParams per method: a statement-level write-scan of the body (through nested control flow; no-shadowing makes a written name unambiguously the parameter; spawn bodies mutate their own snapshot so are correctly skipped) sets Param.Borrow when the parameter is never written and its type is borrow-safe - a compound whose stampDeclaredType does not recurse into element backing (a flat list/map, or a struct/bytes; a list of list falls back to copy so the stamp can't mutate the shared backing). Interpreter.bindArg aliases when Param.Borrow && (i.isModule || i.entryGlobalsImmutable), else copies as before.
• What it buys. It removes a class of accidental quadratics transparently. The markdown block collectors (collectFence / collectQuote / collectList / tableFrom, all lines as list of string) deep-copied the whole line list once per block (lines x blocks); parsing a 160-chapter synthetic book as one document drops from 5.1 s to 0.85 s and turns from super-linear (2.9x per input doubling) to linear (2.0x). The countNodes budget walk borrows its Node argument, and a globals-free script's own read-only helpers go linear the same way. The .j-level workaround does not pay off: a count-during-construction rewrite of the countNodes guard measured a wash (9.5 s vs 9.6 s on a 100k-node document), because eliminating the read-only walk forces threading the count back through the builders, re-introducing an equal volume of copies. No reference-semantic handle a pure .j module can hang a large list on exists, so the copy is only removable below the language.
• Discipline. TinyGo-clean, reflect-free, strict behaviour parity, race-clean. internal/parser/borrow_test.go pins the write-scan and type gate (a false positive would alias a mutated parameter); internal/interpreter/borrow_test.go and borrow_internal_test.go pin the soundness gate (a script with a mutable global keeps copy semantics; a globals-free script and a module borrow) and the value-semantics parity (borrowed reads correct, caller values intact, returned borrows copied at the receiver).

#M25.2 - per-function escape analysis for scripts with mutable globals

Done. M25.1 gates a whole script all-or-nothing on "does it declare any mutable top-level global". M25.2 adds a per-function decision on top: borrow a never-written parameter in any method proven not to mutate a global transitively, even in a script that has mutable globals elsewhere.

• The analysis (computeEntryGlobalSafe, run after module load so the module-alias and namespace tables exist). Each entry-program method is scanned for a local hazard, then a fixpoint propagates it along named-call edges (CallExpr.Method), so a method that reaches a hazardous method is itself hazardous. A local hazard is: a write whose root is not a method-local name (a mutable global write - a const target is already rejected, so any non-local write hits a mutable global); a CallValueExpr (dynamic func-value dispatch); a module call (a module can re-enter the host via meta.callMain and reach a host global write); a callback builtin (the higher-order lists layer, which invokes a func-value argument, and the by-name dispatchers meta.call / meta.callMain / testing.run / runWith / assertThrows - keyed by canonical namespace, so an aliased use lists as l is caught); or an unresolved bare call. The walker defaults an unrecognised node to hazardous, so a new AST node never silently escapes. spawn bodies are skipped (they mutate a deep-copied snapshot, not the live globals). A method with no hazard is stamped MethodDef.GlobalSafe, and methodBorrowCtx widens the bind gate to i.isModule || i.entryGlobalsImmutable || m.GlobalSafe.
• Why callback builtins are a denylist. A func value is a ConstRefExpr at the AST level (indistinguishable from a constant), and func values also arrive through func-typed variables and untyped curried returns (makeAdder(1) - methods declare no return type), so a func-value argument cannot be spotted statically. The sound alternative is to name the builtins that can invoke .j code (via BuiltinCtx.Invoke or CallByName* / CallHostWith*). The invariant Conservative by construction: a script function that calls a module or uses a func value does not borrow (M25.1 still covers it when the script is globals-free or the call is into a module, whose own helpers borrow via isModule).
  • any such builtin must be listed - lives beside the set in globalsafe.go.
• What it buys. A read-only helper in a script that holds mutable globals goes linear: a per-element peek(xs, i) scanned over a growing list drops from quadratic to linear once peek/scan are proven GlobalSafe.
• Discipline. internal/interpreter/globalsafe_internal_test.go pins the flag (pure / direct-write / index+append-write / nested-block / transitive / mutual recursion / cycle-reaching-a-writer / function-value-call); borrow_test.go pins the value-semantics soundness end to end (direct, transitive-via-callee, meta.call, and lists.map global mutations all keep copy semantics; a GlobalSafe helper in a mutable-globals script borrows correctly). Race-clean.

#M26 - jvc package manager (decks)

Planned. The package manager for Jennifer and its distribution: the tool itself (M26.1), shipping a known-good copy inside every interpreter release (M26.2), gating that release on jvc's own test suite (M26.3), and the lockfile forward-compatibility guard the two programs need once the interpreter reads jvc's output (M26.4).

#M26.1 - the package manager itself

Planned. A package manager for Jennifer, in the shape of PHP's Composer (or Rust's Cargo): declare dependencies in a manifest, jvc install resolves and fetches them, and the app imports what it pulled. Installing an app becomes git clone + jvc install, and jvc update advances within the declared constraints.

• Packages are "decks". A deck is a distributable, versioned bundle of .j modules, published to a public deck repository / registry (provided later) that jvc resolves and fetches from - packagist-style; a deck can also come straight from a git URL.
• Naming conventions. A deck has two separate identities. Its canonical name is the @vendor/deckname scope in deck.toml (what imports and jvc key on) - kept clean, with no "deck" word: an official deck is @jennifer/routeros, imported import "@jennifer/routeros/"; -> routeros.*. Its GitHub repo name is cosmetic (jvc reads deck.toml, not the repo name), so the "deck" marker lives there and only there:
  • Official decks (in the jennifer-language org) use a deck- prefix - jennifer-language/deck-routeros. The prefix is the "not core, but official deck" statement: it clusters the decks and keeps the org's top level readable (core jennifer / homebrew-tap vs deck-*). The org already supplies "jennifer", so deck- is the useful signal (deck vs core).
  • Community decks (any account) can be named anything - jvc only needs it configured - but the suggested form is a jennifer- prefix, alice/jennifer-routeros: on a personal account there is no Jennifer namespace, so "which ecosystem" is the useful signal instead.
  • All deck repos carry the GitHub topic jennifer-deck for discovery, which works regardless of the repo name.
• Installed into the vendor/ tree M19.7 resolves. jvc writes decks into the project-local vendor/ tree that the interpreter already addresses through the @scope/package import form and vendor-root discovery shipped in M19.7 - so a hand-populated vendor/ imports before jvc exists, and jvc is just the manager layered over that resolver. Nothing is global; each app owns its decks beside it.
• The one remaining language-surface question: inline version selectors. M19.7 resolves import "@jennifer/supercms/" as cms; (the trailing / expands to the package-named entry supercms/supercms.j) against whatever is installed. jvc supplies the default - plain import @jennifer/supercms; takes the version jvc resolved (declared in deck.toml, pinned in the lockfile), version-transparent, which is what almost every script wants. The opt-in for side-by-side versions is a per-import selector matched against the installed set (never triggering a fetch): @jennifer/supercms=1.2.3 (exact), >=1.2.3 / ~ / ^ (a semver constraint over what is installed), or #cefa234 (a git commit); one script can pin =1.x while another pins =2.x, and two versions in one file take distinct as aliases. An unsatisfiable selector errors pointing at jvc install, not a silent download. Cost: the selector is new grammar (the lexer reads @vendor/deck + semver op + #commit as one token up to ;); the plain M19.7 string-path form is the no-new-grammar fallback that loses only the inline selector.
• deck.toml manifest + lockfile. deck.toml (TOML, so it needs the toml library) declares required decks and constraints (bitcoin = ">=1.2.0"), and jvc produces a camcorder.lock pinning exact resolved versions (content hash per deck) so git clone + jvc install is reproducible. Dependency sets split by section ([prod] / [dev], jvc install --prod), with a taxative (the section is the exact set) vs additive (base plus the section's extras) mode still to design.
• jvc owns the lifecycle: dependency resolution (semver constraint solving across the graph), downloading, jvc update (advance to the newest constraint-satisfying versions, rewrite camcorder.lock), integrity pinning, and the publish flow to the registry.

Migrating bundled modules out to decks. Once decks exist, niche or product-specific modules that ship bundled today should graduate out into decks (the archetype is gotify - a single-product push integration every install need not carry); language-fundamental modules stay bundled. Moving one changes its import, so it is a breaking change under semver: within 1.x ship it both ways (bundled + @-deck) with the bundled copy marked @deprecated so imports re-point at their own pace, let the two drift without breaking, and remove the bundled copy in 2.0.0. Conversely, new third-party service integrations ship as decks from the start rather than as core modules (core stays general primitives; specific-vendor clients live in the ecosystem) - the M27 candidate-deck ecosystem collects the list (GitLab, GitHub, Steam, TheMovieDB, Jellyfin, Frigate, RouterOS, ...).

Requires: the public deck registry (separate infrastructure, provided later); its language-side prerequisites - the @scope/package resolver + vendor root (M19.7), toml, the module system, and semver's range surface - have shipped.

#M26.2 - bundle jvc in tagged releases

Planned. Ship a known-good jvc inside every tagged jennifer release, so install Jennifer yields a working deck manager with no second step, while jvc app install can still shadow the bundled copy for anyone who needs a fix ahead of the next language release (the bundled copy is then the rescue path if a self-installed jvc breaks). jvc is Jennifer source (.j files, ~17 modules, no build step, no per-platform artifact), so bundling is copying text - but it uses http / os.run / archive, so it runs on the default jennifer binary only; jennifer-tiny (no net / exec) does not carry it, and the launcher must exec jennifer, never the tiny build.

• Vendored copy, pinned to a commit. The jvc source is vendored into the jennifer tree (a sync script refreshes it) with a CI check that the copy matches a pinned jvc commit SHA - a commit, never a branch or a tag, since a tag is a mutable pointer (the same rule the deck resolver applies to git-sourced decks). A git submodule is the alternative if keeping upstream canonical and the pin visible in git log outweighs the --recursive friction. Fetch-at-build is rejected (a release build must stay offline / air-gapped, and packagers dislike network); a separate companion tarball is rejected (it leaves a fresh install with no jvc, so it does not meet the goal).
• Install as source, beside the bundled modules. $PREFIX/share/jennifer/jvc/ holds jvc's cli/*.j, and $PREFIX/bin/jvc is a one-line launcher (exec jennifer run $PREFIX/share/jennifer/jvc/cli/jvc.j "$@"), threaded through the .deb / OCI image / tarball / Homebrew packaging the same way the system modules already are. The shippable set is the clean cli/ directory once jvc moves its registry-writing publish path off the server/ maintenance verbs (a client CLI should not bundle the registry server's admin code); until then it is cli/*.j plus server/{store,admin}.j.
• Report the pair in jennifer version. jennifer 0.25.0 (jvc 0.3.0), so a bug report names both halves. The jvc pin is stamped at build time through the version codegen path (gen-version.sh -> internal/version/version_gen.go), not -ldflags -X, which TinyGo silently ignores (implementation-note 7). jvc's own jvc version stays the authority on which copy is running vs installed (PATH order decides silently; its provenance report is the mitigation for that and for a ~/.local/bin shadow).

Requires: M26.1 (a taggable jvc to pin). Do not bundle ahead of it.

#M26.3 - jvc suite as a release gate

Planned. Run jvc's test overlays against the release-candidate interpreter in release.yml; a red suite blocks the tag. jvc is the language's most complete integration test - its assertions exercise toml / json / semver / archive / http / fs / os / path / hash / encoding / convert / strings / lists / maps / docblock / flatdb, git through exec, and the module system itself (cross-module struct identity, the @vendor resolver, the capability pragmas), so a change that breaks the language's own package manager cannot ship. This gate is what makes bundling valuable rather than merely convenient.

• jvc is a first-class caller. The gate fits the existing breaking-change discipline (one batch updates a library, its overlays, docs, and every caller): jvc becomes another caller updated in the same batch. An unintended break is a hard red caught in the language CI instead of jvc's; an intended break (a pre-1.0 milestone is free to make one) is handled by advancing the pinned jvc commit to a version already green against the RC, in that same batch - the gate passes because the pin moved, not because anything reverted.
• The pin policy is written, not implicit. A release pins a jvc commit known-green against that RC. An intended interpreter break requires a compatible jvc commit to exist before the tag; if jvc cannot keep up, the release waits or holds the pin back and documents the incompatibility. The language cut thereby depends on jvc being green - an acceptable reverse dependency for one maintainer who owns both repositories, named here so it is a deliberate choice.

Requires: M26.2 (a pinned, bundled jvc) and jvc's overlay suite. The two recent breaks it would have caught - cooked-string {expr} interpolation turning embedded JSON literals into lex errors, and the fmt / lint line-width disagreement (fmt not counting a trailing {) - motivate it; the latter is already fixed in the tree, which the gate would confirm ships.

#M26.4 - lockfile forward-compatibility guard (design-open)

Planned. Once the interpreter's vendor resolver reads jvc's camcorder.lock at import time, a newer jvc can write a lockfileVersion the bundled resolver predates. The forward-compat rule both sides agree on: the interpreter refuses an unknown lockfileVersion with a clear message rather than misreading it, settled before the first jvc that changes the format ships.

• Open design question, deliberately deferred. Nothing in internal/ reads camcorder.lock today; the lockfile contract is spec, not code. Whether the core resolver should parse jvc's lockfile [engines] at all is unsettled - the interpreter already enforces version floors per file via the # pragma-jennifer-version: header and exposes meta.CAPABILITIES, so engine-floor enforcement may stay jvc's job and the interpreter's only lockfile duty be the lockfileVersion refusal above. Enforcing package-manager policy in the core resolver runs against the minimal-core stance, so this is resolved when M26.1's resolver work is designed, not as part of bundling.

Requires: M26.1 (the lockfile format and the resolver that would read it).

#M27 - candidate decks (deck ecosystem)

Planned. A running parking lot of deck ideas - third-party service and integration clients that, once jvc / decks (M26) land, ship as decks rather than core modules/. The rule: core stays general primitives (protocols, formats, infrastructure - http, graphql, csv); a client for one specific vendor or service lives in the ecosystem as a deck (independently versioned, community-maintainable, so vendor API churn never touches the core). This list is demand-driven and open-ended, a collection not a commitment.

Most are thin clients over http / rest + json (plus xml where a vendor returns XML, and the graphql module where the API is GraphQL). Each is a login / token step, a generic call(path, params) -> json.Value, and a handful of conveniences; a fat typed wrapper is explicitly not the plan - these APIs are enormous and firmware-versioned, so a thin client ages far better.

#M27.1 - self-hosted infrastructure

A LAN appliance, usually a self-signed cert. Per-vendor maturity differs and should set the order, not the vendor:

• routeros - a full RouterOS abstraction layer (MikroTik), well beyond the small bundled mikrotik.j API client. Already in progress; the likely first published deck.
• proxmox - Proxmox VE: documented REST / JSON, API-token header auth (PVEAPIToken=...). Clean.
• vmware - vCenter / vSphere (vCSA): the vSphere Automation REST API (JSON, session auth), clean and tractable like Proxmox. A standalone ESXi host is the messier case - historically only the SOAP / VMOMI Web Services API (XML / SOAP, heavier), with just partial REST on 8.x - so vCenter is the target, a bare ESXi host best-effort.
• synology - DSM: the cleanest NAS API - a documented Web API (SYNO.API.Auth login -> session sid, JSON responses).
• unraid - the newer official API is GraphQL over HTTP with an API key.
• qnap - QTS: the messiest - much of the useful surface is undocumented, reverse-engineered CGI with XML responses and a legacy hashed-password auth; firmware-fragile and hard to keep green. Lowest priority, on real need only.
• ugreen - NASync / UGOS Pro: no official API - only the internal token-based API the web GUI uses (log in for a token, then GET), reverse- engineered by the community (a working Home Assistant integration exists). Same keep-green risk as qnap; UGOS is new and evolving, so revisit if UGREEN ever ships official docs.
• jellyfin - the self-hosted media server's REST API (API-key / token auth).
• frigate - the Frigate NVR REST API (events / config / recordings), often paired with its MQTT feed (the mqtt module).

#M27.2 - public / SaaS APIs

• gitlab / github - dev-platform clients; both expose REST and GraphQL, token auth.
• steam - the Steam Web API (JSON, ?key= auth); parts of the surface are community-reverse-engineered, which is exactly why it belongs in a deck, not core.
• themoviedb - TMDB's clean, well-documented REST JSON API (bearer / key auth).

#M27.3 - daily helpers

A grab-bag of small, everyday helper decks - the little utilities a script reaches for often, each a tiny pure-.j deck.

• cli spinners - a small deck of terminal progress spinners for a long-running task: a catalogue of spinner styles (dots / line / bar / braille / arc / ...), each individually colourable (through ansi) and driven at its own speed (frame interval). Self-suppresses when stdout is not a TTY (os.isTerminal), so piped output stays clean.

#M27.4 - bioinformatics

A sequence-manipulation deck for DNA / RNA / protein, modelled on the Sequence Manipulation Suite (SMS) tool catalogue - the classic, comprehensive reference for this surface. Almost all of it is pure string / list / map work, so it is a natural pure-.j deck (leaning on strings, regex, lists, maps, math, and stats, no Go), dogfooding the language and community-maintainable as tables and algorithms are added. Grouped SMS-style:

• Transforms - complement, reverseComplement, reverse, transcribe (DNA <-> RNA), translate (codon table), six-frame translation, splitCodons, amino-acid oneToThree / threeToOne.
• Composition & properties - gcContent, base / amino-acid composition, dnaStats / proteinStats summaries, molecularWeight (DNA / RNA / protein), meltingTemp (Wallace + nearest-neighbour), isoelectricPoint (pI), gravy (hydropathy), codonUsage. The thermodynamic / pI / nearest-neighbour formulas want exp / ln / log, so they pull in M24.10 (math foundations).
• Search - exact and IUPAC-ambiguity pattern find (via regex character classes), fuzzy search (n mismatches), ORF finder (six frames), CpG islands, restriction-site search and restrictionDigest (fragments) over a bundled enzyme table.
• Formats - FASTA parse / write (a Record{id, description, sequence} list), FASTQ reads (sequence + quality), format conversion, filterDna / filterProtein (strip non-sequence characters).
• Manipulation - randomDna / randomProtein (length + optional composition), composition-preserving shuffle, point mutate (rate), range / sliding-window extraction.
• Comparison - pairwise alignGlobal (Needleman-Wunsch) / alignLocal (Smith-Waterman) with percent identity / similarity, plus hammingDistance / editDistance. Alignment is the one O(nm) hot loop - fine in .j for the small sequences a deck user handles; a candidate Go primitive only if whole-genome throughput is ever needed.
• Reference data - the standard genetic code + alternative codon tables, IUPAC ambiguity codes, per-residue property tables (MW / pKa / hydropathy), and a common-enzyme table - all plain .j maps a community can extend.

FASTA / FASTQ I/O and alignment cover the "molecule structures" the original note gestured at; PDB / 3-D structure parsing stays out of v1 (a much larger, separate effort).

#M27.5 - forensic / statistical genetics

The statistical-genetics sibling of the sequence deck (M27.4): it works on profiles (an unordered allele pair per autosomal STR locus, plus uniparental haplotypes for mtDNA / Y-STR) and reference frequency / count data, not on sequences, so it shares no code and no audience with SMS. Pure .j (probability arithmetic over allele-frequency maps, no Go, TinyGo-clean), leaning on math and on xml / text parsing to ingest a published frequency table.

• Match probabilities - Hardy-Weinberg single-locus genotype frequencies (homozygote p^2, heterozygote 2 pa pb), with the NRC II theta / Fst sub-population correction (Balding-Nichols), multiplied across loci: randomMatchProbability (RMP), the single-source match LR = 1 / RMP, and cpi / cpe (combined probability of inclusion / exclusion) for mixtures. A minimum-allele-frequency floor (5 / 2N, so the table keeps each locus's N) handles rare or unobserved alleles.
• Lineage markers (mtDNA / Y-STR) - mitochondrial and Y-chromosome markers are haploid, non-recombining, and uniparentally inherited, so match probability is not Hardy-Weinberg but a direct haplotype count: frequency k / N in a reference database, with a Clopper-Pearson exact-binomial upper bound as the conservative estimate (which pulls in the beta distribution M24.11 adds to stats). Deliberately database-independent, so the deck supplies the estimator (haplotypeFrequency(k, N) / lineageMatchProbability) and the caller feeds the count from whatever database they queried. mtDNA adds a haplotype coded as differences from the rCRS (e.g. 263G 315.1C) plus the substantive align step that renders a raw sequence into that standard nomenclature; Y-STR is a per-locus repeat-count vector with exact / single-step comparison.
• Kinship likelihood ratios - relationships encoded as IBD coefficients (kappa0 / kappa1 / kappa2: parent-child (0, 1, 0), full sibs (1/4, 1/2, 1/4), half-sib / avuncular / grandparent (1/2, 1/2, 0), first cousins (3/4, 1/4, 0), ...). kinshipLR(a, b, relationship, db) tests one relationship against another; paternityIndex(mother, child, allegedFather, db) gives a combined paternity index (CPI) and probabilityOfPaternity (W = CPI / (CPI + 1)), with a stepwise STR mutation model to survive a lone inconsistency. General pedigrees (beyond pairs / trios) need a peeling engine - Elston-Stewart - the one substantial algorithm, the Familias / forrel-style capability.

Mixture deconvolution (multi-contributor, drop-in / drop-out - the EuroForMix space) is a larger, later effort layered on this base.

A concrete frequency source to wire in first, as a sample: the ENFSI STR reference database STRidER - a loadFrequencies(xml, "strider") over the xml library, with its formulae page and online calculator as the exact-conventions spec and a validation target.

#M27.6 - NGS / high-throughput sequencing

Unlike the pure-.j decks above, NGS breaks the model on two axes - scale (FASTQ.gz files run 10s of GB, BAM 100s, so everything streams, never load-into-memory) and compute (alignment / assembly / variant calling are heavily SIMD-optimised C a tree-walker is ~100-1000x too slow to replace). So the deck is deliberately the glue and light-I/O layer, not the heavy engine, with a different posture from the pure-.j decks: Go-backed streaming parsers (the decompress-and-parse hot loop in Go, the net.readAll / binary pattern) with the per-record logic in .j. In scope:

• Streaming format I/O - FASTQ (gzipped, over compress + fs handles) and the tab-delimited SAM / VCF / BED / GFF / GTF text formats: parse / filter / convert as a stream, so a 50 GB file never lands in memory.
• QC + preprocessing (FastQC / fastp-lite) - per-base quality and read-length / GC distributions, adapter detection, quality / adapter trimming, length filtering, subsampling: one streaming pass over FASTQ.
• Interval ops (bedtools-lite) - overlap / intersect / merge over BED / GFF features.
• Pipeline orchestration - the real sweet spot: NGS is fundamentally bwa | samtools | gatk glued together, and Jennifer already has os.run / os.spawn + spawn concurrency, so it can drive the standard tools, parse their output, manage intermediate files, fan out over samples in parallel, and handle errors - a Snakemake-lite in a real language.

Out of scope (wrap and pipe the native tool, do not reimplement): read alignment (BWA / Bowtie2 / minimap2), de-novo assembly (SPAdes), variant calling (GATK), and heavy BAM / CRAM handling - which additionally needs BGZF (blocked gzip for random access), a compress gap and a Go addition whose standalone value is limited without the downstream compute the deck omits.

#M28 - multiplatform: promote macOS / Windows to supported

Linux is the only supported platform, but best-effort unsupported macOS / Windows binaries (the standard-Go jennifer, via cross-compile) already ship each release - so the work is not "add the ports" but promoting them to supported, which graduates the "cross-build for macOS / Windows" 1.0.0 distribution requirement. A portability audit found the surface small: separators / EOL / $HOME / temp are already runtime.GOOS-derived (internal/lib/os/oslib.go), os/exec keys on runtime.Compiler != "tinygo" (not GOOS, so it is enabled on Windows), and signals + the four Linux-only hardware libs (serial / spi / i2c / gpio) stub cleanly on non-Linux (*_other.go). Extra distribution packaging (a Homebrew tap, Snap, Nix flake, Flatpak / AppImage) stays a per-format nice-to-have, shipped only when a user asks and a maintainer keeps it green - none blocks a release.

#M28.1 - Windows: promote to supported

Planned. The Windows track is a handful of concrete gaps, not a rewrite:

• Exe-relative module default. compileDefaultSysmoddir bakes one hardcoded POSIX path (/usr/share/jennifer/modules, internal/module/sysmoddir.go) into a Windows binary; give it a Windows-native, exe-relative default (<dir(os.Executable())>\share\jennifer\modules) via a build-tag split (sysmoddir_windows.go / _unix.go), so a portable-zip user's import "name.j"; resolves with no env var (the M21.13 installer's JENNIFER_SYSMODDIR stays the explicit override; precedence unchanged).
• Per-OS golden strategy. examples/expected/osinfo.txt is the sole platform-pinned golden (pins linux / amd64 / / / :, compared byte-exact in cmd/jennifer/examples_test.go); add per-OS expected-file selection or a runtime.GOOS-gated skip for the osinfo canary (already flagged at examples/osinfo.j).
• fs.chmod / fs.chown on Windows. Define the Windows behaviour (a friendly catchable error is acceptable; the chown test is already Linux-gated), and document that signal-based graceful shutdown is limited on Windows (signal_other.go stubs os.catchSignal).
• A windows-latest CI test job running go test ./... so Windows correctness is actually verified (the exec suite self-skips off Linux; the osinfo golden is the known failure the item above resolves); once green, move windows/amd64 out of the build-unsupported matrix into the supported set and drop the "unsupported" labelling for that arch.

Requires: none.

#M28.2 - macOS: promote to supported

Planned. The parallel case: the same "already ships unsupported, promote it" shape as M28.1, and simpler - macOS lacks even the module-path blocker Windows has (the POSIX exe-relative default resolves cleanly), and its separators / EOL / $HOME match Linux. A macos-latest CI test job running go test ./... verifies correctness (reusing the per-OS osinfo golden strategy from M28.1); once green, move darwin/amd64 + darwin/arm64 out of the build-unsupported matrix into the supported set and drop the "unsupported" labelling. Requires: none.

#M29 - project governance, licensing, and contribution policy

Planned. A hard requirement for 1.0.0 stable (also listed under Requirements for 1.0.0 stable). The rules for how the project is run and how outside contributions are taken - organizational, not code. Untouched while the project is solo (one author, Copyright (C) 2026 mplx <jennifer@mplx.dev>, LGPL-3.0-only, no outside PRs), but it must be settled before the first external contribution is merged: several of the choices are hard to reverse once other people's copyrightable work is in the tree. The open questions, roughly by urgency:

• Copyright-holder model. Under distributed copyright (the default, no paperwork) every non-trivial contributor automatically holds copyright in their patch, so the tree becomes a mosaic of holders and any future relicensing needs each one's agreement. The alternatives are a CLA (contributor grants the project a broad license, keeps their own copyright) or an assignment / CAA (contributor transfers copyright to a single holder) - both consolidate the rights but add contributor friction, and assignment needs an entity to hold them. This is the decision that is expensive to undo.
• The copyright notice. Whether headers stay per-author ((C) <name>) or move to a collective label ((C) The Jennifer Authors, defined by git history). The trap to avoid: a two-file AUTHORS (holders) / CONTRIBUTORS (credit) split only carries information when a work-for-hire contributor exists (employer holds copyright, individual is merely credited); for an all-volunteer project the two lists are identical, so the split is pointless. Either keep no enumerated holder file (the collective label refers to git history) or consolidate ownership via CLA / assignment.
• Relicensing headroom. LGPL already lets anyone embed / link Jennifer without permission, so ordinary use never needs a contributor's sign-off. The only thing distributed copyright forecloses is issuing a different license - e.g. a commercial embedding exception for a deep-embedded jennifer-tiny target that cannot meet LGPL's static-relink terms. If keeping that option open matters (embedding is a first-class goal), a CLA is the tool; if "LGPL-only forever" is acceptable, distributed copyright is fine and the constraint never bites.
• Contribution mechanics. CONTRIBUTING.md, the sign-off mechanism (a lightweight DCO Signed-off-by line, which asserts "I have the right to submit this" without a license grant, vs a full CLA-bot, which also grants one - the choice follows from the relicensing decision above), a code of conduct, and the PR / review workflow.
• Project governance. Who decides (BDFL vs a maintainer group), how commit rights are granted (judgment and sustained involvement, never an LOC or commit-count threshold - metrics are a bad proxy and get gamed), and a MAINTAINERS file once more than one decision-maker exists. Being listed as a contributor confers no authority; credit and governance are separate.
• Name / mark. Whether the "Jennifer" / jennifer-lang identity needs any trademark-style usage policy (forks, the deck registry) or stays informal.

The license itself stays LGPL-3.0-only unless a deliberate relicensing decision above changes it; this milestone is about the process and ownership around it, not a license change. Not legal advice - the chosen model should get a real legal review before it is published.

Requires: none (organizational, independent of the codebase). Socially paired with the M19.8 org move and triggered by the first external contribution, but no code prerequisite - which is why it is the one 1.0.0 requirement that can be settled at any time before the first outside PR.

#Requirements for 1.0.0 stable

• Project governance, licensing, and contribution policy - the M29 work: the copyright-holder model, copyright notice, relicensing headroom, CONTRIBUTING.md / sign-off, governance, and name / mark. A hard requirement for 1.0.0, and it must be settled before the first external contribution is merged (whichever comes first).
• Cross-build for macOS / Windows. The M28 multiplatform track (M28.1 Windows, M28.2 macOS) does this; ships as soon as it lands.
• Real apt repository (replacing the "GitHub Release artifact" install of the M15.8 .deb) if user demand warrants the maintenance.
• Container image (OCI). Done - .github/workflows/docker.yml builds and pushes multi-arch (linux/amd64 + linux/arm64) ghcr.io/<owner>/jennifer images on each release tag: a Debian-slim default (:latest / :<ver>, full host features) and a distroless :static variant. The image bundles both binaries and the system modules under the compile-default module dir, so a bare import "name.j"; resolves with no env var. See packaging/docker/.
• Homebrew tap (macOS, best-effort unsupported). Available - packaging/homebrew/jennifer.rb builds the standard jennifer from source (so Intel + Apple Silicon work with no Gatekeeper friction) and bakes the version and module path via -ldflags -X, so a bare import "name.j"; resolves with no env var. Published to the jennifer-language/tap tap by a manual publish.sh (the AUR convention; no CI secret). The -UNSUPPORTED macOS tarball stays alongside it.

The extra Linux / macOS distribution formats (Homebrew, Snap, Nix, Flatpak, AppImage, ...) are not requirements; they live in the horizon idea collection and ship when there's user demand and a maintainer willing to keep one green.

#Long horizon

Ideas for development beyond 1.0.0 - embedding, a WASM runtime, specialised-domain libraries, and a grab-bag of smaller possibilities - live in their own collection, kept out of the near-term plan so this file stays focused on the road to 1.0.0. See the beyond-1.0.0 idea collection.