summaryrefslogtreecommitdiff
path: root/skills
diff options
context:
space:
mode:
Diffstat (limited to 'skills')
-rw-r--r--skills/chapter-split.md6
-rw-r--r--skills/chapter25-codex-notes.md208
2 files changed, 89 insertions, 125 deletions
diff --git a/skills/chapter-split.md b/skills/chapter-split.md
index da3a7e9d..c5dee447 100644
--- a/skills/chapter-split.md
+++ b/skills/chapter-split.md
@@ -18,9 +18,9 @@ completed cleanup and partial-field-view snapshot.
On 2026-11-08, Cliff merged and pushed Chapter 30, then requested
[Chapter 31](../chapter31/README.md) on branch `ch31`. It starts from the
-completed Chapter 30 compiler. Chapter 31 now develops software drawing in
-Simple and small graphical turn-based games, starting with tic-tac-toe and an
-optional MiniFB window/input backend. New work belongs in `chapter31/`,
+completed Chapter 30 compiler. Chapter 31 develops software drawing, audio,
+time and math libraries, array initialization and static data, and graphical
+games including tic-tac-toe and Breakout. New work belongs in `chapter31/`,
preserving Chapter 30 as the preceding snapshot.
| Previous directory | Final chapter |
diff --git a/skills/chapter25-codex-notes.md b/skills/chapter25-codex-notes.md
index abc28f1b..05c11a7f 100644
--- a/skills/chapter25-codex-notes.md
+++ b/skills/chapter25-codex-notes.md
@@ -33,75 +33,90 @@ field shapes, existing Iter/SCCP propagates them, and TypeCheck checks and erase
the views. Borrowed partials can read proven fields but cannot write; unknown
callers promise no initialized fields. No new passes or backward demand walks.
-## Chapter 31: graphical games (2026-11-11)
-
-Cliff merged `ch30` into `main` at `06fb5ace` and pushed it, then requested
-branch `ch31` and a complete `chapter31/` snapshot. Continue new work in
-Chapter 31. Small graphical turn-based games now drive its library work:
-`sys.gfx` provides the optional MiniFB pixel window/input boundary, while
-`sys.draw.Canvas` draws rectangles, circles, thick lines, colors, and bitmap
-labels entirely in Simple. `docs/examples/TicTacToeGraphical.smp` is the first
-game; the existing terminal version remains available. See Chapter 31's
-`docs/drawing.md`, `docs/graphics.md`, and `docs/audio.md`. Optional `sys.audio`
-uses miniaudio for native-thread playback, default boop/win/loss cues, and
-copied mono PCM. Default tests must not require audio hardware or downloads.
-Chapter 31 supports `0x`/`0X` hexadecimal and C-style leading-zero octal
-integer literals. Cliff explicitly prefers `025755`, not a `0o` prefix.
-The 3x5 font uses five octal row digits; packed pixel colors use hex.
-Default builds/tests must not download MiniFB or require a display; interactive
-launch targets are explicit. Drawing and game checks run without a backend.
-Cliff requires offline builds: only explicit `make libs`/`init` (legacy `lib`
-alias) may access the network. Cache pinned dependencies under `lib/`, never
-`build/`; `clean` must preserve them. Shared `build-support/libraries.mk`
-gates all chapter JAR downloads. Graphics/audio makefiles use this same gate;
-missing caches fail promptly, and makefile edits never trigger network checks.
-All chapter Makefiles use `build-support/java.mk`: explicit JAR prerequisites,
-whole-source-set compilation, optional tags, and consistent class directories.
-JARs may be copied from another local chapter cache during any offline target;
-only explicit setup may download. Keep chapter-to-chapter Makefile differences
-limited to features introduced there. Native tests must build the released
-`sys` objects before executing clients, including single-test and standalone
-test targets.
-Chapter 30 retains the preceding compiler and library. Keep inherited Java test names,
-use LF for new text files, and do not add Python code or test drivers.
-Runnable examples belong in `chapter31/docs/examples`.
-
-MiniFB discovery defaults to executable-relative and obvious chapter build
-locations; examples should run directly without environment setup. Explicit
-`SIMPLE_MINIFB` paths override discovery and `off` keeps headless tests stable.
-
-The Clock example now shows digital/analog local-time clocks, switched by the
-software `sys.draw.Button` widget or Space. Button input is caller-fed, fires
-on release inside after a press inside, and has no native/window dependency.
-
-Clock rendering needs native regression coverage as well as Eval2: evaluator
-checks cannot catch instruction encoding or relocation errors. X86 floating
-comparisons use UCOMISD's CF/ZF/PF, preserve unordered behavior when layout
-negates a branch, and must not use signed SF/OF conditions. Encoding metadata
-for relocation sites uses instruction identity: scheduling/RA can clone equal
-constant loads, each of which still requires its own relocation.
-
-Time and animation now belong in Chapter 31, not a follow-on chapter proposal.
-See `chapter31/docs/time.md`: bare i64 epoch milliseconds, distinct monotonic
-deadlines, optional monotonic nanoseconds, OS local zones, Simple calendar/text
-and cooperative timer IDs, and input-aware `gfx.wait`. Cliff explicitly accepts
-`-1` for absolute parse errors despite its collision with the instant just before
-the epoch; relative time parsing is deferred. Built-in `%t` selectors cover ISO,
-12/24-hour clocks, elapsed minutes, calendar dates, and clock seconds. UTC is
-the interpolation default; local-zone formatting is an explicit library call.
+## Chapter 31: restart guidance (2026-11-14)
+
+Continue work in `chapter31/`; preserve the preceding chapter snapshots.
+There is no unfinished task from this session. Check Git status before editing:
+Cliff is actively refactoring Breakout and editing README/Canvas alongside us.
+Preserve those edits and let him do the game-method moves himself. No commit,
+push, or chapter split has been requested.
+
+Read Chapter 31's README and the relevant library docs for implemented features.
+They cover graphics/audio, Clock and Breakout, time/math, array initializers,
+read-only non-null arrays, compiler intrinsics, and static constant-array data.
+Do not revive old proposals as pending work. TypeConAry is now unified and
+non-generic; its type, rather than initializer syntax, triggers static data.
+Identical constant arrays may share storage, including strings. Preserve element
+ranges in printed types and the empty-array lattice behavior tested in TypeTest.
+
+Useful implementation facts:
+
+- Struct method headers are parsed first; bodies wait until fields are known.
+ MethodAccess infers whether the receiver needs write access. Read-only methods
+ can accept read-only receivers; writes through receiver aliases still require
+ write access. MethodFieldsTest and MethodAccessTest cover this behavior.
+- Nested functions inside methods have their own receiver parameter. Bare field
+ names resolve through that receiver, including across blocks and nested
+ functions. This is not closure capture or a bound method value: a bare callback
+ invocation supplies the calling function's receiver. Nonconstant local captures
+ remain unsupported. A no-argument function type is `{ bool }` or `{ int }`,
+ not `{ -> bool }`.
+- Bare forward types use file-qualified names. Missing required types produce
+ source diagnostics. Store-width discovery waits for the forward pointer type
+ upgrade so worklist notification is preserved.
+- A final constant method target comes from its declaration. Loading it must not
+ discard its identity merely because it has not escaped to outside code.
+- Do not use ordinary HashMap/HashSet with Node keys for bookkeeping:
+ Node.hashCode participates in GVN locking. Use identity maps/sets.
+- Breakout keeps input history in Game; there is no separate Controls class now.
+ Debounce's callback returns int because audio.stop returns i32; the result is
+ ignored. Boosted brick hits use sound 3 and the brick's soundDepth, not sound 4.
+ The old collisionsAndBoost sound expectations are fixed.
+
+Keep arithmetic compact, but space assignments, compound assignments, and
+relational operators. Preserve deliberate column alignment above other spacing
+rules. Time values use `_ms`/`_msec` suffixes; timer IDs have a smaller unsigned
+type. Prefer named bounds and products of time units to large magic numbers.
+
+Build and test from the chapter directory using the existing Java harness;
+do not add Python code or test drivers. Useful commands are `make breakout
+CTAGS=`, `make test CLASS=BreakoutTest CTAGS=`, and `make test CLASS=GraphicsTest
+METHOD=breakoutInputAndFrames CTAGS=`. Native coverage matters: Eval2 cannot
+detect instruction encoding or relocation errors. Use identity for relocation
+sites because equal constant loads can still require separate relocations.
+X86 floating comparisons use UCOMISD's CF/ZF/PF, preserve unordered behavior
+when negating a branch, and must not use signed SF/OF conditions.
+
+At this reset, the 752-test suite excluding BreakoutTest and GraphicsTest passed,
+the Breakout input/render smoke test passed, and all five BreakoutTest tests
+passed. These are dated results, not a fixed expected count. Earlier logs with
+receiver, forward-type, callback-target, or collision failures are superseded.
+No test process is left running. Do not rerun unchanged checks just for a reset.
+
+Default builds/tests are offline and need no display or audio hardware. Only
+explicit `make libs`/`init` (legacy `lib`) may download dependencies. Cache them
+under `lib/`, never `build/`; clean must preserve the cache. Missing dependencies
+fail promptly. Interactive launch targets are explicit; `SIMPLE_MINIFB=off` and
+`SIMPLE_MINIAUDIO=off` select headless tests. Build released sys objects before
+running native clients, including single-test targets. Runnable examples belong
+in `docs/examples`. Keep new and edited text LF-only.
+Shared `build-support/java.mk` and `libraries.mk` own the common build and
+download rules. Keep chapter Makefile differences limited to introduced
+features; cached JARs may be copied between chapters during offline builds.
+Keep inherited Java test names. MiniFB discovery supports executable-relative
+and chapter build paths; examples should run without environment setup.
+
+Clock button input is caller-fed and fires on release inside after a press
+inside. Its drawing widget has no native-window dependency. Time/animation
+already belong in this chapter. Time parsing uses -1 for absolute parse errors
+by Cliff's choice; relative time parsing remains deferred. UTC is the default
+for time interpolation; local-zone formatting is an explicit library call.
+Hex literals use 0x/0X and octal uses a leading zero, not 0o.
## Chapter 30 starting point (2026-11-07; superseded by Chapter 31)
-Cliff committed the Chapter 29 work as `bb9b30b2c` and requested merging
-`escape-flow` into `main`, then starting Chapter 30. Local `main` now includes
-that commit. The working branch is `ch30`, with a complete `chapter30/` copy
-and build/IDE entries. Small games drive compiler and sys-library improvements,
-starting with ASCII tic-tac-toe; the games are workloads, not the chapter's theme.
-Runnable examples belong in `chapter30/docs/examples`, not `src/test/smp/examples`.
-Do not add Python to the codebase or use Python test drivers; use the existing
-Java test harness.
-Chapter 29 retains the completed compiler and documentation. Inherited Java
-test names keep their historical identities.
+Chapter 30 is the preceding snapshot. Its old branch and startup instructions
+are superseded by the Chapter 31 guidance above.
`ScopeNode.dup()` shares `Kind` boundaries and `Var` records. When pruning a
saved break/continue scope, use `_pop()` and copy surviving forward references
@@ -109,21 +124,10 @@ with `balanceLoopFRefs`; `pop()` promotes them by mutating shared boundaries
and indices while the active scope still has its old binding order. Merge jump
scopes with loop-reference balancing, not `balanceIf`'s declaration checks.
-## Historical restart handoff (2026-11-06; superseded by Chapter 30)
+## Escape-flow implementation lessons
-Cliff requested this handoff before restarting. Active branch is `escape-flow`,
-tracking `origin/escape-flow`; HEAD is `8f460340c`. `ch29-cleanup` was previously
-fast-forwarded into local `main`, then this branch was created. The escape-flow
-implementation is still **uncommitted and unstaged**. Preserve all working-tree
-changes, including untracked `chapter29/docs/escape-flow.md` and
-`chapter29/src/test/java/com/seaofnodes/simple/EscapeFlowTest.java`. No commit,
-push, or chapter split is currently requested. Cliff thinks this may deserve
-its own chapter; keep working in Chapter29 until that decision is made.
-
-Read [the escape-flow design](../chapter29/docs/escape-flow.md) first. It is the
-current account; the later sections of deferred-construction.md retain older
-failed experiments and are explicitly superseded. The implementation is a
-tested first pass, not a claim that all outside-value precision is solved.
+See [the escape-flow design](../chapter29/docs/escape-flow.md). These are reusable
+implementation facts; old branch status and validation logs remain in Git.
Important implementation choices for review/resumption:
@@ -162,50 +166,10 @@ in EscapeFlowTest.testUnknownCallerCallback now proves that only `<clinit>` and
object/callback merge can also have an abstract pointer type, so do not cap
arbitrary TypePtr values at outside escapes.
-Validation saved under ignored `build/`:
-
-- `xint-alloc-build.log` and `xint-alloc-chapter*.log`: all five XInt chapters
- (26/27/28a/28b/29) rebuild; 134 focused type, escape, module, and import tests
- pass after renaming the pooled allocator to `XInt.alloc` and using it for
- the three foreign-set builders. It returns zeroed mutable storage to fill
- and pass to `intern`; `_free` still returns storage to the pool.
-- `escape-string-reorder-final.log`: full 28a/28b/29 suites pass after the
- String declaration reorder and measured spill expectations (538/578/601
- active tests), plus shared printer and ISA checks.
-- `escape-backport-final.log`: combined full Make run for 28a/28b/29,
- respectively 538/578/601 active tests pass with assertions, plus shared
- printer and ISA checks. Added allocator, unknown-callback cycle, and saved
- private-function exclusion coverage. Destination baselines are recorded in
- `escape-backport-baseline.log` (531 in 28a, 571 in 28b).
-- `remove-public-interface-tests.log`: full Chapter29 `make -k tests CTAGS=`,
- all 598 active tests pass after removing the frozen public-interface inventory
- and moving its test coverage to the converged escape sets.
-- `class-self-default-tests.log`: full Chapter29 `make -k tests CTAGS=`, all
- 598 active tests pass after sharpening the hidden receiver default, including
- the retained escape-exclusion assertion. No printed-IR golden changed.
-- `escape-flow-complete.log`: full Chapter29 `make -k tests`, all 598 active
- tests pass with assertions (404 raw0, 38 raw1, 13 standalone, 29 system,
- 1 fuzzer, 113 aggregate).
-- `escape-flow-last-check.log`: 26 tests pass after the final small CLInit guard
- cleanup: ClassInitDependenciesTest, ConvertNodeTest, EscapeFlowTest.
-- `EscapeSeeds.java` / `.class`: four recursive programs across four worklist
- seeds, 16 checks pass against unchanged expected IR. Sources are in
- `build/remaining-failures/*.smp`. The four are Chapter12 testCoRecur,
- testCoRecur2, testCoRecur3, and testPrivateRecursiveReturn.
-- `EscapeLoads.java` and `OutsideCallback.java` are disposable diagnostic
- harnesses; `escape-flow-*.log` includes intermediate failures. Use the final
- logs above, not an earlier trial, as the validation baseline.
-
-Run Make from `chapter29`; use the existing JUnit classpath
-`build/classes/main;build/classes/test;lib/*`. No tests/JVMs are left running.
-Do not recreate tmp/* experiment directories. No new whole-IR passes, side IR,
-IterPeeps escape-repair hooks, or relaxed goldens were introduced. There is no
-need to rerun unchanged checks merely because the conversation restarted.
-
-## Current workspace (2026-11-06)
+## Chapter 29 parser snapshot (historical)
Chapter 29 is **Tech Debt Cleanup**. Cliff approved keeping the parser split
-and moving it into this new snapshot; continue parser work there. Chapter 28b
+and moving it into that snapshot; current work belongs in Chapter 31. Chapter 28b
retains the original parser. The new `parser/` package follows the grammar;
`Var` belongs there and `IterPeeps` belongs in `codegen/`.