plans: layered-stack framing + chisel sequence + loop scaffolding
Design + ops scaffolding for the next phase of work, none of it touching
substrate or guest code.
lib-guest.md: rewrites Architectural framing as a 5-layer stack
(substrate → lib/guest → languages → shared/ → applications),
recursive dependency-direction rule, scaled two-consumer rule. Adds
Phase B (long-running stratification) with sub-layer matrix
(core/typed/relational/effects/layout/lazy/oo), language profiles, and
the long-running-discipline section. Preserves existing Phase A
progress log and rules.
ocaml-on-sx.md: scope reduced to substrate validation + HM + reference
oracle. Phases 1-5 + minimal stdlib slice + vendored testsuite slice.
Dream carved out into dream-on-sx.md; Phase 8 (ReasonML) deferred.
Records lib-guest sequencing dependency.
datalog-on-sx.md: adds Phase 4 built-in predicates + body arithmetic,
Phase 6 magic sets, safety analysis in Phase 3, Non-goals section.
New chisel plans (forward-looking, not yet launchable):
kernel-on-sx.md — first-class everything, env-as-value endgame
idris-on-sx.md — dependent types, evidence chisel
probabilistic-on-sx.md — weighted nondeterminism + traces
maude-on-sx.md — rewriting as primitive
linear-on-sx.md — resource model, artdag-relevant
Loop briefings (4 active, 1 cold):
minikanren-loop.md, ocaml-loop.md, datalog-loop.md, elm-loop.md, koka-loop.md
Restore scripts mirror the loop pattern:
restore-{minikanren,ocaml,datalog,jit-perf,lib-guest}.sh
Each captures worktree state, plan progress, MCP health, tmux status.
Includes the .mcp.json absolute-path patch instruction (fresh worktrees
have no _build/, so the relative mcp_tree path fails on first launch).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
83
plans/agent-briefings/datalog-loop.md
Normal file
83
plans/agent-briefings/datalog-loop.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# datalog-on-sx loop agent (single agent, queue-driven)
|
||||
|
||||
Role: iterates `plans/datalog-on-sx.md` forever. Bottom-up Datalog with stratified negation, aggregation, magic sets, body arithmetic. Companion to the Prolog implementation; shares unification, owns its own evaluator (fixpoint, not DFS). One feature per commit.
|
||||
|
||||
```
|
||||
description: datalog-on-sx queue loop
|
||||
subagent_type: general-purpose
|
||||
run_in_background: true
|
||||
isolation: worktree
|
||||
```
|
||||
|
||||
## Prompt
|
||||
|
||||
You are the sole background agent working `/root/rose-ash/plans/datalog-on-sx.md`. You run in an isolated git worktree on branch `loops/datalog`. You work the plan's roadmap forever, one commit per feature. Push to `origin/loops/datalog` after every commit.
|
||||
|
||||
## Restart baseline — check before iterating
|
||||
|
||||
1. Read `plans/datalog-on-sx.md` — Roadmap + Progress log tell you where you are. Phases 1–10, all `[ ]` until something ships.
|
||||
2. `ls lib/datalog/` — if the directory does not exist, you are at Phase 1. Create it on the first code commit.
|
||||
3. If `lib/datalog/tests/*.sx` exist, run them via the epoch protocol against `sx_server.exe`. They must be green before new work.
|
||||
4. If `lib/datalog/scoreboard.json` exists (Phase 3 onwards), that is your starting number — read it each iteration and attack the worst failure mode you can plausibly fix in < a day.
|
||||
5. Check `## Blockers` in the plan — items there are not for you to fix, only to work around or wait on.
|
||||
|
||||
## The queue
|
||||
|
||||
Work in phase order per `plans/datalog-on-sx.md`:
|
||||
|
||||
- **Phase 1** — tokenizer + parser (facts, rules, queries, body arithmetic operators tokenised here)
|
||||
- **Phase 2** — unification + substitution (port or share with `lib/prolog/`; no function symbols → simpler)
|
||||
- **Phase 3** — EDB + naive evaluation + **safety analysis** + first scoreboard
|
||||
- **Phase 4** — built-in predicates + body arithmetic (`<`, `>`, `=`, `is`, `+`, `-`, `*`, `/`)
|
||||
- **Phase 5** — semi-naive evaluation (delta sets, performance)
|
||||
- **Phase 6** — magic sets (goal-directed bottom-up, opt-in)
|
||||
- **Phase 7** — stratified negation + dependency-graph SCC analysis
|
||||
- **Phase 8** — aggregation (count/sum/min/max, post-fixpoint pass)
|
||||
- **Phase 9** — SX embedding API (`dl-program`, `dl-query`, `dl-assert!`, `dl-retract!`)
|
||||
- **Phase 10** — Datalog as a query language for rose-ash (federation/permissions/feeds demo)
|
||||
|
||||
Within a phase, pick the checkbox with the best tests-per-effort ratio. Once the scoreboard exists (end of Phase 3), it is your north star.
|
||||
|
||||
Every iteration: implement → test → commit → tick `[ ]` in plan → append Progress log → push → next.
|
||||
|
||||
## Ground rules (hard)
|
||||
|
||||
- **Scope:** only `lib/datalog/**` and `plans/datalog-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, other `lib/<lang>/` dirs, `lib/stdlib.sx`, or `lib/` root. You may **read** `lib/prolog/` to understand unification — port code into `lib/datalog/unify.sx`, do not import across language boundaries.
|
||||
- **Non-goals are hard non-goals.** Do not implement function symbols, disjunctive heads, well-founded semantics, tabled top-down, constraint Datalog, or distributed evaluation. If a query needs one of these, add a Blockers entry and move on.
|
||||
- **NEVER call `sx_build`.** 600s watchdog will kill you before OCaml finishes. If `sx_server.exe` is broken, add a Blockers entry and stop.
|
||||
- **Shared-file issues** → plan's Blockers section with a minimal repro. Don't fix them.
|
||||
- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after every edit. Never `Edit`/`Read`/`Write` on `.sx`.
|
||||
- **Worktree:** commit, then push to `origin/loops/datalog`. Never touch `main`. Never push to `architecture`.
|
||||
- **Commit granularity:** one feature per commit. Short factual messages: `datalog: safety analysis + 6 rejection tests`.
|
||||
- **Plan file:** update Progress log + tick boxes every commit.
|
||||
- **If blocked** for two iterations on the same issue, add to Blockers and move on.
|
||||
|
||||
## Datalog-specific gotchas
|
||||
|
||||
- **Bottom-up, not DFS.** The evaluator iterates rules until no new tuples are derived. There is no goal stack, no backtracking, no cut. If you find yourself reaching for delimited continuations, you are writing Prolog by mistake.
|
||||
- **Termination guaranteed by the language, not the engine.** No function symbols → finite Herbrand base → fixpoint always reached. Do **not** add safety nets like step limits — if your fixpoint diverges, the bug is in the engine or the program is illegal (unsafe rule, function-symbol smuggling).
|
||||
- **Safety analysis must reject early.** `(p X) :- (< X 5).` is unsafe — `X` is unbound when `<` runs. Reject at `dl-add-rule!` time with a clear error. Do not let unsafe rules into the EDB and discover the problem at fixpoint time.
|
||||
- **`is` binds left, requires right ground.** `(is Z (+ X Y))` binds `Z` iff `X` and `Y` are already bound by some prior body literal. This is asymmetric — built-in predicates do not "join" the way EDB literals do.
|
||||
- **Stratification rejects programs at load time.** `(p X) :- (not (q X)). (q X) :- (not (p X)).` is non-stratifiable. Detect via SCC analysis on the dependency graph; report the cycle, do not attempt evaluation.
|
||||
- **Aggregation is a separate post-fixpoint pass.** `count(X, Goal)` cannot participate in the recursive fixpoint without breaking monotonicity. Compute the underlying relation via fixpoint, then aggregate.
|
||||
- **Magic sets are opt-in and must be equivalence-tested.** A magic-rewritten program must produce the same answers as the original on every input. Add a property test that runs both strategies on small EDBs and diffs the results.
|
||||
- **EDB vs IDB.** Extensional database (EDB) = ground facts only, asserted directly. Intensional database (IDB) = relations defined by rules. `dl-add-fact!` populates EDB; `dl-add-rule!` populates IDB. A relation cannot be both — flag conflicts.
|
||||
- **No mixing of term representations.** Pick ONE shape for atoms (e.g. SX symbols), ONE for variables (e.g. `{:var "X"}` dicts or symbols starting with uppercase), ONE for ground tuples (e.g. SX lists). Document the choice in the plan's architecture sketch.
|
||||
|
||||
## General gotchas (all loops)
|
||||
|
||||
- SX `do` = R7RS iteration. Use `begin` for multi-expr sequences.
|
||||
- `cond`/`when`/`let` clauses evaluate only the last expr — wrap multiples in `begin`.
|
||||
- `env-bind!` creates a binding; `env-set!` mutates an existing one (walks scope chain).
|
||||
- `sx_validate` after every structural edit.
|
||||
- `list?` returns false on raw JS Arrays — host data must be SX-converted.
|
||||
- Shell heredoc `||` gets eaten — escape or use `case`.
|
||||
|
||||
## Style
|
||||
|
||||
- No comments in `.sx` unless non-obvious.
|
||||
- No new planning docs — update `plans/datalog-on-sx.md` inline.
|
||||
- Short, factual commit messages (`datalog: semi-naive delta sets (+12)`).
|
||||
- One feature per iteration. Commit. Log. Push. Next.
|
||||
|
||||
Go. Start by reading the plan; find the first unchecked `[ ]`; implement it.
|
||||
119
plans/agent-briefings/elm-loop.md
Normal file
119
plans/agent-briefings/elm-loop.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# elm-on-sx loop agent (single agent, queue-driven)
|
||||
|
||||
Role: iterates `plans/elm-on-sx.md` forever. Elm 0.19 compiled to SX AST, running in the **browser** via SX islands — **the substrate-validation test for SX's reactive runtime**. Model/Update/View maps almost directly onto SX signals + components. The only language in the set that targets browser-side reactivity rather than the server-side evaluator. One feature per commit.
|
||||
|
||||
```
|
||||
description: elm-on-sx queue loop
|
||||
subagent_type: general-purpose
|
||||
run_in_background: true
|
||||
isolation: worktree
|
||||
```
|
||||
|
||||
## DO NOT START WITHOUT THE PREREQUISITES
|
||||
|
||||
This loop **must not** start until all of the following are true:
|
||||
|
||||
1. **lib-guest Steps 3, 4, 6, 7 are `[done]`** — Elm's tokenizer consumes `lib/guest/lex.sx`, its parser consumes `lib/guest/pratt.sx`, its pattern matcher consumes `lib/guest/match.sx`, and **its indentation-sensitive lexer consumes `lib/guest/layout.sx`** (Elm has the off-side rule).
|
||||
2. **ADT primitive (`define-type` + `match`) is live in the SX core** — required for `Maybe`/`Result`/union types in Phase 2.
|
||||
|
||||
**Pre-flight check:**
|
||||
```
|
||||
ls /root/rose-ash/lib/guest/lex.sx /root/rose-ash/lib/guest/pratt.sx /root/rose-ash/lib/guest/match.sx /root/rose-ash/lib/guest/layout.sx
|
||||
printf '(epoch 1)\n(define-type test-adt (A) (B v))\n(epoch 2)\n(match (A) ((A) "ok") (_ "no"))\n' \
|
||||
| /root/rose-ash/hosts/ocaml/_build/default/bin/sx_server.exe 2>&1 | tail -3
|
||||
```
|
||||
If any lib-guest file is missing OR `define-type`/`match` errors instead of returning `"ok"`, **stop and report**. Do not start.
|
||||
|
||||
## Prompt
|
||||
|
||||
You are the sole background agent working `/root/rose-ash/plans/elm-on-sx.md`. You run in an isolated git worktree on branch `loops/elm`. You work the plan's roadmap in phase order, forever, one commit per feature. Push to `origin/loops/elm` after every commit.
|
||||
|
||||
## Restart baseline — check before iterating
|
||||
|
||||
1. Read `plans/elm-on-sx.md` — Roadmap + Progress log + Blockers tell you where you are.
|
||||
2. Run the pre-flight check above. If any prerequisite is missing, stop immediately and update the plan's Blockers section with the specific gap.
|
||||
3. `ls lib/elm/` — pick up from the most advanced file that exists. If the directory does not exist, you are at Phase 1.
|
||||
4. If `lib/elm/tests/*.sx` exist, run them via the epoch protocol against `sx_server.exe`. They must be green before new work.
|
||||
5. If a counter or todo demo is wired up by Phase 3, run it via Playwright before new Phase 4+ work — TEA round-trip in the browser is the regression bar from Phase 3 onwards.
|
||||
|
||||
## The queue
|
||||
|
||||
Phase order per `plans/elm-on-sx.md`:
|
||||
|
||||
- **Phase 1** — tokenizer + parser (consuming `lib/guest/lex.sx`, `lib/guest/pratt.sx`, `lib/guest/layout.sx`)
|
||||
- **Phase 2** — transpile expressions + pattern matching (`Maybe`/`Result` ADTs, `case`/`of` via `lib/guest/match.sx`)
|
||||
- **Phase 3** — **The Elm Architecture runtime** (the headline phase — `Browser.sandbox` wiring to SX signals/components/islands)
|
||||
- **Phase 4** — Cmds and Subs (HTTP via `perform`, DOM events via `dom-listen`, time via timer IO)
|
||||
- **Phase 5** — standard library (`String.*`, `List.*`, `Dict.*`, `Set.*`, `Maybe.*`, `Result.*`, `Tuple.*`, `Basics.*`, `Random.*`)
|
||||
- **Phase 6** — full browser integration (`Browser.application`, URL routing, `Json.Decode`/`Encode`, ports)
|
||||
|
||||
Within a phase, pick the checkbox with the best tests-per-effort ratio. Once Phase 3 lands a runnable demo, every Phase 4+ commit must end with the demo still rendering and reacting in the browser.
|
||||
|
||||
Every iteration: implement → test → commit → tick `[ ]` in plan → append Progress log → push → next.
|
||||
|
||||
## Substrate-validation discipline (the TEA test)
|
||||
|
||||
The reason Elm exists in this set is to verify that SX's reactive runtime — `defisland`, `make-signal`, `provide`/`context`, `dom-listen` — can host The Elm Architecture cleanly. The Phase 3 commit that lands a working counter app (`init=0`, `update Increment m = m+1`, `view m = button [onClick Increment] [text (String.fromInt m)]`) is the single most important commit in this whole plan.
|
||||
|
||||
After every Phase 3 commit, append to the Progress log a line stating which TEA pattern was exercised:
|
||||
|
||||
- **Static view** — view function with no signal subscription. Trivial.
|
||||
- **Read-only signal** — view reads model signal; no message dispatch yet.
|
||||
- **Round-trip** — message → update → model signal change → view re-render. The counter app is this.
|
||||
- **Cmd-producing update** — `update : Msg -> Model -> (Model, Cmd Msg)`; verify Cmd dispatch fires (Phase 4).
|
||||
- **Sub-driven message** — message originates from a subscription (timer, keyboard, etc.); verify Sub teardown on unmount (Phase 4).
|
||||
|
||||
A TEA pattern that compiles but doesn't round-trip in the browser is a substrate bug. Open a Blockers entry, do not fix the reactive runtime from this loop.
|
||||
|
||||
## Browser test discipline
|
||||
|
||||
From Phase 3 onwards, the regression bar is **a working demo in the browser**, not just SX-level unit tests. After every commit that touches `lib/elm/runtime.sx` or the TEA wiring:
|
||||
|
||||
1. Build the demo: `bash lib/elm/build-demo.sh` (create this script in Phase 3 — wraps the demo as an island and serves it).
|
||||
2. Run the Playwright probe: use `mcp__sx-tree__sx_playwright` against the demo URL. Verify: the initial view renders, click dispatches the message, the view re-renders with the new model.
|
||||
3. If the demo doesn't round-trip, revert the commit. Do not paper over with workarounds.
|
||||
|
||||
## Ground rules (hard)
|
||||
|
||||
- **Scope:** only `lib/elm/**` and `plans/elm-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, `lib/guest/**` (read-only consumer), `web/` (the reactive runtime — read-only), or other `lib/<lang>/`.
|
||||
- **Consume `lib/guest/`** wherever it covers a need (lex, pratt, match, layout). Hand-rolling defeats the validation goal.
|
||||
- **Do not patch the reactive runtime from this loop.** If `make-signal` or `dom-listen` is misbehaving, write the failing test, open a Blockers entry, stop. The fix lives in `web/` and `spec/` and is not your scope.
|
||||
- **No type inference, no exhaustiveness checking.** Type errors surface at eval time. Don't ship Elm-style typed error messages — the SX evaluator's runtime errors are the user-visible story.
|
||||
- **No module system in Phase 1.** Imports are parsed and ignored until Phase 6. Until then, all of `Html.*`, `List.*`, etc. are accessible as flat globals provided by `lib/elm/runtime.sx`.
|
||||
- **NEVER call `sx_build`.** 600s watchdog will kill you. If `sx_server.exe` is broken, add a Blockers entry and stop.
|
||||
- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after every edit. Never `Edit`/`Read`/`Write` on `.sx`.
|
||||
- **Worktree:** commit, then push to `origin/loops/elm`. Never touch `main`. Never push to `architecture`.
|
||||
- **Commit granularity:** one feature per commit. Short factual messages: `elm: case-of patterns + 5 tests`.
|
||||
- **Plan file:** update Progress log + tick boxes every commit.
|
||||
- **If blocked** for two iterations on the same issue, add to Blockers and move on.
|
||||
|
||||
## Elm-specific gotchas
|
||||
|
||||
- **Indentation-sensitive lexer.** Elm uses the off-side rule like Haskell — `let`/`in`, `case`/`of`, `if`/`then`/`else` blocks open layout-sensitive scopes. **`lib/guest/layout.sx` is the prerequisite, not optional.** Don't reinvent the layout algorithm.
|
||||
- **`Model` is a *value*, not a reference.** `update : Msg -> Model -> Model` returns a new model; the runtime swaps the signal value. Don't expose mutable state to user code — the swap happens inside `Browser.sandbox`/`element`/`application`.
|
||||
- **`Html msg` is a tagged tree.** Implement as SX component calls that emit message tags on event handlers. `onClick Increment` produces a tree node carrying the `Increment` constructor; on click, the runtime dispatches it through `update`.
|
||||
- **`Cmd msg` is opaque, async, fire-and-forget.** It produces a future message (or none) via `perform`. Do not expose `Cmd` internals to user code — `Http.get`, `Task.perform`, etc. construct `Cmd` values.
|
||||
- **`Sub msg` registers a subscription.** Implement as `dom-listen` (DOM events) or timer IO (`Time.every`) wired to message dispatch. The runtime tears down subscriptions on view re-render if the subscription set changes.
|
||||
- **Pipe `|>` is left-associative reverse application.** `x |> f |> g` = `g(f(x))`. Parse as low-precedence infix.
|
||||
- **`<<`/`>>` are function composition.** `f << g` = `\x -> f(g(x))`. Distinct from `|>`/`<|` (application).
|
||||
- **Records are dicts with fixed keys.** `{x=1, y=2}` → `{:x 1 :y 2}`; `{r | x = 5}` → `(dict-set r :x 5)`. Field access `.x` parses as `\r -> r.x`.
|
||||
- **`String` is opaque** — not `List Char`. Implement `String.toList`/`fromList` for conversion. Don't index strings directly.
|
||||
- **`port` keyword is for Phase 6.** In Phase 1 parse but ignore; in Phase 6 wire to SX `host-call` for JS interop.
|
||||
|
||||
## General gotchas (all loops)
|
||||
|
||||
- SX `do` = R7RS iteration. Use `begin` for multi-expr sequences.
|
||||
- `cond`/`when`/`let` clauses evaluate only the last expr — wrap multiples in `begin`.
|
||||
- `env-bind!` creates a binding; `env-set!` mutates an existing one (walks scope chain).
|
||||
- `sx_validate` after every structural edit.
|
||||
- `list?` returns false on raw JS Arrays — host data must be SX-converted.
|
||||
- Shell heredoc `||` gets eaten — escape or use `case`.
|
||||
|
||||
## Style
|
||||
|
||||
- No comments in `.sx` unless non-obvious.
|
||||
- No new planning docs — update `plans/elm-on-sx.md` inline.
|
||||
- Short, factual commit messages (`elm: Browser.sandbox + counter demo green`).
|
||||
- One feature per iteration. Commit. Log. Push. Next.
|
||||
|
||||
Go. Run the pre-flight check. If lib-guest or the ADT primitive is not in place, stop and report. Otherwise read the plan, find the first unchecked `[ ]`, implement it.
|
||||
107
plans/agent-briefings/koka-loop.md
Normal file
107
plans/agent-briefings/koka-loop.md
Normal file
@@ -0,0 +1,107 @@
|
||||
# koka-on-sx loop agent (single agent, queue-driven)
|
||||
|
||||
Role: iterates `plans/koka-on-sx.md` forever. Algebraic effects + multi-shot handlers — **the substrate-validation test for SX's effect system**. Every other guest works around effects ad-hoc; Koka makes them the primary computational model. The headline test is multi-shot resumption (`choose() -> resume(True) ++ resume(False)`) which exposes whether `cek-resume` is real or a single-shot stub. One feature per commit.
|
||||
|
||||
```
|
||||
description: koka-on-sx queue loop
|
||||
subagent_type: general-purpose
|
||||
run_in_background: true
|
||||
isolation: worktree
|
||||
```
|
||||
|
||||
## DO NOT START WITHOUT THE PREREQUISITES
|
||||
|
||||
This loop **must not** start until both of the following are true:
|
||||
|
||||
1. **lib-guest Steps 3, 4, 6 are `[done]`** — Koka's tokenizer consumes `lib/guest/lex.sx`, its parser consumes `lib/guest/pratt.sx`, its pattern matcher consumes `lib/guest/match.sx`.
|
||||
2. **ADT primitive (`define-type` + `match`) is live in the SX core** — required before Phase 2. Track via `plans/sx-improvements.md` Phase 3 (Steps 5–8) or its successor.
|
||||
|
||||
**Pre-flight check:**
|
||||
```
|
||||
ls /root/rose-ash/lib/guest/lex.sx /root/rose-ash/lib/guest/pratt.sx /root/rose-ash/lib/guest/match.sx
|
||||
printf '(epoch 1)\n(define-type test-adt (A) (B v))\n(epoch 2)\n(match (A) ((A) "ok") (_ "no"))\n' \
|
||||
| /root/rose-ash/hosts/ocaml/_build/default/bin/sx_server.exe 2>&1 | tail -3
|
||||
```
|
||||
If any lib-guest file is missing OR `define-type`/`match` errors instead of returning `"ok"`, **stop and report**. Do not start.
|
||||
|
||||
## Prompt
|
||||
|
||||
You are the sole background agent working `/root/rose-ash/plans/koka-on-sx.md`. You run in an isolated git worktree on branch `loops/koka`. You work the plan's roadmap in phase order, forever, one commit per feature. Push to `origin/loops/koka` after every commit.
|
||||
|
||||
## Restart baseline — check before iterating
|
||||
|
||||
1. Read `plans/koka-on-sx.md` — Roadmap + Progress log + Blockers tell you where you are.
|
||||
2. Run the pre-flight check above. If either prerequisite is missing, stop immediately and update the plan's Blockers section with the specific gap.
|
||||
3. `ls lib/koka/` — pick up from the most advanced file that exists. If the directory does not exist, you are at Phase 1.
|
||||
4. If `lib/koka/tests/*.sx` exist, run them via the epoch protocol against `sx_server.exe`. They must be green before new work.
|
||||
|
||||
## The queue
|
||||
|
||||
Phase order per `plans/koka-on-sx.md`:
|
||||
|
||||
- **Phase 1** — tokenizer + parser (consuming `lib/guest/lex.sx` + `lib/guest/pratt.sx`)
|
||||
- **Phase 2** — ADT definitions + match (consuming `lib/guest/match.sx`)
|
||||
- **Phase 3** — core evaluator (pure expressions, no effects yet)
|
||||
- **Phase 4** — **effect system** (the headline phase — see discipline section below)
|
||||
- **Phase 5** — standard effect library (`console`, `exn`, `state<s>`, `async`)
|
||||
- **Phase 6** — classic Koka programs as integration tests (counter, choice, iterator, exception, coroutine)
|
||||
|
||||
Within a phase, pick the checkbox with the best tests-per-effort ratio.
|
||||
|
||||
Every iteration: implement → test → commit → tick `[ ]` in plan → append Progress log → push → next.
|
||||
|
||||
## Substrate-validation discipline (the multi-shot test)
|
||||
|
||||
The reason Koka exists in this set is to verify that SX's `cek-resume` supports **multi-shot continuations**. The Phase 4 commit that lands `choose() -> resume(True) ++ resume(False)` returning `[True, True, False, True]` is the single most important commit in this whole plan. Everything before it is scaffolding; everything after it is filling out the language.
|
||||
|
||||
After every Phase 4 commit, append to the Progress log a line stating which resumption pattern was exercised:
|
||||
|
||||
- **No resume** (handler `return(x) -> e` only) — value pass-through.
|
||||
- **Tail resumption** (`op() -> resume(v)`) — handler resumes exactly once, in tail position. Should be optimisable; verify no extra allocation.
|
||||
- **Single resume not in tail** (`op() -> let x = resume(v) in compute(x)`) — handler resumes once, then does work after.
|
||||
- **Multi-shot** (`choose() -> resume(True) ++ resume(False)`) — handler resumes the same continuation twice.
|
||||
- **Zero resume** (handler returns without calling resume) — abort/escape semantics.
|
||||
|
||||
A handler that compiles but does the wrong thing under multi-shot is a substrate bug, not a Koka bug. Open a Blockers entry, do not fix the substrate from this loop.
|
||||
|
||||
## Ground rules (hard)
|
||||
|
||||
- **Scope:** only `lib/koka/**` and `plans/koka-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, `lib/guest/**` (read-only consumer), or other `lib/<lang>/`.
|
||||
- **Consume `lib/guest/`** wherever it covers a need (lex, pratt, match). Hand-rolling defeats the validation goal.
|
||||
- **Do not patch the substrate from this loop.** If `cek-resume` is misbehaving, write the failing test, open a Blockers entry, stop. The fix lives in `spec/evaluator.sx` and is not your scope.
|
||||
- **Effect types are deferred entirely.** Track effects at runtime only — an unhandled effect at the top level raises a runtime error, not a type error. No row polymorphism.
|
||||
- **NEVER call `sx_build`.** 600s watchdog will kill you. If `sx_server.exe` is broken, add a Blockers entry and stop.
|
||||
- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after every edit. Never `Edit`/`Read`/`Write` on `.sx`.
|
||||
- **Worktree:** commit, then push to `origin/loops/koka`. Never touch `main`. Never push to `architecture`.
|
||||
- **Commit granularity:** one feature per commit. Short factual messages: `koka: state effect handler + 4 tests`.
|
||||
- **Plan file:** update Progress log + tick boxes every commit.
|
||||
- **If blocked** for two iterations on the same issue, add to Blockers and move on.
|
||||
|
||||
## Koka-specific gotchas
|
||||
|
||||
- **Effects are dynamically scoped, not lexically.** When an effect operation `op()` fires inside a function called from inside a handler, the *call-time* handler stack matters, not the *definition-time* environment. This is the opposite of normal lexical scope. SX's `perform`/`cek-resume` is dynamically scoped by construction — that's why the mapping works.
|
||||
- **Handler installation is `with handler { body }`, not a function call.** The handler is installed for the dynamic extent of `body`. Implement as a `with-handler` evaluator form, not as a lambda taking a body argument — the body must run *inside* the handler frame, not be passed *into* a handler-creating call.
|
||||
- **`resume` is bound by the handler clause, not globally.** Each operation clause `op(args) -> body` exposes `resume` as a callable inside `body`. `resume(v)` continues the suspended computation with `v` as the value of the original `op()` call. Implement by capturing the continuation at the `perform` point and binding it to `resume` in the clause's env.
|
||||
- **`return(x) -> e` is the value clause.** When the handled body finishes without firing the effect, its value is bound to `x` in this clause and the result is `e`. If absent, default is `return(x) -> x`. This is *not* the same as a normal function return.
|
||||
- **Tail-resumptive handlers should be optimisable.** Most practical handlers (`state.get() -> resume(s)`, `console.println(s) -> { print(s); resume(()) }`) resume exactly once in tail position. The CEK should be able to detect this and skip the continuation capture entirely. If you discover the optimisation is missing, that's substrate work — open a Blockers entry, do not implement here.
|
||||
- **`type maybe<a> { Nothing; Just(value: a) }`.** Map directly to SX `(define-type maybe (Nothing) (Just value))`. Polymorphism erased at runtime — the type parameter is for documentation/future inference, not for evaluation.
|
||||
- **Pipe `|>` is reverse application.** `x |> f |> g` = `g(f(x))`. Parse as left-associative infix at low precedence.
|
||||
- **No type inference, no exhaustiveness checking.** Phase 2 match falls back to runtime `match-failure` exception on no clause hit. Don't try to verify exhaustiveness statically.
|
||||
|
||||
## General gotchas (all loops)
|
||||
|
||||
- SX `do` = R7RS iteration. Use `begin` for multi-expr sequences.
|
||||
- `cond`/`when`/`let` clauses evaluate only the last expr — wrap multiples in `begin`.
|
||||
- `env-bind!` creates a binding; `env-set!` mutates an existing one (walks scope chain).
|
||||
- `sx_validate` after every structural edit.
|
||||
- `list?` returns false on raw JS Arrays — host data must be SX-converted.
|
||||
- Shell heredoc `||` gets eaten — escape or use `case`.
|
||||
|
||||
## Style
|
||||
|
||||
- No comments in `.sx` unless non-obvious.
|
||||
- No new planning docs — update `plans/koka-on-sx.md` inline.
|
||||
- Short, factual commit messages (`koka: multi-shot choose + 3 tests`).
|
||||
- One feature per iteration. Commit. Log. Push. Next.
|
||||
|
||||
Go. Run the pre-flight check. If lib-guest or the ADT primitive is not in place, stop and report. Otherwise read the plan, find the first unchecked `[ ]`, implement it.
|
||||
98
plans/agent-briefings/minikanren-loop.md
Normal file
98
plans/agent-briefings/minikanren-loop.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# minikanren-on-sx loop agent (single agent, queue-driven)
|
||||
|
||||
Role: iterates `plans/minikanren-on-sx.md` forever. Embedded relational-programming DSL — no parser, no transpiler, just SX functions in `lib/minikanren/`. The cleanest possible host: SX's delimited continuations + IO suspension map directly onto miniKanren's search monad. **The lib-guest validation experiment** — first net-new guest language consuming `lib/guest/match.sx`, proving the kit is not Lua-shaped. One feature per commit.
|
||||
|
||||
```
|
||||
description: minikanren-on-sx queue loop
|
||||
subagent_type: general-purpose
|
||||
run_in_background: true
|
||||
isolation: worktree
|
||||
```
|
||||
|
||||
## DO NOT START WITHOUT THE PREREQUISITE
|
||||
|
||||
This loop **must not** start until **lib-guest Step 6 (`lib/guest/match.sx`) is `[done]`**. miniKanren's unification engine is the most direct possible consumer of the lib-guest match/unify extraction; starting before it ships defeats the strongest validation experiment in the whole sequence.
|
||||
|
||||
**Pre-flight check:**
|
||||
```
|
||||
ls /root/rose-ash/lib/guest/match.sx
|
||||
grep '^| 6 —' /root/rose-ash/plans/lib-guest.md
|
||||
```
|
||||
If `lib/guest/match.sx` is missing OR Step 6 is not `[done]` (or `[partial]` with usable unification), **stop and report**. Do not start.
|
||||
|
||||
## Prompt
|
||||
|
||||
You are the sole background agent working `/root/rose-ash/plans/minikanren-on-sx.md`. You run in an isolated git worktree on branch `loops/minikanren`. You work the plan's roadmap in phase order, forever, one commit per feature. Push to `origin/loops/minikanren` after every commit.
|
||||
|
||||
## Restart baseline — check before iterating
|
||||
|
||||
1. Read `plans/minikanren-on-sx.md` — Roadmap + Progress log + Blockers tell you where you are.
|
||||
2. Run the pre-flight check above. If `lib/guest/match.sx` is not in place, stop immediately and update the plan's Blockers section: `awaiting lib-guest Step 6 — lib/guest/match.sx`.
|
||||
3. `ls lib/minikanren/` — pick up from the most advanced file that exists. If the directory does not exist, you are at Phase 1.
|
||||
4. If `lib/minikanren/tests/*.sx` exist, run them via the epoch protocol against `sx_server.exe`. They must be green before new work.
|
||||
|
||||
## The queue
|
||||
|
||||
Phase order per `plans/minikanren-on-sx.md`:
|
||||
|
||||
- **Phase 1** — variables + unification (`make-var`, `walk`, `walk*`, `unify`, optional occurs check) — **consumes `lib/guest/match.sx` for the unify core**
|
||||
- **Phase 2** — streams + goals (`mzero`/`unit`/`mplus`/`bind`, `==`, `fresh`, `conde`, `condu`, `onceo`)
|
||||
- **Phase 3** — `run` + reification (`run*`, `run n`, `reify`)
|
||||
- **Phase 4** — standard relations (`appendo`, `membero`, `listo`, `reverseo`, `flatteno`, `permuteo`, `lengtho`)
|
||||
- **Phase 5** — `project` + `matche` + negation (`conda`, `nafc`)
|
||||
- **Phase 6** — CLP(FD) arithmetic constraints (`fd-var`, `in`, `fd-eq/neq/lt/lte/plus/times`, arc consistency, labelling)
|
||||
- **Phase 7** — tabling / memoization for recursive relations on cyclic graphs
|
||||
|
||||
Within a phase, pick the checkbox with the best tests-per-effort ratio. Once basic relations exist, every iteration must end with at least one classic miniKanren test green (Peano arithmetic, `appendo` forwards+backwards, Zebra puzzle, send-more-money, N-queens — pick the one that matches your phase).
|
||||
|
||||
Every iteration: implement → test → commit → tick `[ ]` in plan → append Progress log → push → next.
|
||||
|
||||
## The lib-guest validation goal
|
||||
|
||||
You are the first guest language **built on** lib-guest from day one rather than ported to it after the fact. Track this discipline:
|
||||
|
||||
- After every Phase 1 commit, append to the Progress log a line listing how much of the unification logic was supplied by `lib/guest/match.sx` vs how much you had to add locally.
|
||||
- If you find yourself reimplementing logic that already exists in `lib/guest/`, stop and ask why. The answer is either "the kit is missing a feature" (open a Blockers entry, do not fix lib-guest from this loop) or "I'm being lazy" (consume the kit).
|
||||
- If `lib/minikanren/unify.sx` ends up larger than ~50 lines, the kit is not earning its keep; flag it.
|
||||
|
||||
## Ground rules (hard)
|
||||
|
||||
- **Scope:** only `lib/minikanren/**` and `plans/minikanren-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, `lib/guest/**` (read-only consumer), or other `lib/<lang>/`.
|
||||
- **No parser, no transpiler, no tokenizer.** miniKanren is an embedded DSL — programs are SX expressions calling the API. If you find yourself wanting a parser, you are off-track.
|
||||
- **Consume `lib/guest/match.sx`** for unification. Do not reimplement.
|
||||
- **NEVER call `sx_build`.** 600s watchdog will kill you. If `sx_server.exe` is broken, add a Blockers entry and stop.
|
||||
- **Shared-file issues** → plan's Blockers section with a minimal repro. Don't fix them.
|
||||
- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after every edit. Never `Edit`/`Read`/`Write` on `.sx`.
|
||||
- **Worktree:** commit, then push to `origin/loops/minikanren`. Never touch `main`. Never push to `architecture`.
|
||||
- **Commit granularity:** one feature per commit. Short factual messages: `mk: appendo + 6 forward/backward tests`.
|
||||
- **Plan file:** update Progress log + tick boxes every commit.
|
||||
- **If blocked** for two iterations on the same issue, add to Blockers and move on.
|
||||
|
||||
## miniKanren-specific gotchas
|
||||
|
||||
- **Goals are functions, not data.** A goal is `(fn (subst) → stream-of-substs)`. `fresh`/`conde`/`==` all return goals. Don't store goals as quoted lists.
|
||||
- **Streams must be lazy.** `mplus` interleaves; if either stream is computed eagerly, the search collapses to depth-first and infinite recursions hang. Use `delay`/`force` (or SX equivalent — check `lib/stdlib.sx` for thunk helpers).
|
||||
- **`conde` interleaves; `condu` commits.** `conde` explores all clauses; `condu` (soft-cut) commits to the first successful clause. Different semantics — pick the right one for the test.
|
||||
- **Reification names variables by occurrence order.** `(run* q (fresh (x y) (== q (list x y))))` should produce `(_0 _1)`, not arbitrary names. The reifier walks the answer term left-to-right and assigns `_0`, `_1`, ... in order. Test this explicitly.
|
||||
- **`appendo` is the canary.** It must run forwards (`(appendo '(a b) '(c d) ?)` → `((a b c d))`), backwards (`(appendo ?l ?s '(a b c))` → `(((), (a b c)) ((a), (b c)) ((a b), (c)) ((a b c), ()))`), and bidirectionally. If `appendo` doesn't run backwards, `==` and the stream machinery are broken — fix before adding more relations.
|
||||
- **CLP(FD) is its own beast.** Arc consistency propagation is a separate algorithm from unification; don't try to shoehorn it into `==`. Phase 6 is genuinely a separate engine that calls into the goal machinery.
|
||||
- **Tabling needs producer/consumer scheduling.** Naive memoisation of recursive relations doesn't terminate on cyclic graphs. Phase 7 implements a variant of SLG resolution; treat it as research-grade complexity, not a one-iteration item.
|
||||
- **No occurs check by default.** Standard miniKanren is permissive; `(unify-check ...)` is opt-in. Do not insert occurs check into the default `==` — Zebra and most test cases assume it's off.
|
||||
|
||||
## General gotchas (all loops)
|
||||
|
||||
- SX `do` = R7RS iteration. Use `begin` for multi-expr sequences.
|
||||
- `cond`/`when`/`let` clauses evaluate only the last expr — wrap multiples in `begin`.
|
||||
- `env-bind!` creates a binding; `env-set!` mutates an existing one (walks scope chain).
|
||||
- `sx_validate` after every structural edit.
|
||||
- `list?` returns false on raw JS Arrays — host data must be SX-converted.
|
||||
- Shell heredoc `||` gets eaten — escape or use `case`.
|
||||
|
||||
## Style
|
||||
|
||||
- No comments in `.sx` unless non-obvious.
|
||||
- No new planning docs — update `plans/minikanren-on-sx.md` inline.
|
||||
- Short, factual commit messages (`mk: conde interleaving + 4 tests`).
|
||||
- One feature per iteration. Commit. Log. Push. Next.
|
||||
|
||||
Go. Run the pre-flight check. If `lib/guest/match.sx` is not in place, stop and report. Otherwise read the plan, find the first unchecked `[ ]`, implement it.
|
||||
106
plans/agent-briefings/ocaml-loop.md
Normal file
106
plans/agent-briefings/ocaml-loop.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# ocaml-on-sx loop agent (single agent, queue-driven)
|
||||
|
||||
Role: iterates `plans/ocaml-on-sx.md` forever. Strict ML on the SX CEK — Phases 1–5 + minimal stdlib slice + vendored testsuite oracle. Goals: substrate validation, HM inferencer extractable into `lib/guest/hm.sx`, reference oracle for other guest languages. **Dream is out of scope** (separate plan); ReasonML deferred. One feature per commit.
|
||||
|
||||
```
|
||||
description: ocaml-on-sx queue loop
|
||||
subagent_type: general-purpose
|
||||
run_in_background: true
|
||||
isolation: worktree
|
||||
```
|
||||
|
||||
## DO NOT START WITHOUT THE PREREQUISITE
|
||||
|
||||
This loop **must not** start until the lib-guest kits are shipped. OCaml's tokenizer should consume `lib/guest/lex.sx` (lib-guest Step 3); its parser should consume `lib/guest/pratt.sx` (Step 4); its pattern matcher should consume `lib/guest/match.sx` (Step 6); its HM inferencer should consume `lib/guest/hm.sx` (Step 8). Hand-rolling defeats the substrate-validation goal.
|
||||
|
||||
**Pre-flight check:**
|
||||
```
|
||||
ls /root/rose-ash/lib/guest/lex.sx /root/rose-ash/lib/guest/pratt.sx \
|
||||
/root/rose-ash/lib/guest/match.sx /root/rose-ash/lib/guest/layout.sx \
|
||||
/root/rose-ash/lib/guest/hm.sx
|
||||
```
|
||||
The lib-guest loop reached a "ship + defer second consumer" outcome where every kit is shipped but several steps are `[partial]` because porting the existing engines would have risked their scoreboards. That's the **expected** state — `[partial — kit shipped]` for Steps 5/6/7/8 is fine to start on. **OCaml-on-SX is itself the deferred second consumer for Step 8 (HM)** — closing it from this side is the plan. Only stop if any of those `lib/guest/*.sx` files are missing.
|
||||
|
||||
## Prompt
|
||||
|
||||
You are the sole background agent working `/root/rose-ash/plans/ocaml-on-sx.md`. You run in an isolated git worktree on branch `loops/ocaml`. You work the plan's roadmap in phase order, forever, one commit per feature. Push to `origin/loops/ocaml` after every commit.
|
||||
|
||||
## Restart baseline — check before iterating
|
||||
|
||||
1. Read `plans/ocaml-on-sx.md` — Roadmap + Progress log + Blockers tell you where you are.
|
||||
2. Run the pre-flight check above. If any of the listed `lib/guest/*.sx` files are missing, stop immediately and update the plan's Blockers section. `[partial — kit shipped]` status on Steps 5–8 is expected and fine to start on.
|
||||
3. `ls lib/ocaml/` — pick up from the most advanced file that exists. If the directory does not exist, you are at Phase 1.
|
||||
4. If `lib/ocaml/tests/*.sx` exist, run them via the epoch protocol against `sx_server.exe`. They must be green before new work.
|
||||
5. If `lib/ocaml/scoreboard.json` exists (Phase 5.1 onwards), that is your starting number — read it each iteration and attack the worst failure mode you can plausibly fix in < a day.
|
||||
|
||||
## The queue
|
||||
|
||||
Phase order per `plans/ocaml-on-sx.md`:
|
||||
|
||||
- **Phase 1** — tokenizer + parser (consuming `lib/guest/lex.sx` + `lib/guest/pratt.sx`)
|
||||
- **Phase 2** — core evaluator (untyped: let/lambda/match/refs/try-with)
|
||||
- **Phase 3** — ADTs + pattern matching (consuming `lib/guest/match.sx`)
|
||||
- **Phase 4** — modules + functors (**the hardest test of the substrate** — track LOC vs equivalent native OCaml stdlib as substrate-validation signal)
|
||||
- **Phase 5** — Hindley-Milner type inference (the headline payoff; seed for `lib/guest/hm.sx`)
|
||||
- **Phase 5.1** — vendor OCaml testsuite slice; create `lib/ocaml/conformance.sh` + `scoreboard.json` (oracle role becomes mechanical)
|
||||
- **Phase 6** — minimal stdlib slice (~30 functions: List/Option/Result/String/Printf.sprintf/Hashtbl)
|
||||
- **Phase 7** — Dream — **out of scope, see `plans/dream-on-sx.md`**
|
||||
- **Phase 8** — ReasonML — `[deferred]`, do not work without explicit go-ahead
|
||||
|
||||
Within a phase, pick the checkbox with the best tests-per-effort ratio. Once the scoreboard exists (Phase 5.1), it is your north star.
|
||||
|
||||
Every iteration: implement → test → commit → tick `[ ]` in plan → append Progress log → push → next.
|
||||
|
||||
## Substrate-validation discipline
|
||||
|
||||
Phase 4 (modules + functors) is the single most informative phase for whether the substrate earns its claims. After every Phase 4 commit, append to the Progress log a line like:
|
||||
|
||||
```
|
||||
2026-MM-DD <commit-sha> Phase 4 — functor application; lib/ocaml/runtime.sx +120 LOC, total Phase 4 LOC = 580.
|
||||
```
|
||||
|
||||
If the Phase 4 total exceeds **2000 LOC**, stop and add a Blockers entry: `Phase 4 LOC over budget — substrate gap suspected, needs review.` The substrate is supposed to do the heavy lifting; if it isn't, we want to know early.
|
||||
|
||||
## Ground rules (hard)
|
||||
|
||||
- **Scope:** only `lib/ocaml/**`, `lib/reasonml/**` (Phase 8 only, deferred), and `plans/ocaml-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, `lib/dream/**` (separate plan), `lib/guest/**` (read-only consumer), or other `lib/<lang>/`.
|
||||
- **Consume `lib/guest/`** wherever it covers a need (lex, pratt, match, ast). Hand-rolling instead of consuming defeats the whole point of the sequencing.
|
||||
- **NEVER call `sx_build`.** 600s watchdog will kill you before OCaml finishes. If `sx_server.exe` is broken, add a Blockers entry and stop.
|
||||
- **Shared-file issues** → plan's Blockers section with a minimal repro. Don't fix them.
|
||||
- **SX files:** `sx-tree` MCP tools ONLY. `sx_validate` after every edit. Never `Edit`/`Read`/`Write` on `.sx`.
|
||||
- **Worktree:** commit, then push to `origin/loops/ocaml`. Never touch `main`. Never push to `architecture`.
|
||||
- **Commit granularity:** one feature per commit. Short factual messages: `ocaml: functor application + 6 tests`.
|
||||
- **Plan file:** update Progress log + tick boxes every commit.
|
||||
- **If blocked** for two iterations on the same issue, add to Blockers and move on.
|
||||
- **Phase 7 (Dream) is forbidden.** Even tempting "while I'm here" detours into `lib/dream/` are forbidden. That plan is cold for a reason.
|
||||
- **Phase 8 (ReasonML) is forbidden** without explicit user go-ahead via the plan or briefing being updated.
|
||||
|
||||
## OCaml-specific gotchas
|
||||
|
||||
- **Strict, not lazy.** Argument evaluation is left-to-right and eager. `let x = (print_endline "a"; 1) in let y = (print_endline "b"; 2) in x + y` prints "a" then "b". Don't reuse Haskell-on-SX patterns that assume thunks.
|
||||
- **Curried by default.** `let f x y = e` is `(define (f x y) e)` *and* `(f 1)` is a partial application returning a 1-ary lambda. The CEK already handles this — don't auto-uncurry.
|
||||
- **`let rec` mutual recursion via `and`.** `let rec f x = ... and g x = ...` — both visible in each other's bodies. Map to nested `letrec` in SX.
|
||||
- **Pattern match is on the value, not on shape inference.** `match x with | None -> ... | Some y -> ...` — runtime tag dispatch via `lib/guest/match.sx`. Exhaustiveness error if no clause matches (Phase 3).
|
||||
- **Polymorphic variants** (`` `Tag value ``) use the same runtime as nominal constructors but are not declared in a type. Treat `` `A 1 `` as `(:A 1)` — same shape as `A 1` from `type t = A of int`.
|
||||
- **`open M` is scope merge, not import.** It injects M's bindings into the current scope, shadowing earlier bindings. Use `env-merge` not aliasing. Subsequent `M.x` references still work (M is still bound separately).
|
||||
- **First-class modules deferred to Phase 5.** Phase 4 modules are dicts; Phase 5 wraps them in a typed envelope. Don't try to do both at once.
|
||||
- **HM error messages are the test.** Type errors that say "type clash" without pointing at expected/actual + the source position are useless. Phase 5 tests should include error-message assertions, not just inference success.
|
||||
- **The reference oracle is the OCaml REPL on this machine.** When you're not sure what `let f x = ref x in let g = f 1 in (!g, !g)` should produce, run it in `ocaml` and match. Don't guess.
|
||||
|
||||
## General gotchas (all loops)
|
||||
|
||||
- SX `do` = R7RS iteration. Use `begin` for multi-expr sequences.
|
||||
- `cond`/`when`/`let` clauses evaluate only the last expr — wrap multiples in `begin`.
|
||||
- `env-bind!` creates a binding; `env-set!` mutates an existing one (walks scope chain).
|
||||
- `sx_validate` after every structural edit.
|
||||
- `list?` returns false on raw JS Arrays — host data must be SX-converted.
|
||||
- Shell heredoc `||` gets eaten — escape or use `case`.
|
||||
|
||||
## Style
|
||||
|
||||
- No comments in `.sx` unless non-obvious.
|
||||
- No new planning docs — update `plans/ocaml-on-sx.md` inline.
|
||||
- Short, factual commit messages (`ocaml: HM let-polymorphism (+11)`).
|
||||
- One feature per iteration. Commit. Log. Push. Next.
|
||||
|
||||
Go. Run the pre-flight check. If lib-guest is not done, stop and report. Otherwise read the plan, find the first unchecked `[ ]`, implement it.
|
||||
@@ -25,6 +25,23 @@ for rose-ash data (e.g. federation graph, content relationships).
|
||||
Dalmau "Datalog and Constraint Satisfaction".
|
||||
- **Commits:** one feature per commit. Keep `## Progress log` updated and tick boxes.
|
||||
|
||||
## Non-goals
|
||||
|
||||
Deliberately out of scope for this implementation. Real engines (Soufflé, Cozo, DDlog) include
|
||||
some of these; we accept they're missing and will note them in `Blockers` if a use case demands
|
||||
one later.
|
||||
|
||||
- **Function symbols** — keeps termination guaranteed and prevents collapse into Prolog.
|
||||
- **Disjunctive heads** (`p :- q. p :- r.` is fine; `p ; q :- r.` is not) — research extension.
|
||||
- **Well-founded semantics** — only stratified negation. Programs that aren't stratifiable are
|
||||
rejected at load time, not evaluated under WFS.
|
||||
- **Tabled top-down (SLG resolution)** — bottom-up only. If you want top-down with termination,
|
||||
use the Prolog implementation.
|
||||
- **Constraint Datalog** (Datalog over reals, intervals, finite domains) — research extension.
|
||||
- **Distributed evaluation / Differential Dataflow** — single-process fixpoint only. The rose-ash
|
||||
cross-service story (Phase 10) federates by querying each service's local Datalog instance and
|
||||
joining results, not by running a distributed fixpoint.
|
||||
|
||||
## Architecture sketch
|
||||
|
||||
```
|
||||
@@ -59,7 +76,8 @@ Key differences from Prolog:
|
||||
|
||||
### Phase 1 — tokenizer + parser
|
||||
- [ ] Tokenizer: atoms (lowercase/quoted), variables (uppercase/`_`), numbers, strings,
|
||||
operators (`:- `, `?-`, `,`, `.`), comments (`%`, `/* */`)
|
||||
operators (`:- `, `?-`, `,`, `.`), arithmetic + comparison operators
|
||||
(`+`, `-`, `*`, `/`, `<`, `<=`, `>`, `>=`, `=`, `!=`), comments (`%`, `/* */`)
|
||||
Note: no function symbol syntax (no nested `f(...)` in arg position).
|
||||
- [ ] Parser:
|
||||
- Facts: `parent(tom, bob).` → `{:head (parent tom bob) :body ()}`
|
||||
@@ -83,16 +101,55 @@ Key differences from Prolog:
|
||||
For each rule, for each combination of body tuples that unify, derive head tuple.
|
||||
Repeat until no new tuples added.
|
||||
- [ ] `dl-query` `db` `goal` → list of substitutions satisfying goal against derived DB
|
||||
- [ ] Tests: transitive closure (ancestor), sibling, same-generation — classic Datalog programs
|
||||
- [ ] **Safety analysis**: every variable in a rule head must also appear in a positive body
|
||||
literal; reject unsafe rules at `dl-add-rule!` time with a clear error pointing at the
|
||||
offending variable. Built-in predicates and negated atoms do not satisfy safety on their
|
||||
own (`p(X) :- X > 0.` is unsafe).
|
||||
- [ ] Tests: transitive closure (ancestor), sibling, same-generation — classic Datalog programs;
|
||||
safety violation rejection cases.
|
||||
|
||||
### Phase 4 — semi-naive evaluation (performance)
|
||||
### Phase 4 — built-in predicates + body arithmetic
|
||||
|
||||
Almost every real query needs `<`, `=`, simple arithmetic, and string comparisons in body
|
||||
position. These are not EDB lookups — they're constraints that filter bindings.
|
||||
|
||||
- [ ] Recognise built-in predicates in body: `(< X Y)`, `(<= X Y)`, `(> X Y)`, `(>= X Y)`,
|
||||
`(= X Y)`, `(!= X Y)` and arithmetic forms `(is Z (+ X Y))`, `(is Z (- X Y))`,
|
||||
`(is Z (* X Y))`, `(is Z (/ X Y))`.
|
||||
- [ ] Built-in evaluation in the fixpoint: at the join step, after binding variables from EDB
|
||||
lookups, evaluate built-ins as constraints. If any built-in fails or has unbound inputs,
|
||||
drop the candidate substitution.
|
||||
- [ ] **Safety extension**: `is` binds its left operand iff right operand is fully ground.
|
||||
`(< X Y)` requires both X and Y bound by some prior body literal — reject unsafe.
|
||||
- [ ] Wire arithmetic operators through to SX numeric primitives — no separate Datalog number
|
||||
tower.
|
||||
- [ ] Tests: range filters, arithmetic derivations (`(plus-one X Y :- ..., (is Y (+ X 1)))`),
|
||||
comparison-based queries, safety violation detection on `(p X) :- (< X 5).`
|
||||
|
||||
### Phase 5 — semi-naive evaluation (performance)
|
||||
- [ ] Delta sets: track newly derived tuples per iteration
|
||||
- [ ] Semi-naive rule: only join against delta tuples from last iteration, not full relation
|
||||
- [ ] Significant speedup for recursive rules — avoids re-deriving known tuples
|
||||
- [ ] `dl-stratify` `db` → dependency graph + SCC analysis → stratum ordering
|
||||
- [ ] Tests: verify semi-naive produces same results as naive; benchmark on large ancestor chain
|
||||
|
||||
### Phase 5 — stratified negation
|
||||
### Phase 6 — magic sets (goal-directed bottom-up)
|
||||
|
||||
Naive bottom-up evaluation derives **all** consequences of all rules before answering, even when
|
||||
the query touches a tiny slice of the EDB. Magic sets rewrite the program so the fixpoint only
|
||||
derives tuples relevant to the goal — a major perf win for "what's reachable from node X" style
|
||||
queries on large graphs.
|
||||
|
||||
- [ ] Adornments: annotate rule predicates with bound (`b`) / free (`f`) patterns based on how
|
||||
they're called (`ancestor^bf(tom, X)` vs `ancestor^ff(X, Y)`).
|
||||
- [ ] Magic transformation: for each adorned predicate, generate a `magic_<pred>` relation and
|
||||
rewrite rule bodies to filter through it. Seed with `magic_<query-pred>(<bound-args>)`.
|
||||
- [ ] Sideways information passing strategy (SIPS): left-to-right by default; pluggable.
|
||||
- [ ] Optional pass — guarded behind `(dl-set-strategy! db :magic)`; default remains semi-naive.
|
||||
- [ ] Tests: ancestor query from a single root on a 10k-node graph — magic-rewritten version
|
||||
should be O(reachable) instead of O(graph). Equivalence vs naive on small inputs.
|
||||
|
||||
### Phase 7 — stratified negation
|
||||
- [ ] Dependency graph analysis: which relations depend on which (positively or negatively)
|
||||
- [ ] Stratification check: error if negation is in a cycle (non-stratifiable program)
|
||||
- [ ] Evaluation: process strata in order — lower stratum fully computed before using its
|
||||
@@ -101,7 +158,7 @@ Key differences from Prolog:
|
||||
- [ ] Tests: non-member (`not(member(X,L))`), colored-graph (`not(same-color(X,Y))`),
|
||||
stratification error detection
|
||||
|
||||
### Phase 6 — aggregation (Datalog+)
|
||||
### Phase 8 — aggregation (Datalog+)
|
||||
- [ ] `count(X, Goal)` → number of distinct X satisfying Goal
|
||||
- [ ] `sum(X, Goal)` → sum of X values satisfying Goal
|
||||
- [ ] `min(X, Goal)` / `max(X, Goal)` → min/max of X satisfying Goal
|
||||
@@ -109,7 +166,7 @@ Key differences from Prolog:
|
||||
- [ ] Aggregation breaks stratification — evaluate in a separate post-fixpoint pass
|
||||
- [ ] Tests: social network statistics, grade aggregation, inventory sums
|
||||
|
||||
### Phase 7 — SX embedding API
|
||||
### Phase 9 — SX embedding API
|
||||
- [ ] `(dl-program facts rules)` → database from SX data directly (no parsing required)
|
||||
```
|
||||
(dl-program
|
||||
@@ -123,7 +180,7 @@ Key differences from Prolog:
|
||||
- [ ] Integration demo: federation graph query — `(ancestor actor1 actor2)` over
|
||||
rose-ash ActivityPub follow relationships
|
||||
|
||||
### Phase 8 — Datalog as a query language for rose-ash
|
||||
### Phase 10 — Datalog as a query language for rose-ash
|
||||
- [ ] Schema: map SQLAlchemy model relationships to Datalog EDB facts
|
||||
(e.g. `(follows user1 user2)`, `(authored user post)`, `(tagged post tag)`)
|
||||
- [ ] Loader: `dl-load-from-db!` — query PostgreSQL, populate Datalog EDB
|
||||
|
||||
110
plans/dream-on-sx.md
Normal file
110
plans/dream-on-sx.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Dream-on-SX: OCaml's Dream web framework on the SX CEK
|
||||
|
||||
`[deferred — depends on ocaml-on-sx + a target user]`
|
||||
|
||||
Carved out of `plans/ocaml-on-sx.md`. The OCaml-on-SX plan was scoped down to **substrate validation + HM + reference oracle** (Phases 1–5 + minimal stdlib slice). Dream is the practical alternative-stack story — the opposite framing — and only makes sense if a real user wants to write rose-ash apps in OCaml/Dream.
|
||||
|
||||
**Do not start without:**
|
||||
1. OCaml-on-SX Phases 1–5 + Phase 6 minimal stdlib green.
|
||||
2. A concrete target user. "OCaml programmers in general" is not a target. "Person X wants to write feature Y on rose-ash in Dream" is.
|
||||
|
||||
If those conditions are not met, this plan stays cold.
|
||||
|
||||
## Why this might be worth doing (when the time comes)
|
||||
|
||||
Dream is the cleanest middleware-shaped HTTP framework in any language:
|
||||
- `handler = request -> response promise`
|
||||
- `middleware = handler -> handler`
|
||||
- `m1 @@ m2 @@ handler` — left-fold composition
|
||||
|
||||
It maps onto SX with almost no impedance — `@@` is function composition, `request → response promise` is `(perform (:http-respond ...))`, middleware chain is plain SX function composition. So the integration cost is low *if* the OCaml-on-SX foundation is in place.
|
||||
|
||||
The user-facing story: rose-ash users who'd never touch s-expressions might write Dream/OCaml apps that integrate with the same federation, auth, and storage primitives. Demo: a Dream app serving sx.rose-ash.com — the framework that describes the runtime it runs on.
|
||||
|
||||
## Dream semantic mappings
|
||||
|
||||
| Dream construct | SX mapping |
|
||||
|----------------|-----------|
|
||||
| `handler = request -> response promise` | `(fn (req) (perform (:http-respond ...)))` |
|
||||
| `middleware = handler -> handler` | `(fn (next) (fn (req) ...))` |
|
||||
| `Dream.router [routes]` | `(ocaml-dream-router routes)` — dispatch on method+path |
|
||||
| `Dream.get "/path" h` | route record `{:method "GET" :path "/path" :handler h}` |
|
||||
| `Dream.scope "/p" [ms] [rs]` | prefix mount with middleware chain |
|
||||
| `Dream.param req "name"` | path param extracted during routing |
|
||||
| `m1 @@ m2 @@ handler` | `(m1 (m2 handler))` — left-fold composition |
|
||||
| `Dream.session_field req "k"` | `(perform (:session-get req "k"))` |
|
||||
| `Dream.set_session_field req "k" v` | `(perform (:session-set req "k" v))` |
|
||||
| `Dream.flash req` | `(perform (:flash-get req))` |
|
||||
| `Dream.form req` | `(perform (:form-parse req))` — returns Ok/Error ADT |
|
||||
| `Dream.websocket handler` | `(perform (:websocket handler))` |
|
||||
| `Dream.run handler` | starts SX HTTP server with handler as root |
|
||||
|
||||
## Roadmap
|
||||
|
||||
The five types: `request`, `response`, `handler = request -> response`, `middleware = handler -> handler`, `route`. Everything else is a function over these.
|
||||
|
||||
- [ ] **Core types** in `lib/dream/types.sx`: request/response records, route record.
|
||||
- [ ] **Router** in `lib/dream/router.sx`:
|
||||
- `dream-get path handler`, `dream-post path handler`, etc. for all HTTP methods.
|
||||
- `dream-scope prefix middlewares routes` — prefix mount with middleware chain.
|
||||
- `dream-router routes` — dispatch tree, returns handler; no match → 404.
|
||||
- Path param extraction: `:name` segments, `**` wildcard.
|
||||
- `dream-param req name` — retrieve matched path param.
|
||||
- [ ] **Middleware** in `lib/dream/middleware.sx`:
|
||||
- `dream-pipeline middlewares handler` — compose middleware left-to-right.
|
||||
- `dream-no-middleware` — identity.
|
||||
- Logger: `(dream-logger next req)` — logs method, path, status, timing.
|
||||
- Content-type sniffer.
|
||||
- [ ] **Sessions** in `lib/dream/session.sx`:
|
||||
- Cookie-backed session middleware.
|
||||
- `dream-session-field req key`, `dream-set-session-field req key val`.
|
||||
- `dream-invalidate-session req`.
|
||||
- [ ] **Flash messages** in `lib/dream/flash.sx`:
|
||||
- `dream-flash-middleware` — single-request cookie store.
|
||||
- `dream-add-flash-message req category msg`.
|
||||
- `dream-flash-messages req` — returns list of `(category, msg)`.
|
||||
- [ ] **Forms + CSRF** in `lib/dream/form.sx`:
|
||||
- `dream-form req` — returns `(Ok fields)` or `(Err :csrf-token-invalid)`.
|
||||
- `dream-multipart req` — streaming multipart form data.
|
||||
- CSRF middleware: stateless signed tokens, session-scoped.
|
||||
- `dream-csrf-tag req` — returns hidden input fragment for SX templates.
|
||||
- [ ] **WebSockets** in `lib/dream/websocket.sx`:
|
||||
- `dream-websocket handler` — upgrades request; handler `(fn (ws) ...)`.
|
||||
- `dream-send ws msg`, `dream-receive ws`, `dream-close ws`.
|
||||
- [ ] **Static files:** `dream-static root-path` — serves files, ETags, range requests.
|
||||
- [ ] **`dream-run`**: wires root handler into SX's `perform (:http-listen ...)`.
|
||||
- [ ] **Demos** in `lib/dream/demos/`:
|
||||
- `hello.ml` → `lib/dream/demos/hello.sx`: "Hello, World!" route.
|
||||
- `counter.ml` → `lib/dream/demos/counter.sx`: in-memory counter with sessions.
|
||||
- `chat.ml` → `lib/dream/demos/chat.sx`: multi-room WebSocket chat.
|
||||
- `todo.ml` → `lib/dream/demos/todo.sx`: CRUD list with forms + CSRF.
|
||||
- [ ] Tests in `lib/dream/tests/`: routing dispatch, middleware composition, session round-trip, CSRF accept/reject, flash read-after-write — 60+ tests.
|
||||
|
||||
## Stdlib additions Dream will need
|
||||
|
||||
Dream pushes beyond OCaml-on-SX's Phase 6 minimal stdlib slice. When this plan activates, OCaml-on-SX gets a follow-on phase that adds at minimum:
|
||||
|
||||
- `Bytes` (binary buffers — request bodies, websocket frames)
|
||||
- `Buffer` (mutable string building)
|
||||
- `Format` (full pretty-printer, not just `Printf.sprintf`)
|
||||
- More `String` (`index_opt`, `contains`, `starts_with`, `ends_with`, `replace_all`)
|
||||
- `Sys` (`argv`, `getenv_opt`, `getcwd`)
|
||||
- `Hashtbl` extensions (`iter`, `fold`, `length`, `remove`)
|
||||
- `Map.Make` / `Set.Make` functors
|
||||
|
||||
Confirm scope before starting; some of these may be addable as Dream-internal helpers rather than full stdlib modules.
|
||||
|
||||
## Ground rules
|
||||
|
||||
- **Scope:** only `lib/dream/**` and `plans/dream-on-sx.md`. Plus the stdlib additions listed above which land in `lib/ocaml/runtime.sx`.
|
||||
- **Hard prerequisite:** OCaml-on-SX Phases 1–5 + Phase 6 minimal stdlib. Verify scoreboard before starting.
|
||||
- **SX files:** `sx-tree` MCP tools only.
|
||||
- **Don't reinvent the SX HTTP server.** Dream wraps the existing `perform (:http-listen ...)` — it does not implement its own listener loop.
|
||||
|
||||
## Progress log
|
||||
|
||||
_(awaiting activation conditions)_
|
||||
|
||||
## Blockers
|
||||
|
||||
_(none yet — plan is cold)_
|
||||
130
plans/idris-on-sx.md
Normal file
130
plans/idris-on-sx.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# Idris-on-SX: dependent types as substrate stress test
|
||||
|
||||
The single most substrate-stretching language in the set. Dependent types unify the term and type universes — types may depend on values, normalisation becomes part of type-checking, decidable equality matters, totality has to be checked. **Idris 2** is the pragmatic choice: smaller than Agda, more accessible than Coq, designed for general programming rather than proof-only.
|
||||
|
||||
**The chisel:** *evidence*. Currently every typed guest in the set (OCaml, Haskell, Elm, Koka, Reasonml) lives in HM-or-rank-1 territory — types are simple-enough algebra. Dependent types force the substrate to think about *terms as evidence*: what does it mean for a value to *witness* a type? what's a normal form? when are two terms equal up to computation?
|
||||
|
||||
**What this exposes about the substrate:**
|
||||
- Whether SX values can carry typing evidence efficiently, or whether a separate elaboration phase is required.
|
||||
- Whether normalisation (beta, iota, delta) is fast enough at type-check time — implicates JIT, allocation, and frame management.
|
||||
- Whether decidable equality of arbitrary values is reachable.
|
||||
- Whether erasure (proofs deleted at runtime) can be expressed cleanly given SX's value model.
|
||||
- Whether HM (lib/guest/typed/hm.sx) extends cleanly to bidirectional dependent inference, or whether they're genuinely different machinery.
|
||||
|
||||
**End-state goal:** **core Idris 2** — Pi types, indexed families, dependent pattern matching, totality checking, erasure, holes for interactive development. Not the full Idris 2 stdlib; a faithful core that runs idiomatic dependent programs.
|
||||
|
||||
## Ground rules
|
||||
- Scope: `lib/idris/**` and `plans/idris-on-sx.md` only. Substrate gaps → `sx-improvements.md`, do not fix from this plan.
|
||||
- Consumes from `lib/guest/`: `core/lex`, `core/pratt` (Idris has indentation but Pratt for ops), `core/match`, `layout/` (Idris is whitespace-sensitive), `typed/hm.sx` (as a starting point that gets extended).
|
||||
- **Will propose** a new sub-layer `lib/guest/dependent/` — universes, conversion checking, normalisation, bidirectional elaboration. A second consumer is genuinely speculative for now; accept "second user TBD" until a Lean-fragment or Agda-fragment plan emerges.
|
||||
- Branch: `loops/idris`. Standard worktree pattern.
|
||||
|
||||
## Architecture sketch
|
||||
|
||||
```
|
||||
Idris source text
|
||||
│
|
||||
▼
|
||||
lib/idris/parser.sx — Haskell-ish, layout-sensitive, type-level syntax
|
||||
│ (consumes lib/guest/layout, lib/guest/pratt)
|
||||
▼
|
||||
lib/idris/elaborate.sx — surface → core: implicit args, holes, do-notation
|
||||
│
|
||||
▼
|
||||
lib/idris/check.sx — bidirectional dependent type-checker
|
||||
│ infer / check modes, conversion via normalisation
|
||||
▼
|
||||
lib/idris/normalise.sx — NbE (normalisation by evaluation): values are
|
||||
│ semantic, neutral terms hold reflected applications
|
||||
▼
|
||||
lib/idris/runtime.sx — erased terms run via standard SX evaluation;
|
||||
constructors as tagged ADTs from sx-improvements
|
||||
```
|
||||
|
||||
## Semantic mappings
|
||||
|
||||
| Idris construct | SX mapping |
|
||||
|----------------|-----------|
|
||||
| `(x : Nat) -> P x` | dependent function type — first-class `{:type :pi :name x :domain Nat :codomain (P x)}` |
|
||||
| `\x => body` | `(fn (x) body)` — same as before |
|
||||
| `data Vect : Nat -> Type -> Type` | indexed family — `define-type` extension carrying index |
|
||||
| `Vect (S n) a` | applied type former — neutral term until index is ground |
|
||||
| `case x of pat => e` | dependent pattern match — refines indices in branches |
|
||||
| `(x : A) ** B x` | dependent pair — `{:type :sigma :name x :first A :second (B x)}` |
|
||||
| `?hole` | unfilled term — type-checker reports goal type |
|
||||
| `Refl : x = x` | propositional equality witness |
|
||||
| `total` | totality check — termination + coverage |
|
||||
|
||||
## Roadmap
|
||||
|
||||
### Phase 1 — Parser + layout
|
||||
- [ ] Lexer/parser via `lib/guest/lex` + `lib/guest/pratt`.
|
||||
- [ ] Layout via `lib/guest/layout` — Idris uses indentation similar to Haskell.
|
||||
- [ ] Type signatures `name : Type`, function definitions with multiple clauses.
|
||||
- [ ] Tests in `lib/idris/tests/parse.sx`.
|
||||
|
||||
### Phase 2 — Untyped evaluator (sanity check)
|
||||
- [ ] Strip types entirely; run programs as untyped lambda calculus + ADTs.
|
||||
- [ ] Goal: factorial, list ops, recursive datatypes work without type-checking.
|
||||
- [ ] Confirms the runtime story before tackling the type checker.
|
||||
|
||||
### Phase 3 — Bidirectional simply-typed checking + universes
|
||||
- [ ] Hierarchy of universes `Type 0 : Type 1 : Type 2 : ...`.
|
||||
- [ ] Check mode (push expected type), infer mode (synthesise type).
|
||||
- [ ] Variable / lambda / application / annotation rules.
|
||||
- [ ] Tests: simple programs that succeed/fail type-check.
|
||||
|
||||
### Phase 4 — Pi types + dependent functions
|
||||
- [ ] Pi as a first-class type former.
|
||||
- [ ] Application instantiates the codomain at the argument value.
|
||||
- [ ] Conversion check: are two types equal up to normalisation?
|
||||
- [ ] Implement NbE — values are either canonical (constructors, functions) or neutral (stuck applications); conversion compares via reify.
|
||||
- [ ] Tests: `id : (a : Type) -> a -> a`, `const`, `flip`.
|
||||
|
||||
### Phase 5 — Indexed families + dependent pattern matching
|
||||
- [ ] `data Vect : Nat -> Type -> Type` — constructors carry index.
|
||||
- [ ] Pattern match refines indices in branches (`Cons` case has `n = S k`).
|
||||
- [ ] Coverage check (incomplete matches reported).
|
||||
- [ ] Tests: `head : Vect (S n) a -> a` (rejects empty vectors at compile time).
|
||||
|
||||
### Phase 6 — Totality / termination
|
||||
- [ ] Termination checker: structural recursion, sized types or call graphs.
|
||||
- [ ] Productivity for codata.
|
||||
- [ ] `total` / `partial` annotations.
|
||||
- [ ] Tests: recursive programs that pass / fail termination.
|
||||
|
||||
### Phase 7 — Erasure
|
||||
- [ ] Mark proof-only arguments as erased.
|
||||
- [ ] Runtime evaluation skips erased subterms.
|
||||
- [ ] Tests: vector head runs at the speed of list head (proof argument deleted).
|
||||
|
||||
### Phase 8 — Holes + interactive development
|
||||
- [ ] `?name` produces a hole with reported goal type.
|
||||
- [ ] Tactic-like elaboration step (small set: `intro`, `apply`, `case-split`).
|
||||
- [ ] Tests: develop a program by progressive hole-filling.
|
||||
|
||||
### Phase 9 — Propose `lib/guest/dependent/`
|
||||
- [ ] Identify reusable universe machinery, conversion-checking framework, NbE infrastructure.
|
||||
- [ ] Hold off on extraction until a second consumer (Lean-fragment, Agda-fragment) is plausible.
|
||||
|
||||
## lib/guest feedback loop
|
||||
|
||||
**Consumes:** `core/lex`, `core/pratt`, `core/match`, `layout/`, `typed/hm.sx` (as starting point).
|
||||
|
||||
**Stresses substrate:** value normalisation cost (every type-check step normalises); decidable equality across closures; whether ADT primitive (`define-type` from sx-improvements Phase 3) handles indexed families.
|
||||
|
||||
**May propose:** `lib/guest/dependent/` sub-layer — universes, NbE, conversion checking, bidirectional elaboration. Speculative second consumer until Lean/Agda-fragment plans materialise.
|
||||
|
||||
**What it teaches:** whether SX's substrate scales to type-level computation. Most languages have a clean separation: types are static, terms are dynamic. Idris collapses them. If SX can host this in <5000 lines, the substrate is genuinely paradigm-agnostic. If it can't, "paradigm-agnostic" was overclaiming.
|
||||
|
||||
## References
|
||||
- Brady, "Type-Driven Development with Idris" (Manning, 2017).
|
||||
- Idris 2 source: https://github.com/idris-lang/Idris2
|
||||
- Coquand & Dybjer "An Algorithm for Type-Checking Dependent Types" (NbE foundations).
|
||||
- Christiansen, "Functional Programming in Lean" (cleanest exposition of bidirectional dependent checking).
|
||||
|
||||
## Progress log
|
||||
_(awaiting completion of Kernel-on-SX or substrate ADT primitive maturity, whichever happens first)_
|
||||
|
||||
## Blockers
|
||||
_(speculative — main risk is substrate normalisation cost)_
|
||||
114
plans/kernel-on-sx.md
Normal file
114
plans/kernel-on-sx.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# Kernel-on-SX: first-class everything
|
||||
|
||||
The natural successor to SX's recently-completed env-as-value work (sx-improvements Phase 4). Kernel — John Shutt's reformulation of Lisp from his 2010 PhD — pushes *first-class* all the way: environments, evaluators, special forms (operatives), lambda variants are all runtime values, manipulable by programs. SX already has env-as-value; Kernel is what env-as-value looks like *all the way*.
|
||||
|
||||
**The chisel:** *reflection*. Every language in the current set treats some part of itself as fixed and ineffable — Common Lisp's special forms, Erlang's process model, OCaml's modules. Kernel reifies more of itself than any other language does. Implementing it stresses the substrate's *self-knowledge*: which parts of evaluation does SX expose to user programs, and which stay opaque?
|
||||
|
||||
**What this exposes about the substrate:**
|
||||
- Whether `eval-expr` can be called as a primitive on user-supplied environments without breaking invariants.
|
||||
- Whether CEK frames can be reified as values (they currently aren't).
|
||||
- Whether special-form dispatch can be table-driven and user-extensible at runtime.
|
||||
- Whether the macro hygiene story extends to Shutt's "hygienic operatives" (operatives that don't capture).
|
||||
|
||||
**End-state goal:** Kernel's R-1RK core — `$vau`/`$lambda`/`wrap`/`unwrap`, first-class environments, the applicative–operative distinction, the standard environment, encapsulations.
|
||||
|
||||
## Ground rules
|
||||
- Scope: `lib/kernel/**` and `plans/kernel-on-sx.md` only. Substrate work belongs to `sx-improvements.md` — if a feature is missing, file it there, don't fix from this plan.
|
||||
- Consumes from `lib/guest/`: `core/lex.sx`, `core/pratt.sx` (s-expression-shaped, minimal demand), `core/ast.sx`, `core/match.sx`.
|
||||
- **May propose** a new sub-layer `lib/guest/reflective/` — environment reification helpers, applicative-vs-operative dispatch, evaluator continuation protocols. A second consumer would be needed; candidates are a hypothetical "MetaScheme" or a Common-Lisp port that exposes its evaluator.
|
||||
- Branch: `loops/kernel`. Standard worktree pattern.
|
||||
|
||||
## Architecture sketch
|
||||
|
||||
```
|
||||
Kernel source text (S-expression syntax)
|
||||
│
|
||||
▼
|
||||
lib/kernel/parser.sx — bog-standard s-expr reader
|
||||
│
|
||||
▼
|
||||
lib/kernel/eval.sx — kernel-eval: walks the AST, threads first-class env
|
||||
│ dispatches to operatives via env-bound bindings, not
|
||||
│ a hardcoded switch
|
||||
▼
|
||||
lib/kernel/runtime.sx — applicative/operative tagged values, wrap/unwrap,
|
||||
│ standard environment construction, encapsulations
|
||||
▼
|
||||
SX CEK evaluator
|
||||
```
|
||||
|
||||
## Semantic mappings
|
||||
|
||||
| Kernel construct | SX mapping |
|
||||
|------------------|-----------|
|
||||
| `($lambda (x) body)` | applicative: `(make-applicative (fn (x) body))` — args evaluated |
|
||||
| `($vau (x) e body)` | operative: `(make-operative (fn (x e) body))` — args UN-evaluated, dynamic env passed as `e` |
|
||||
| `(wrap op)` | applicative wrapping an operative: evaluate args, then call op |
|
||||
| `(unwrap app)` | get the underlying operative of an applicative |
|
||||
| `($define! x v)` | operative: bind `x` to `v` in dynamic env |
|
||||
| `(eval expr env)` | call `kernel-eval` on `expr` in `env` — first-class |
|
||||
| `(make-environment)` | fresh empty env |
|
||||
| `(get-current-environment)` | reify the calling env (via SX env-as-value) |
|
||||
| `($if c t e)` | operative: evaluate `c`, then `t` or `e` in dynamic env |
|
||||
|
||||
The whole interesting thing: there are no special forms hardcoded in the evaluator. `$if`, `$define!`, `$lambda` are all *operatives* bound in the standard environment. User code can rebind them. The evaluator is just `lookup-and-call`.
|
||||
|
||||
## Roadmap
|
||||
|
||||
### Phase 1 — Parser
|
||||
- [ ] S-expression reader with the standard atoms (number, string, symbol, boolean, nil) and lists.
|
||||
- [ ] Reader macros optional; defer to Phase 6.
|
||||
- [ ] Tests in `lib/kernel/tests/parse.sx`.
|
||||
|
||||
### Phase 2 — Core evaluator with first-class environments
|
||||
- [ ] `kernel-eval expr env` — primary entry, walks AST, threads env as a value.
|
||||
- [ ] Symbol lookup → environment value (using SX env-as-value primitives).
|
||||
- [ ] List → look up head, dispatch on tag (applicative vs operative).
|
||||
- [ ] No hardcoded special forms — even `if`/`define`/`lambda` are env-bound.
|
||||
- [ ] Tests in `lib/kernel/tests/eval.sx`.
|
||||
|
||||
### Phase 3 — `$vau` / `$lambda` / `wrap` / `unwrap`
|
||||
- [ ] Operative tagged value: `{:type :operative :params :env-param :body :static-env}`.
|
||||
- [ ] Applicative tagged value wraps an operative + the "evaluate args first" contract.
|
||||
- [ ] `$vau` builds operatives; `$lambda` is `wrap` ∘ `$vau`.
|
||||
- [ ] `wrap` / `unwrap` round-trip cleanly.
|
||||
- [ ] Tests: define a custom operative, define a custom applicative on top of it.
|
||||
|
||||
### Phase 4 — Standard environment
|
||||
- [ ] Standard env construction: bind `$if`, `$define!`, `$lambda`, `$vau`, `wrap`, `unwrap`, `eval`, `make-environment`, `get-current-environment`, plus arithmetic and list primitives.
|
||||
- [ ] Tests: classic Kernel programs (factorial, list operations, environment manipulation).
|
||||
|
||||
### Phase 5 — Encapsulations
|
||||
- [ ] `make-encapsulation-type` returns three operatives: encapsulator, predicate, decapsulator. Standard Kernel idiom for opaque types.
|
||||
- [ ] Tests: implement promises, streams, or simple modules via encapsulations.
|
||||
|
||||
### Phase 6 — Hygienic operatives (Shutt's later work)
|
||||
- [ ] Operatives that don't capture caller bindings — uses scope sets / frame stamps to track provenance.
|
||||
- [ ] Bridge to SX's hygienic macro story; possibly extends `lib/guest/reflective/` with hygiene primitives.
|
||||
- [ ] Tests: write an operative that introduces a binding and verify it doesn't shadow caller's same-named bindings.
|
||||
|
||||
### Phase 7 — Propose `lib/guest/reflective/`
|
||||
- [ ] Once Phase 3 lands and stabilises, identify which env-reification + dispatch primitives are reusable. Candidate API: `make-operative`, `make-applicative`, `with-current-env`, `eval-in-env`.
|
||||
- [ ] Find a second consumer (Common-Lisp's macro-expansion evaluator? a metacircular Scheme variant? a future plan).
|
||||
- [ ] Only extract once two consumers exist (per stratification rule).
|
||||
|
||||
## lib/guest feedback loop
|
||||
|
||||
**Consumes:** `core/lex`, `core/pratt`, `core/ast`, `core/match`.
|
||||
|
||||
**Stresses substrate:** env-as-value (Phase 4 of sx-improvements) under heavy use; `eval` as a primitive on user environments; potentially CEK frame reification.
|
||||
|
||||
**May propose:** `lib/guest/reflective/` sub-layer — environment manipulation, evaluator-as-value, applicative/operative dispatch protocols.
|
||||
|
||||
**What it teaches:** whether SX's recent env-as-value direction generalises to "evaluator-as-value." If Kernel implements cleanly in <2000 lines, env-as-value is real. If it requires substrate fixes at every turn, env-as-value was incomplete and the substrate is telling us what's missing.
|
||||
|
||||
## References
|
||||
- Shutt, "Fexprs as the basis of Lisp function application" (PhD thesis, 2010).
|
||||
- Kernel Report (R-1RK): https://web.cs.wpi.edu/~jshutt/kernel.html
|
||||
- Klisp implementation (Andres Navarro) — pragmatic reference.
|
||||
|
||||
## Progress log
|
||||
_(awaiting Phase 1 — depends on stable env-as-value substrate state)_
|
||||
|
||||
## Blockers
|
||||
_(none yet — main risk is substrate gap discovery during Phase 2)_
|
||||
@@ -1,7 +1,9 @@
|
||||
# lib/guest — shared toolkit for SX-hosted languages
|
||||
# lib/guest — the metatheory layer for SX-hosted languages
|
||||
|
||||
Extract the duplicated plumbing across `lib/{haskell,common-lisp,erlang,prolog,js,lua,smalltalk,tcl,forth,ruby,apl,hyperscript}` into a small, composable kit so language N+1 costs ~200 lines instead of ~2000, without regressing any existing conformance scoreboard.
|
||||
|
||||
**This is a long-running, accreting plan.** Phase 0–3 (below) is the bootstrapping extraction — pulling the most obvious shared plumbing out of existing guests. Phase B onwards (see Stratification) is the ongoing accretion: codifying the universal patterns rose-ash's languages share, stratified by audience, refined continuously by pairs of new language consumers. The plan does not have a "done" state. The closest equivalent is "no two languages currently disagree about an abstraction in lib/guest" — and that's a moving target as new languages come online.
|
||||
|
||||
Branch: `architecture`. SX files via `sx-tree` MCP only. Never edit generated files.
|
||||
|
||||
## Thesis
|
||||
@@ -10,7 +12,64 @@ The substrate (CEK, hygienic macros, records, delimited continuations, IO suspen
|
||||
|
||||
**Canaries:** Lua (small, conventional expression-grammar — exercises lex/Pratt/AST) and Prolog (paradigm-different — exercises pattern-match/unification). The two-canary rule prevents Lua-shaped abstractions.
|
||||
|
||||
**Two-language rule:** no extraction is merged until **two** guests consume it.
|
||||
**Two-language rule:** no extraction is merged until **two** guests consume it. The rule scales with the universality claim — see *Stratification* for layer-appropriate pairs.
|
||||
|
||||
## Architectural framing — the layered stack
|
||||
|
||||
Rose-ash stratifies into five layers, each with a different invariant, audience, and time horizon. The same operating principles (dependency direction, two-consumer rule, layered editorial bar) work at every layer.
|
||||
|
||||
| Layer | rose-ash location | Time horizon | Audience |
|
||||
|-------|-------------------|--------------|----------|
|
||||
| **Substrate** (SX) | `spec/`, `hosts/` | years | platform maintainers |
|
||||
| **lib/guest** (language metatheory) | `lib/guest/` | years, slower than substrate | guest-language authors |
|
||||
| **Languages** | `lib/<lang>/` | months–years | application authors |
|
||||
| **shared/** (application metatheory) | `shared/` | months | service authors |
|
||||
| **Applications** | `blog/`, `market/`, `cart/`, `events/`, `federation/`, `account/`, `orders/`, `artdag/` | weeks–months | village members |
|
||||
|
||||
What each layer *is*:
|
||||
|
||||
- **Substrate (SX)** — values, evaluation, continuations, effects, hygienic macros, reactivity. The *physics* of the platform. Bugs here are catastrophic for everyone.
|
||||
- **lib/guest** — patterns that recur across paradigms: pattern matching, lexical primitives, precedence parsing, type inference, layout algorithms, effect handler protocols, module dispatch. *Applied PL theory.* Bugs only affect adopters; non-consumers don't care.
|
||||
- **Languages** — specific syntactic and semantic commitments that *are* a particular language. The user-facing surface for code authoring.
|
||||
- **shared/ (application metatheory)** — patterns that recur across domains: app factory, OAuth flow, ActivityPub, internal HMAC channel, fragments, sessions. Mature counterpart of what lib/guest is becoming, just at the application layer. The two-consumer rule there is already passed (every service is a consumer).
|
||||
- **Applications** — the village system itself. Federation, blog, market, events, etc. The proof point that justifies all the layers below.
|
||||
|
||||
This five-layer separation is unusually clean. Most platforms collapse two adjacent layers — JVM and BEAM are pure substrate (no shared metatheory layer), Lisp images and Smalltalk environments bundle substrate + metatheory, conventional web stacks merge "shared infrastructure" with "applications." Racket's `#lang` machinery is the closest analogue at the lib/guest boundary. Treating each layer as a deliberately separate stratum is a design choice, not a code-organisation accident.
|
||||
|
||||
### Dependency direction (strict, at every boundary)
|
||||
|
||||
Higher layers may use lower; lower layers must not know higher exists.
|
||||
|
||||
- Applications import from `shared/`. `shared/` doesn't know which application is using it.
|
||||
- `shared/` and applications import from languages (via SX modules and the host runtime). Languages don't know what application calls them.
|
||||
- Languages import from lib/guest. lib/guest doesn't know which language is consuming it.
|
||||
- lib/guest uses SX primitives. SX doesn't import from lib/guest.
|
||||
|
||||
Same invariant that makes substrate/metatheory separation work in PL theory, applied recursively up the stack. Violations show up as cyclic imports or as suspiciously language-specific code in `lib/guest/`, suspiciously domain-specific code in `shared/`, etc.
|
||||
|
||||
### Two-consumer rule, recursive
|
||||
|
||||
The pair-validation discipline applies at every layer, with audience-appropriate pairs:
|
||||
|
||||
- An entry in `lib/guest/core/` needs two consumers from different paradigms (e.g. lua + prolog).
|
||||
- An entry in `lib/guest/typed/` needs two typed consumers.
|
||||
- A pattern in `shared/` needs two services using it (largely already enforced — auth/HMAC/AP are used everywhere).
|
||||
- An application's reusable abstraction promotion to `shared/` should happen only after a second domain wants the same shape.
|
||||
|
||||
At every layer, "shared between two consumers we happen to have" is not enough — the pair must be appropriate to the universality being claimed.
|
||||
|
||||
### Editorial bar
|
||||
|
||||
An entry belongs at layer N only if it codifies a piece of universal-or-near-universal pattern *for that layer's audience*. Same bar at every level; just the meaning of "universal" changes — universal-across-paradigms for lib/guest, universal-across-services for shared/, universal-across-domains for application metatheory.
|
||||
|
||||
### Leverage versus concreteness
|
||||
|
||||
The two directions matter at every layer.
|
||||
|
||||
- **Leverage compounds downward.** A substrate fix benefits every layer above. A lib/guest fix benefits every consuming language. A `shared/` fix benefits every service. So the highest-leverage work is always the layer that *enables* the most above it.
|
||||
- **Concreteness flows upward.** Applications are what the village actually uses; substrate is invisible to them. Each layer is judged by its appropriate audience: substrate by correctness and speed, lib/guest by paradigm-coverage, languages by ergonomic fit, `shared/` by service reuse, applications by real users on real use cases.
|
||||
|
||||
The pleasant property: once you internalise the operating discipline at one layer, you know how to operate at every other. Pair-driven extraction. Two-consumer rule scaled to the layer's universality. Higher-uses-lower invariant. Codify-don't-just-deduplicate. The lib/guest plan is a working example of these principles applied at the metatheory layer; the same playbook applies all the way up.
|
||||
|
||||
## Current baseline
|
||||
|
||||
@@ -34,6 +93,10 @@ The baseline only needs to be re-snapshotted when the substrate (`spec/**`, `hos
|
||||
|
||||
---
|
||||
|
||||
## Phase A — Bootstrapping extraction (Phases 0–3 below)
|
||||
|
||||
The following four phases (0/1/2/3) are the bootstrap — pulling the most obvious shared plumbing out of existing guests. Largely shipped; partial-status entries are deferred ports waiting for their natural consumer (datalog, minikanren, ocaml, etc.) to close them. Phase B (Stratification) is the long-running successor.
|
||||
|
||||
## Phase 0 — Baseline snapshot (one-shot)
|
||||
|
||||
### Step 0: Snapshot every guest's scoreboard
|
||||
@@ -147,6 +210,82 @@ Extract from `haskell/infer.sx`. Algorithm W or J, generalisation, instantiation
|
||||
|
||||
---
|
||||
|
||||
## Phase B — Stratification (long-running)
|
||||
|
||||
lib/guest itself decomposes by audience. Phase B accepts that and codifies the decomposition. Sub-layers emerge as paradigms reveal which abstractions are real; nothing in this section is fully fleshed out — it's the editorial direction, not a concrete queue.
|
||||
|
||||
### Proposed sub-layer shape
|
||||
|
||||
| Sub-layer | Purpose | Pair-validation requirement |
|
||||
|-----------|---------|------------------------------|
|
||||
| `lib/guest/core/` | True universals: lex, pratt, ast, match, prefix-rename, conformance harness | Two consumers from *different paradigms* (e.g. lua + prolog) |
|
||||
| `lib/guest/typed/` | HM, generalisation, kind system, type-class-style dispatch | Two typed consumers (e.g. ocaml + haskell) |
|
||||
| `lib/guest/relational/` | Unification beyond core match, occurs-check toggles, substitution composition, search strategies | Two relational consumers (e.g. minikanren + datalog) |
|
||||
| `lib/guest/effects/` | Handler stacks, perform/resume protocols, dynamic-extent tracking | Two effect-typed consumers (e.g. koka + future) |
|
||||
| `lib/guest/layout/` | Off-side rule, semicolon insertion, brace insertion | Two whitespace-sensitive consumers (e.g. haskell + elm or python-shape) |
|
||||
| `lib/guest/lazy/` | Thunk wrapping, force/delay protocols, sharing semantics | Two lazy consumers (e.g. haskell + future lazy guest) |
|
||||
| `lib/guest/oo/` | Message dispatch, method tables, super lookup | Two message-passing consumers (e.g. smalltalk + ruby) |
|
||||
|
||||
Future rows as paradigms emerge: constraint-domain solvers, gradual typing, capability-based effect systems, dependent types, etc. Layers should not be created speculatively — wait for two real consumers in the same paradigm before opening a sub-layer.
|
||||
|
||||
### Re-homing the Phase A entries
|
||||
|
||||
The Phase 0–3 entries currently at the lib/guest root are the candidates for re-homing under sub-layers as the stratification settles. Initial mapping (subject to refinement):
|
||||
|
||||
- `conformance.sx`, `prefix.sx` → stay at root (true infrastructure, not paradigm-specific)
|
||||
- `lex.sx`, `pratt.sx`, `ast.sx`, `match.sx` → `core/`
|
||||
- `layout.sx` → `layout/`
|
||||
- `hm.sx` → `typed/` (currently the most overclaiming entry at root — has no plausible non-typed consumer)
|
||||
|
||||
### Two-consumer rule, scaled
|
||||
|
||||
The flat "two guests must consume it" rule scales with the layer's universality claim:
|
||||
|
||||
- A `core/` extraction must be cross-paradigm-validated (lua + prolog, not lua + tcl which are both dynamic-imperative).
|
||||
- A `typed/` extraction needs two typed consumers; that's a tighter audience but still real.
|
||||
- A `relational/` extraction needs two relational consumers, etc.
|
||||
- Each layer's bar is *exactly* the universality it claims, no more, no less. An abstraction that claims universality (root level) but only has typed consumers belongs in `typed/`, not at root.
|
||||
|
||||
### Language profiles
|
||||
|
||||
Each language ends up consuming a *profile* of which sub-layers it uses. Profiles are aspirational until each language ports — but the matrix tells you which sub-layers to invest in based on consumer demand, and serves as a quick design document for new languages ("which existing profile does it most resemble?").
|
||||
|
||||
| Language | core | typed | relational | effects | layout | lazy | oo |
|
||||
|----------|:----:|:-----:|:----------:|:-------:|:------:|:----:|:--:|
|
||||
| ocaml | ✓ | ✓ | | | | | |
|
||||
| haskell | ✓ | ✓ | | | ✓ | ✓ | |
|
||||
| elm | ✓ | ✓ | | | ✓ | | |
|
||||
| reasonml | ✓ | ✓ | | | | | |
|
||||
| minikanren | ✓ | | ✓ | | | | |
|
||||
| datalog | ✓ | | ✓ | | | | |
|
||||
| prolog | ✓ | | ✓ | | | | |
|
||||
| koka | ✓ | ✓ | | ✓ | | | |
|
||||
| erlang | ✓ | | | (msg) | | | |
|
||||
| elixir | ✓ | | | (msg) | | | |
|
||||
| smalltalk | ✓ | | | | | | ✓ |
|
||||
| ruby | ✓ | | | | | | ✓ |
|
||||
| common-lisp | ✓ | | | | | | (CLOS) |
|
||||
| lua / tcl / forth / apl | ✓ | | | | | | |
|
||||
| js | ✓ | | | (async) | | | |
|
||||
|
||||
`(msg)`, `(async)`, `(CLOS)` denote shapes that *might* live in `effects/` or `oo/` once the paradigm gets a second consumer to validate against.
|
||||
|
||||
## Long-running discipline
|
||||
|
||||
This plan does not have a "done" state. The operating mode is *continuous pair-driven refactoring*:
|
||||
|
||||
- When a new guest reaches the same shape as an existing one → look for shared abstraction → consider extraction.
|
||||
- When two existing consumers diverge on how they use a kit → consider a sub-layer split or a redesign.
|
||||
- When a sub-layer accumulates more than ~5 entries → consider further stratification.
|
||||
- When a kit has *never* been refactored after a second consumer ported → suspicious; the second port probably reshaped expectations and the kit should have flexed. Audit it.
|
||||
- When a Phase A entry (currently at root) gets a second consumer in a narrower paradigm than "universal" → re-home into the appropriate sub-layer, don't wait for a third.
|
||||
|
||||
**Substrate work and lib/guest work feed each other.** Substrate fixes (sx-improvements queue) raise lib/guest's ceiling — every kit gets faster and more correct. lib/guest exposes substrate gaps that wouldn't show up in single-guest work — when two paradigms can't share an abstraction cleanly, the substrate may be missing a primitive. Treat lib/guest issues as substrate-investigation prompts before papering them over with kit-side workarounds.
|
||||
|
||||
**Extraction is not the goal — codification is.** "I refactored 800 lines of duplication into 200 lines of shared kit" is the bootstrapping mode. The long-running mode is "I codified a piece of language theory in working SX form, validated by N paradigms." The same line-count delta means very different things in those two modes. Keep the bar at codification, not just deduplication.
|
||||
|
||||
---
|
||||
|
||||
## Progress log
|
||||
|
||||
| Step | Status | Commit | Delta |
|
||||
@@ -169,7 +308,7 @@ Extract from `haskell/infer.sx`. Algorithm W or J, generalisation, instantiation
|
||||
- **Scope:** ONLY `lib/guest/**`, `lib/{lua,prolog,haskell,common-lisp,tcl}/**` (canaries + extraction targets), `plans/lib-guest.md`, `plans/agent-briefings/lib-guest-loop.md`. No `spec/`, `hosts/`, `web/`, `shared/`.
|
||||
- **SX files:** `sx-tree` MCP tools only. `sx_validate` after every edit.
|
||||
- **No raw dune.** Use `sx_build target="ocaml"` MCP tool.
|
||||
- **Two-language rule:** never merge an extraction until two guests consume it (Step 8 excepted with explicit note).
|
||||
- **Two-language rule (scaled by claim):** never merge an extraction until two guests consume it. The pair must be appropriate to the layer's universality claim — `core/` needs cross-paradigm pair, `typed/` needs two typed consumers, `relational/` needs two relational consumers, etc. (See *Phase B — Stratification* for the matrix.) Step 8 (Phase A) excepted with explicit OCaml-paired note.
|
||||
- **Conformance baseline is the bar.** Any port whose scoreboard regresses by ≥1 test → revert, mark blocked, move on.
|
||||
- **Substrate change → re-snapshot.** If `spec/` or `hosts/` changes underneath this loop, re-run Step 0 before continuing.
|
||||
- **One step per code commit.** Plan updates as a separate commit. Short message with delta.
|
||||
|
||||
144
plans/linear-on-sx.md
Normal file
144
plans/linear-on-sx.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Linear-on-SX: resource model
|
||||
|
||||
Linear and affine type systems track *consumption* — values used at most once, references handed off rather than copied. Currently SX has no notion of "this value cannot be duplicated"; adding it changes the value space fundamentally. **Granule** (Eyers, Gaboardi, Orchard et al.) is the cleanest research target — graded modal types extending HM with linearity. Alternative: a Linear Haskell fragment (Bernardy et al.). Both are more principled than Rust's borrow checker for the chiseling purpose, since they isolate linearity from the borrow/lifetime story.
|
||||
|
||||
**The chisel:** *consumption*. Asks the substrate to articulate its aliasing and ownership semantics. SX values are currently fully duplicable — every let-binding can copy, every closure capture is implicit, every reference is shareable. Linear types force the substrate to honour at-most-one-use as a first-class property.
|
||||
|
||||
**What this exposes about the substrate:**
|
||||
- Whether SX can statically track at-most-once consumption without runtime overhead (compile-time check).
|
||||
- Whether closures can be linearly typed — capturing a linear value should make the closure itself linear.
|
||||
- Whether substrate primitives (`make-ref`, `set-ref!`, `deref-ref`) can be *exposed* with linear interfaces alongside the duplicable defaults.
|
||||
- Whether handlers (effects) compose with linearity — does using a capability consume it?
|
||||
- Whether the macro system handles linear binding hygienically.
|
||||
|
||||
**End-state goal:** **Granule core** — linear arrows `A ⊸ B`, unrestricted modality `!A` (Box A in some treatments), graded modalities `□_n A` (n-uses), linear pattern matching, integration with HM. Standard library demonstrating linear file handles, linear channels, linear references. **Practical relevance:** artdag — content-addressed values, IPFS pins, file handles, network sockets all want "use exactly once" or "use exactly N times" semantics.
|
||||
|
||||
## Ground rules
|
||||
- Scope: `lib/linear/**` and `plans/linear-on-sx.md` only. Substrate gaps → `sx-improvements.md`.
|
||||
- Consumes from `lib/guest/`: `core/lex`, `core/pratt`, `core/ast`, `core/match`, `typed/hm.sx` (extended with linear type variables and modalities).
|
||||
- **Will propose** a new sub-layer `lib/guest/linear/` — linearity tracking infrastructure, modality bookkeeping, separation logic primitives. Second consumer: a Rust-fragment, a Linear Haskell fragment, ATS-on-SX, or a future capability-secure language.
|
||||
- Branch: `loops/linear`. Standard worktree pattern.
|
||||
|
||||
## Architecture sketch
|
||||
|
||||
```
|
||||
Linear source text (Granule-flavoured: HM + linear arrows + modalities)
|
||||
│
|
||||
▼
|
||||
lib/linear/parser.sx — Haskell-ish syntax with -o for linear arrow,
|
||||
│ ![A] for unrestricted, [n]A for graded
|
||||
▼
|
||||
lib/linear/elaborate.sx — surface → core: explicit modality coercions,
|
||||
│ let-binding linearity inference
|
||||
▼
|
||||
lib/linear/check.sx — bidirectional type checker tracking BOTH
|
||||
│ types AND usage counts per binding
|
||||
▼
|
||||
lib/linear/typed/ — extends lib/guest/typed/hm.sx with:
|
||||
│ linear arrow types, modality types, grade algebra
|
||||
▼
|
||||
lib/linear/runtime.sx — runtime is plain SX (linearity erased after check)
|
||||
standard library: linear refs, linear channels,
|
||||
linear file handles
|
||||
```
|
||||
|
||||
## Semantic mappings
|
||||
|
||||
| Linear construct | SX mapping |
|
||||
|------------------|-----------|
|
||||
| `A -o B` | linear arrow type `{:type :arrow :linear true :domain A :codomain B}` |
|
||||
| `A -> B` | unrestricted arrow (sugar for `!A -o B`) |
|
||||
| `!A` | unrestricted (duplicable) modality on type A |
|
||||
| `[n] A` | graded: usable exactly n times |
|
||||
| `let !x = e in body` | unbox an unrestricted value (allow duplication) |
|
||||
| `let x = e in body` | linear binding — `x` must appear *exactly once* in `body` |
|
||||
| `case x of !y -> body` | match-and-unbox |
|
||||
| `dup x in body` | duplicate (only on unrestricted values; type error otherwise) |
|
||||
| `share x` | turn a linear value into unrestricted (under specific guarantees) |
|
||||
|
||||
The key novel substrate property: every binding has a *grade* — how many times it's used. The type checker computes grades, complains if usage doesn't match the declared grade. Runtime is plain SX — linearity is erased after type checking.
|
||||
|
||||
## Roadmap
|
||||
|
||||
### Phase 1 — Parser
|
||||
- [ ] Granule-flavoured syntax: HM core plus linear arrows, modality annotations.
|
||||
- [ ] Reuse `lib/guest/lex`, `lib/guest/pratt`.
|
||||
- [ ] Tests in `lib/linear/tests/parse.sx`.
|
||||
|
||||
### Phase 2 — Type system: linear vs unrestricted base
|
||||
- [ ] Two type "worlds": linear (`A -o B`) and unrestricted (`!A`, `A -> B`).
|
||||
- [ ] Type checker tracks usage count per variable.
|
||||
- [ ] Reject programs that use a linear variable zero or twice times in a context.
|
||||
- [ ] Tests: programs that violate linearity get rejected with clear errors.
|
||||
|
||||
### Phase 3 — Linear functions + linear pattern matching
|
||||
- [ ] Linear lambda: `\x -> body` — `x` consumed exactly once in `body`.
|
||||
- [ ] Linear pair `(x, y)` — both components consumed if pair is consumed.
|
||||
- [ ] `let (x, y) = pair in body` — destructure (consume) pair, both `x` and `y` are linear.
|
||||
- [ ] Tests: linear list manipulation, linear pair swapping.
|
||||
|
||||
### Phase 4 — Modalities (! and graded)
|
||||
- [ ] `!A` — unrestricted modality, can be duplicated/discarded freely.
|
||||
- [ ] Promotion: `[e]` lifts linear `e : A` to unrestricted `!A` (only if `e` uses only unrestricted values).
|
||||
- [ ] Graded modalities `[n] A` for n-times use; algebra over grades (semiring with +, *).
|
||||
- [ ] Tests: graded programs (use-twice, use-three-times patterns).
|
||||
|
||||
### Phase 5 — Linear references + standard library
|
||||
- [ ] `LinearRef A` — write-once or in-place-update with type-tracked transitions.
|
||||
- [ ] `LinearChannel A` — send-and-consume.
|
||||
- [ ] `LinearFile` — open returns linear handle, read/write consume + return new handle, close consumes terminally.
|
||||
- [ ] Tests: linear file API usage, channel send/receive, in-place-mutation patterns.
|
||||
|
||||
### Phase 6 — Effects + linearity
|
||||
- [ ] When linear values flow through `perform`/handlers, the handler must consume them linearly too.
|
||||
- [ ] Capabilities as linear values: `Cap` consumed when capability is exercised.
|
||||
- [ ] Tests: handler that takes a linear capability and uses it once.
|
||||
|
||||
### Phase 7 — Borrowing (lightweight)
|
||||
- [ ] `borrow x as y in body` — temporarily allow non-consuming use of a linear value.
|
||||
- [ ] Borrow ends at end of `body`; original `x` still linear after.
|
||||
- [ ] No lifetime regions à la Rust — just lexical borrow scopes.
|
||||
- [ ] Tests: read a linear file handle without consuming it.
|
||||
|
||||
### Phase 8 — Integration with artdag idioms
|
||||
- [ ] Demo: artdag-style pipeline where each effect node holds a linear CID, transforms it, returns a new linear CID.
|
||||
- [ ] Demo: IPFS pin operations as linear capability transitions.
|
||||
- [ ] Tests: end-to-end pipeline that compiles iff linearity is honoured.
|
||||
|
||||
### Phase 9 — Propose `lib/guest/linear/`
|
||||
- [ ] Extract linearity-tracking type-checker infrastructure.
|
||||
- [ ] Extract grade algebra primitives (semiring operations).
|
||||
- [ ] Extract modality coercion machinery.
|
||||
- [ ] Wait for second consumer before extracting (Rust-fragment is the natural pair).
|
||||
|
||||
## lib/guest feedback loop
|
||||
|
||||
**Consumes:** `core/lex`, `core/pratt`, `core/ast`, `core/match`, `typed/hm.sx` (extended).
|
||||
|
||||
**Stresses substrate:** value duplicability assumptions throughout — does the SX evaluator implicitly duplicate values anywhere (caching? memoisation? structural sharing)? Those become bugs under linearity.
|
||||
|
||||
**May propose:** `lib/guest/linear/` sub-layer — usage tracking (grades), modality coercions, linear arrows. Also might motivate `lib/guest/typed/hm.sx` to grow a "type-system-extension" interface so linearity, refinement types, and effect rows can all extend HM uniformly.
|
||||
|
||||
**What it teaches:** whether SX's value model is paradigm-agnostic or quietly assumes duplicability. If the substrate has any "values are duplicable for free" assumptions baked in, linearity surfaces them. If linearity composes cleanly, it's strong evidence for substrate paradigm-neutrality.
|
||||
|
||||
## Practical artdag connection
|
||||
|
||||
Artdag (the federated content-addressed media processing engine) has natural linearity:
|
||||
- A CID is conceptually unique; pinning + unpinning has a linear-resource shape.
|
||||
- File handles, network sockets, IPFS connections all want at-most-once-close semantics.
|
||||
- L1↔L2 token transfer (scoped JWT) has at-most-once-use semantics.
|
||||
|
||||
If linear-on-sx works, artdag could rewrite its resource-handling layer in linear-typed code, getting compile-time guarantees of resource discipline. That's a real-world payoff that justifies more than the "chisel" framing.
|
||||
|
||||
## References
|
||||
- Bernardy et al., "Linear Haskell: Practical Linearity in a Higher-Order Polymorphic Language" (POPL 2018).
|
||||
- Orchard, Liepelt, Eades, "Quantitative program reasoning with graded modal types" (ICFP 2019) — Granule.
|
||||
- Wadler, "Linear types can change the world!" (1990) — foundational.
|
||||
- Pierce (TAPL), Ch. 14 — linear and affine types.
|
||||
- Granule source: https://github.com/granule-project/granule
|
||||
|
||||
## Progress log
|
||||
_(awaiting Phase 1 — depends on lib/guest/typed/hm.sx maturity)_
|
||||
|
||||
## Blockers
|
||||
_(none yet — main risk is type-checker complexity for graded modalities)_
|
||||
131
plans/maude-on-sx.md
Normal file
131
plans/maude-on-sx.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# Maude-on-SX: rewriting as primitive
|
||||
|
||||
Equational logic + term rewriting as the *only* computational primitive. Every other guest in the set reduces ultimately to lambda terms or stack frames; **Maude** (Clavel et al.) reduces to *rewrite rules over equational classes modulo theories* (associativity, commutativity, identity). Implementing it forces the substrate to articulate its reduction semantics — currently implicit in the CEK machine and the JIT.
|
||||
|
||||
**The chisel:** *reduction step*. Different from Idris's *evidence* chisel and from Probabilistic's *trace* chisel. Maude asks: "what is one step of computation?" Maude's answer (apply a rewrite rule, modulo equational theories) is more general than CEK's transition. Making both consistent is informative — either the substrate has room for them to coexist, or one is a special case of the other.
|
||||
|
||||
**What this exposes about the substrate:**
|
||||
- Whether SX's pattern matching (lib/guest/match.sx) extends to *equational matching* — matching modulo associativity, commutativity, identity.
|
||||
- Whether the substrate has a notion of "normal form" or just "result of evaluation."
|
||||
- Whether term-graph sharing matters at the value-level.
|
||||
- Whether confluence (different rewrite orders → same result) can be checked or just hoped for.
|
||||
- Whether order-sorted signatures (subsorts, polymorphism via inheritance) fit SX's value taxonomy.
|
||||
|
||||
**End-state goal:** **Maude 3 functional + system modules** — sorts, subsorts, equations, conditional equations, rewrite rules, equational matching modulo `assoc`/`comm`/`id`, simple strategy language. Not the full LTL model checker; a faithful core that runs idiomatic Maude programs and proves equational identities.
|
||||
|
||||
## Ground rules
|
||||
- Scope: `lib/maude/**` and `plans/maude-on-sx.md` only. Substrate gaps → `sx-improvements.md`.
|
||||
- Consumes from `lib/guest/`: `core/lex`, `core/pratt`, `core/ast`, `core/match` (extended).
|
||||
- **Will propose** a new sub-layer `lib/guest/rewriting/` — equational matching beyond syntactic match, normal-form computation, confluence checking, term-graph rewriting. Second consumer: a Pure-on-SX plan, a CafeOBJ port, or a research term-rewriting playground.
|
||||
- Branch: `loops/maude`. Standard worktree pattern.
|
||||
|
||||
## Architecture sketch
|
||||
|
||||
```
|
||||
Maude source text (functional / system / object modules)
|
||||
│
|
||||
▼
|
||||
lib/maude/parser.sx — fmod ... endfm syntax, sort declarations,
|
||||
│ equations, rewrite rules
|
||||
▼
|
||||
lib/maude/signatures.sx — sort hierarchy, operator declarations with arities,
|
||||
│ subsort relationships, kind inference
|
||||
▼
|
||||
lib/maude/matching.sx — pattern matching MODULO equational theories
|
||||
│ (assoc, comm, id) — generalises core/match.sx
|
||||
▼
|
||||
lib/maude/reduce.sx — apply equations until normal form (confluent set)
|
||||
│
|
||||
▼
|
||||
lib/maude/rewrite.sx — apply rewrite rules under a strategy (system modules)
|
||||
│
|
||||
▼
|
||||
lib/maude/runtime.sx — module loading, reflection (META-LEVEL)
|
||||
```
|
||||
|
||||
## Semantic mappings
|
||||
|
||||
| Maude construct | SX mapping |
|
||||
|----------------|-----------|
|
||||
| `sort Nat .` | declare sort: `(declare-sort Nat)` |
|
||||
| `subsort Nat < Int .` | subsort relation: `(declare-subsort Nat Int)` |
|
||||
| `op _+_ : Nat Nat -> Nat [assoc comm id: 0] .` | operator with equational attributes |
|
||||
| `eq X + 0 = X .` | equation in the equational theory |
|
||||
| `ceq X + Y = Y if foo(X, Y) .` | conditional equation |
|
||||
| `rl [step] : foo(X) => bar(X) .` | rewrite rule (asymmetric, in system modules) |
|
||||
| `red TERM .` | reduce term to normal form by equations |
|
||||
| `rew TERM .` | apply rewrite rules under default strategy |
|
||||
| `META-LEVEL` | reflection: terms representing terms |
|
||||
|
||||
The novel substrate stress: equational matching. Pattern `X + Y` against `1 + 2 + 3` (where `+` is `assoc comm`) succeeds with multiple binding sets: `(X=1, Y=2+3)`, `(X=2, Y=1+3)`, `(X=3, Y=1+2)`, etc. The matcher must enumerate solutions, not return the first.
|
||||
|
||||
## Roadmap
|
||||
|
||||
### Phase 1 — Parser + signatures
|
||||
- [ ] Parser for `fmod` / `endfm` syntax, sort declarations, op declarations, equations.
|
||||
- [ ] Sort hierarchy with subsort relations.
|
||||
- [ ] Operator overloading by arity + sort.
|
||||
- [ ] Tests: parse classic examples (peano nat, list of naturals).
|
||||
|
||||
### Phase 2 — Syntactic equational reduction
|
||||
- [ ] Apply equations left-to-right until no equation matches.
|
||||
- [ ] Standard pattern matching (no equational theories yet — strict syntactic match).
|
||||
- [ ] Tests: peano arithmetic, list manipulation, propositional logic simplifier.
|
||||
|
||||
### Phase 3 — Equational matching (assoc / comm / id)
|
||||
- [ ] Extend matching to handle `assoc` operators (flatten then match across permutations of subterm groups).
|
||||
- [ ] Handle `comm` (try both argument orderings).
|
||||
- [ ] Handle `id: e` (X * e ≡ X).
|
||||
- [ ] Combinations: `assoc comm id` together.
|
||||
- [ ] Returns *all* matches, not just first — caller drives.
|
||||
- [ ] Tests: classic AC-matching examples (multiset rewriting, set theory, group equations).
|
||||
|
||||
### Phase 4 — Conditional equations
|
||||
- [ ] `ceq L = R if Cond` — apply only when `Cond` reduces to true.
|
||||
- [ ] Recursion via the same reduce engine (terminating because Cond is shorter).
|
||||
- [ ] Tests: gcd, sorting, conditional simplifications.
|
||||
|
||||
### Phase 5 — System modules + rewrite rules
|
||||
- [ ] `mod ... endm` syntax with `rl` rules.
|
||||
- [ ] Rules apply asymmetrically (`=>` not `=`); fairness across rules.
|
||||
- [ ] Default strategy: top-down, leftmost-outermost, first applicable rule.
|
||||
- [ ] Tests: state-transition systems (puzzle solvers, protocol simulators).
|
||||
|
||||
### Phase 6 — Strategy language
|
||||
- [ ] Compose strategies: sequential `;`, alternative `|`, iteration `*`, fixed-point.
|
||||
- [ ] User-named strategies; strategy expressions as values.
|
||||
- [ ] Tests: programs whose meaning depends on strategy choice.
|
||||
|
||||
### Phase 7 — Reflection (META-LEVEL)
|
||||
- [ ] Terms-as-data: `META-LEVEL` lets you encode/decode terms as Maude terms.
|
||||
- [ ] Build proofs / programs that manipulate Maude programs.
|
||||
- [ ] Tests: meta-circular interpretation, generic theorem helpers.
|
||||
|
||||
### Phase 8 — Propose `lib/guest/rewriting/`
|
||||
- [ ] Extract equational matching engine (the most reusable piece).
|
||||
- [ ] Extract normal-form-by-equations infrastructure.
|
||||
- [ ] Extract strategy combinators.
|
||||
- [ ] Wait for second consumer before extracting.
|
||||
|
||||
## lib/guest feedback loop
|
||||
|
||||
**Consumes:** `core/lex`, `core/pratt`, `core/ast`, `core/match` (with proposed extension for equational matching).
|
||||
|
||||
**Stresses substrate:** matching backtracking and enumeration (Maude's all-matches semantics is very different from Haskell-style first-match); whether SX values can carry sort metadata efficiently; term-graph sharing.
|
||||
|
||||
**May propose:** `lib/guest/rewriting/` sub-layer — equational matching (extending core/match), normal-form-by-equations machinery, strategy combinators, confluence checking.
|
||||
|
||||
**What it teaches:** whether the substrate's reduction model has implicit assumptions (deterministic, leftmost-outermost, etc.) that a rewriting language exposes. If `core/match.sx` cleanly extends to equational matching via a configuration toggle, that's substrate-deep validation. If extending it requires fundamental rework, the substrate's matching abstraction was leaking.
|
||||
|
||||
## References
|
||||
- Clavel et al., "All About Maude — A High-Performance Logical Framework" (Springer, 2007).
|
||||
- Maude Manual: https://maude.lcc.uma.es/
|
||||
- "Term Rewriting and All That" (Baader & Nipkow, 1998) — theoretical foundation.
|
||||
- Eker, "Associative-Commutative Rewriting on Large Terms" (RTA 2003) — for the matching algorithm.
|
||||
- Pure language (Albrecht Gräf): https://agraef.github.io/pure-lang/ — practical functional rewriting.
|
||||
|
||||
## Progress log
|
||||
_(awaiting Phase 1 — depends on substrate matching maturity from lib/guest/core/match.sx)_
|
||||
|
||||
## Blockers
|
||||
_(speculative — equational matching is algorithmically heavy and may surface JIT issues)_
|
||||
@@ -1,44 +1,34 @@
|
||||
# OCaml-on-SX: OCaml + ReasonML + Dream on the CEK/VM
|
||||
# OCaml-on-SX: substrate validation + HM + reference oracle
|
||||
|
||||
The meta-circular demo: SX's native evaluator is OCaml, so implementing OCaml on top of
|
||||
SX closes the loop — the source language of the host is running inside the host it
|
||||
compiles to. Beyond the elegance, it's practically useful: once OCaml expressions run on
|
||||
the SX CEK/VM you get Dream (a clean OCaml web framework) almost for free, and ReasonML
|
||||
is a syntax variant that shares the same transpiler output.
|
||||
The strict-ML answer to "does the SX substrate really do what we claim it does?" OCaml has *exactly* the feature set SX was designed around — CEK, records, ADTs, exceptions, modules, refs, strict evaluation — so implementing it on SX is the strongest possible test of the substrate. Phase 5 also produces a real Hindley-Milner inferencer that feeds back into `lib/guest/hm.sx`, and the resulting OCaml interpreter serves as a reference oracle for every other guest language (when SX behavior is ambiguous, native OCaml answers).
|
||||
|
||||
End-state goal: **OCaml programs running on the SX CEK/VM**, with enough of the standard
|
||||
library to support Dream's middleware model. Dream-on-SX is the integration target —
|
||||
a `handler`/`middleware`/`router` API that feels idiomatic while running purely in SX.
|
||||
ReasonML (Phase 8) adds an alternative syntax frontend that targets the same transpiler.
|
||||
**End-state goal:** OCaml Phases 1–5 running on the SX CEK, with a vendored slice of the official OCaml testsuite as the oracle corpus. HM extracted into `lib/guest/hm.sx` once Haskell-on-SX adopts it as second consumer.
|
||||
|
||||
**Out of scope (this plan):** Dream web framework — moved to `plans/dream-on-sx.md`, only spins up if a target user appears. Full standard library — only the minimal slice needed for substrate validation and the oracle role.
|
||||
|
||||
**Conditional:** ReasonML syntax variant (Phase 8) — kept in the plan but deferred until Phases 1–2 land and a decision is made to ship a user-facing OCaml.
|
||||
|
||||
## What this covers that nothing else in the set does
|
||||
|
||||
- **Strict ML semantics** — unlike Haskell, OCaml is call-by-value with explicit `Lazy.t`
|
||||
for laziness. Pattern match is exhaustive. Polymorphic variants. Structural equality.
|
||||
- **First-class modules and functors** — modules as values (phase 4); functors as SX
|
||||
higher-order functions over module records. Unlike Haskell typeclasses, OCaml's module
|
||||
system is explicit and compositional.
|
||||
- **Mutable state without monads** — `ref`, `:=`, `!` are primitives. Arrays. `Hashtbl`.
|
||||
The IO model is direct; `Lwt`/Dream map to `perform`/`cek-resume` for async.
|
||||
- **Dream's composable HTTP model** — `handler = request -> response promise`,
|
||||
`middleware = handler -> handler`. Algebraically clean; `@@` composition maps to SX
|
||||
function composition trivially.
|
||||
- **ReasonML** — same semantics, JS-friendly surface syntax. JSX variant pairs with SX
|
||||
component rendering.
|
||||
- **Strict ML semantics** — unlike Haskell, OCaml is call-by-value with explicit `Lazy.t` for laziness. Pattern match is exhaustive. Polymorphic variants. Structural equality.
|
||||
- **First-class modules and functors** — modules as values (Phase 4); functors as SX higher-order functions over module records. Unlike Haskell typeclasses, OCaml's module system is explicit and compositional. **The hardest test of the substrate** — if Phase 4 takes 3000 lines instead of 800, the substrate is telling us something.
|
||||
- **Mutable state without monads** — `ref`, `:=`, `!` are primitives. Arrays. `Hashtbl`. The IO model is direct.
|
||||
- **Reference oracle** — when other guest languages disagree about a semantic edge case (HM in Haskell-on-SX vs in OCaml-on-SX, exception ordering, equality semantics), native OCaml is the tiebreaker. The vendored testsuite slice (Phase 5.1) makes this oracle role concrete.
|
||||
|
||||
## Sequencing dependency
|
||||
|
||||
**OCaml-on-SX should not start until lib-guest Steps 0–7 are complete.** OCaml's tokenizer should consume `lib/guest/lex.sx` (lib-guest Step 3); its precedence parser should consume `lib/guest/pratt.sx` (Step 4); its pattern matcher should consume `lib/guest/match.sx` (Step 6). Starting OCaml early means it hand-rolls these and never validates the abstraction — losing one of the main strategic payoffs.
|
||||
|
||||
Reciprocally, **lib-guest Step 8 (HM extraction) waits on OCaml-on-SX Phase 5** — extracting HM with only Haskell as consumer is speculative; with both Haskell and OCaml the two-language rule is satisfied for real.
|
||||
|
||||
## Ground rules
|
||||
|
||||
- **Scope:** only touch `lib/ocaml/**`, `lib/dream/**`, `lib/reasonml/**`, and
|
||||
`plans/ocaml-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, or other
|
||||
`lib/<lang>/`.
|
||||
- **Scope:** only touch `lib/ocaml/**`, `lib/reasonml/**` (Phase 8 only), and `plans/ocaml-on-sx.md`. Do **not** edit `spec/`, `hosts/`, `shared/`, `lib/dream/**` (separate plan), or other `lib/<lang>/`.
|
||||
- **Consume `lib/guest/`** wherever it covers a need (lex, pratt, match, ast). Hand-rolling instead of consuming defeats the substrate-validation goal.
|
||||
- **Shared-file issues** go under "Blockers" below with a minimal repro; do not fix here.
|
||||
- **SX files:** use `sx-tree` MCP tools only.
|
||||
- **Architecture:** OCaml source → AST → SX AST → CEK. No standalone OCaml evaluator.
|
||||
The OCaml AST is walked by an `ocaml-eval` function in SX that produces SX values.
|
||||
- **Type system:** deferred until Phase 5. Phases 1–4 are intentionally untyped —
|
||||
get the evaluator right first, then layer HM inference on top.
|
||||
- **Dream:** implemented as a library in Phase 7; no separate build step. `Dream.run`
|
||||
wraps SX's existing HTTP server machinery via `perform`/`cek-resume`.
|
||||
- **Architecture:** OCaml source → AST → SX AST → CEK. No standalone OCaml evaluator. The OCaml AST is walked by an `ocaml-eval` function in SX that produces SX values.
|
||||
- **Type system:** deferred until Phase 5. Phases 1–4 are intentionally untyped — get the evaluator right first, then layer HM inference on top.
|
||||
- **Commits:** one feature per commit. Keep `## Progress log` updated and tick boxes.
|
||||
|
||||
## Architecture sketch
|
||||
@@ -48,10 +38,11 @@ OCaml source text
|
||||
│
|
||||
▼
|
||||
lib/ocaml/tokenizer.sx — keywords, operators, string/char literals, comments
|
||||
│
|
||||
│ (built on lib/guest/lex.sx)
|
||||
▼
|
||||
lib/ocaml/parser.sx — OCaml AST: let/let rec, fun, match, if, begin/end,
|
||||
│ module/struct/functor, type decls, expressions
|
||||
│ (precedence via lib/guest/pratt.sx)
|
||||
▼
|
||||
lib/ocaml/desugar.sx — surface → core: tuple patterns, or-patterns,
|
||||
│ sequence (;) → (do), when guards, field punning
|
||||
@@ -60,7 +51,7 @@ lib/ocaml/transpile.sx — OCaml AST → SX AST
|
||||
│
|
||||
▼
|
||||
lib/ocaml/runtime.sx — ADT constructors, module primitives, ref/array ops,
|
||||
│ Stdlib shims, Dream server (phase 7)
|
||||
│ minimal Stdlib shims (Phase 6)
|
||||
▼
|
||||
SX CEK evaluator (both JS and OCaml hosts)
|
||||
```
|
||||
@@ -89,49 +80,18 @@ SX CEK evaluator (both JS and OCaml hosts)
|
||||
| `r := v` | `(set-ref! r v)` |
|
||||
| `(a, b, c)` | tagged list `(:tuple a b c)` |
|
||||
| `[1; 2; 3]` | `(list 1 2 3)` |
|
||||
| `[| 1; 2; 3 |]` | `(make-array 1 2 3)` (Phase 6) |
|
||||
| `[\| 1; 2; 3 \|]` | `(make-array 1 2 3)` (Phase 6) |
|
||||
| `try e with \| Ex -> h` | `(guard (fn (ex) h) e)` via SX exception system |
|
||||
| `raise Ex` | `(perform (:raise Ex))` |
|
||||
| `Printf.printf "%d" x` | `(perform (:print (format "%d" x)))` |
|
||||
|
||||
## Dream semantic mappings (Phase 7)
|
||||
|
||||
| Dream construct | SX mapping |
|
||||
|----------------|-----------|
|
||||
| `handler = request -> response promise` | `(fn (req) (perform (:http-respond ...)))` |
|
||||
| `middleware = handler -> handler` | `(fn (next) (fn (req) ...))` |
|
||||
| `Dream.router [routes]` | `(ocaml-dream-router routes)` — dispatch on method+path |
|
||||
| `Dream.get "/path" h` | route record `{:method "GET" :path "/path" :handler h}` |
|
||||
| `Dream.scope "/p" [ms] [rs]` | prefix mount with middleware chain |
|
||||
| `Dream.param req "name"` | path param extracted during routing |
|
||||
| `m1 @@ m2 @@ handler` | `(m1 (m2 handler))` — left-fold composition |
|
||||
| `Dream.session_field req "k"` | `(perform (:session-get req "k"))` |
|
||||
| `Dream.set_session_field req "k" v` | `(perform (:session-set req "k" v))` |
|
||||
| `Dream.flash req` | `(perform (:flash-get req))` |
|
||||
| `Dream.form req` | `(perform (:form-parse req))` — returns Ok/Error ADT |
|
||||
| `Dream.websocket handler` | `(perform (:websocket handler))` |
|
||||
| `Dream.run handler` | starts SX HTTP server with handler as root |
|
||||
| `Printf.sprintf "%d" x` | `(format "%d" x)` |
|
||||
|
||||
## Roadmap
|
||||
|
||||
### Phase 1 — Tokenizer + parser
|
||||
|
||||
- [ ] **Tokenizer:** keywords (`let`, `rec`, `in`, `fun`, `function`, `match`, `with`,
|
||||
`type`, `of`, `module`, `struct`, `end`, `functor`, `sig`, `open`, `include`,
|
||||
`if`, `then`, `else`, `begin`, `try`, `exception`, `raise`, `mutable`,
|
||||
`for`, `while`, `do`, `done`, `and`, `as`, `when`), operators (`->`, `|>`,
|
||||
`<|`, `@@`, `@`, `:=`, `!`, `::`, `**`, `:`, `;`, `;;`), identifiers (lower,
|
||||
upper/ctor, labels `~label:`, optional `?label:`), char literals `'c'`,
|
||||
string literals (escaped + heredoc `{|...|}`), int/float literals,
|
||||
line comments `(*` nested block comments `*)`.
|
||||
- [ ] **Parser:** top-level `let`/`let rec`/`type`/`module`/`exception`/`open`/`include`
|
||||
declarations; expressions: literals, identifiers, constructor application,
|
||||
lambda, application (left-assoc), binary ops with precedence table,
|
||||
`if`/`then`/`else`, `match`/`with`, `try`/`with`, `let`/`in`, `begin`/`end`,
|
||||
`fun`/`function`, tuples, list literals, record literals/updates, field access,
|
||||
sequences `;`, unit `()`.
|
||||
- [ ] **Patterns:** constructor, literal, variable, wildcard `_`, tuple, list cons `::`,
|
||||
list literal, record, `as`, or-pattern `P1 | P2`, `when` guard.
|
||||
- [ ] **Tokenizer** built on `lib/guest/lex.sx`: keywords (`let`, `rec`, `in`, `fun`, `function`, `match`, `with`, `type`, `of`, `module`, `struct`, `end`, `functor`, `sig`, `open`, `include`, `if`, `then`, `else`, `begin`, `try`, `exception`, `raise`, `mutable`, `for`, `while`, `do`, `done`, `and`, `as`, `when`), operators (`->`, `|>`, `<|`, `@@`, `@`, `:=`, `!`, `::`, `**`, `:`, `;`, `;;`), identifiers (lower, upper/ctor, labels `~label:`, optional `?label:`), char literals `'c'`, string literals (escaped + heredoc `{|...|}`), int/float literals, line comments `(*` nested block comments `*)`.
|
||||
- [ ] **Parser** with precedence via `lib/guest/pratt.sx`: top-level `let`/`let rec`/`type`/`module`/`exception`/`open`/`include` declarations; expressions: literals, identifiers, constructor application, lambda, application (left-assoc), binary ops with precedence table, `if`/`then`/`else`, `match`/`with`, `try`/`with`, `let`/`in`, `begin`/`end`, `fun`/`function`, tuples, list literals, record literals/updates, field access, sequences `;`, unit `()`.
|
||||
- [ ] **Patterns:** constructor, literal, variable, wildcard `_`, tuple, list cons `::`, list literal, record, `as`, or-pattern `P1 | P2`, `when` guard.
|
||||
- [ ] OCaml is **not** indentation-sensitive — no layout algorithm needed.
|
||||
- [ ] Tests in `lib/ocaml/tests/parse.sx` — 50+ round-trip parse tests.
|
||||
|
||||
@@ -154,21 +114,19 @@ SX CEK evaluator (both JS and OCaml hosts)
|
||||
|
||||
- [ ] `type` declarations: `type t = A | B of t1 * t2 | C of { x: int }`.
|
||||
- [ ] Constructors as tagged lists: `A` → `(:A)`, `B(1, "x")` → `(:B 1 "x")`.
|
||||
- [ ] `match`/`with`: constructor, literal, variable, wildcard, tuple, list cons/nil,
|
||||
`as` binding, or-patterns, nested patterns, `when` guard.
|
||||
- [ ] `match`/`with` consumes `lib/guest/match.sx`: constructor, literal, variable, wildcard, tuple, list cons/nil, `as` binding, or-patterns, nested patterns, `when` guard.
|
||||
- [ ] Exhaustiveness: runtime error on incomplete match (no compile-time check yet).
|
||||
- [ ] Built-in types: `option` (`None`/`Some`), `result` (`Ok`/`Error`),
|
||||
`list` (nil/cons), `bool`, `unit`, `exn`.
|
||||
- [ ] `exception` declarations; built-in: `Not_found`, `Invalid_argument`,
|
||||
`Failure`, `Match_failure`.
|
||||
- [ ] Polymorphic variants (surface syntax `\`Tag value`; runtime same tagged list).
|
||||
- [ ] Built-in types: `option` (`None`/`Some`), `result` (`Ok`/`Error`), `list` (nil/cons), `bool`, `unit`, `exn`.
|
||||
- [ ] `exception` declarations; built-in: `Not_found`, `Invalid_argument`, `Failure`, `Match_failure`.
|
||||
- [ ] Polymorphic variants (surface syntax `` `Tag value ``; runtime same tagged list).
|
||||
- [ ] Tests in `lib/ocaml/tests/adt.sx` — 40+ tests: ADTs, match, option/result.
|
||||
|
||||
### Phase 4 — Modules + functors
|
||||
|
||||
**The hardest test of the substrate.** First-class modules + functors are where the SX/CEK story either works elegantly or reveals a missing piece. Track line count vs equivalent OCaml stdlib implementations as the substrate-validation signal.
|
||||
|
||||
- [ ] `module M = struct let x = 1 let f y = x + y end` → SX dict `{:x 1 :f <fn>}`.
|
||||
- [ ] `module type S = sig val x : int val f : int -> int end` → interface record
|
||||
(runtime stub; typed checking in Phase 5).
|
||||
- [ ] `module type S = sig val x : int val f : int -> int end` → interface record (runtime stub; typed checking in Phase 5).
|
||||
- [ ] `module M : S = struct ... end` — coercive sealing (runtime: pass-through).
|
||||
- [ ] `functor (M : S) -> struct ... end` → SX `(fn (M) ...)`.
|
||||
- [ ] `module F = Functor(Base)` — functor application.
|
||||
@@ -176,12 +134,13 @@ SX CEK evaluator (both JS and OCaml hosts)
|
||||
- [ ] `include M` — same as open at structure level.
|
||||
- [ ] `M.name` — dict get via `:name` key.
|
||||
- [ ] First-class modules (pack/unpack) — deferred to Phase 5.
|
||||
- [ ] Standard module hierarchy: `List`, `Option`, `Result`, `String`, `Char`,
|
||||
`Int`, `Float`, `Bool`, `Unit`, `Printf`, `Format` (stubs, filled in Phase 6).
|
||||
- [ ] Standard module hierarchy stubs: `List`, `Option`, `Result`, `String`, `Int`, `Printf`, `Hashtbl` (filled in Phase 6).
|
||||
- [ ] Tests in `lib/ocaml/tests/modules.sx` — 30+ tests.
|
||||
|
||||
### Phase 5 — Hindley-Milner type inference
|
||||
|
||||
This is one of the headline payoffs of the whole plan. The inferencer built here is the seed of `lib/guest/hm.sx` (lib-guest Step 8) — once Haskell-on-SX adopts it as second consumer, it gets extracted.
|
||||
|
||||
- [ ] Algorithm W: `gen`/`inst`, `unify`, `infer-expr`, `infer-decl`.
|
||||
- [ ] Type variables: `'a`, `'b`; unification with occur-check.
|
||||
- [ ] Let-polymorphism: generalise at let-bindings.
|
||||
@@ -194,121 +153,67 @@ SX CEK evaluator (both JS and OCaml hosts)
|
||||
- [ ] No rank-2 polymorphism, no GADTs (out of scope).
|
||||
- [ ] Tests in `lib/ocaml/tests/types.sx` — 60+ inference tests.
|
||||
|
||||
### Phase 6 — Standard library
|
||||
### Phase 5.1 — Vendor OCaml testsuite slice (oracle corpus)
|
||||
|
||||
- [ ] `List`: `map`, `filter`, `fold_left`, `fold_right`, `length`, `rev`, `append`,
|
||||
`concat`, `flatten`, `iter`, `iteri`, `mapi`, `for_all`, `exists`, `find`,
|
||||
`find_opt`, `mem`, `assoc`, `assq`, `sort`, `stable_sort`, `nth`, `hd`, `tl`,
|
||||
`init`, `combine`, `split`, `partition`.
|
||||
- [ ] `Option`: `map`, `bind`, `fold`, `get`, `value`, `join`, `iter`, `to_list`,
|
||||
`to_result`, `is_none`, `is_some`.
|
||||
- [ ] `Result`: `map`, `bind`, `fold`, `get_ok`, `get_error`, `map_error`,
|
||||
`to_option`, `is_ok`, `is_error`.
|
||||
- [ ] `String`: `length`, `get`, `sub`, `concat`, `split_on_char`, `trim`,
|
||||
`uppercase_ascii`, `lowercase_ascii`, `contains`, `starts_with`, `ends_with`,
|
||||
`index_opt`, `replace_all` (non-stdlib but needed).
|
||||
- [ ] `Char`: `code`, `chr`, `escaped`, `lowercase_ascii`, `uppercase_ascii`.
|
||||
- [ ] `Int`/`Float`: arithmetic, `to_string`, `of_string_opt`, `min_int`, `max_int`.
|
||||
- [ ] `Hashtbl`: `create`, `add`, `replace`, `find`, `find_opt`, `remove`, `mem`,
|
||||
`iter`, `fold`, `length` — backed by SX mutable dict.
|
||||
- [ ] `Map.Make` functor — balanced BST backed by SX sorted dict.
|
||||
- [ ] `Set.Make` functor.
|
||||
- [ ] `Printf`: `sprintf`, `printf`, `eprintf` — format strings via `(format ...)`.
|
||||
- [ ] `Sys`: `argv`, `getenv_opt`, `getcwd` — via `perform` IO.
|
||||
- [ ] Scoreboard runner: `lib/ocaml/conformance.sh` + `scoreboard.json`.
|
||||
- [ ] Target: 150+ tests across all stdlib modules.
|
||||
The oracle role only works against a real test corpus. Vendor a slice of the official OCaml testsuite (from `ocaml/ocaml` `testsuite/tests/`).
|
||||
|
||||
### Phase 7 — Dream web framework (`lib/dream/`)
|
||||
- [ ] Pick ~100–200 tests covering: basic eval, ADTs, modules, functors, pattern matching, exceptions, refs, simple stdlib (List, Option, Result, String). Skip tests that depend on Phase 6 stdlib not implemented or on out-of-scope features (GADTs, objects, Lwt, Unix module, etc.).
|
||||
- [ ] Vendored at `lib/ocaml/testsuite/` with a manifest of which tests are included and why each excluded test was dropped.
|
||||
- [ ] `lib/ocaml/conformance.sh` runs the slice via the epoch protocol, writes `lib/ocaml/scoreboard.{json,md}`.
|
||||
- [ ] Each iteration after Phase 5.1 lands: scoreboard is the regression bar, just like other guests.
|
||||
- [ ] License: official OCaml testsuite is LGPL — confirm rose-ash repo can vendor LGPL test files (header preserved). If not, write equivalent tests from scratch sourced from the OCaml manual.
|
||||
|
||||
The five types: `request`, `response`, `handler = request -> response`,
|
||||
`middleware = handler -> handler`, `route`. Everything else is a function over these.
|
||||
### Phase 6 — Minimal stdlib slice
|
||||
|
||||
- [ ] **Core types** in `lib/dream/types.sx`: request/response records, route record.
|
||||
- [ ] **Router** in `lib/dream/router.sx`:
|
||||
- `dream-get path handler`, `dream-post path handler`, etc. for all HTTP methods.
|
||||
- `dream-scope prefix middlewares routes` — prefix mount with middleware chain.
|
||||
- `dream-router routes` — dispatch tree, returns handler; no match → 404.
|
||||
- Path param extraction: `:name` segments, `**` wildcard.
|
||||
- `dream-param req name` — retrieve matched path param.
|
||||
- [ ] **Middleware** in `lib/dream/middleware.sx`:
|
||||
- `dream-pipeline middlewares handler` — compose middleware left-to-right.
|
||||
- `dream-no-middleware` — identity.
|
||||
- Logger: `(dream-logger next req)` — logs method, path, status, timing.
|
||||
- Content-type sniffer.
|
||||
- [ ] **Sessions** in `lib/dream/session.sx`:
|
||||
- Cookie-backed session middleware.
|
||||
- `dream-session-field req key`, `dream-set-session-field req key val`.
|
||||
- `dream-invalidate-session req`.
|
||||
- [ ] **Flash messages** in `lib/dream/flash.sx`:
|
||||
- `dream-flash-middleware` — single-request cookie store.
|
||||
- `dream-add-flash-message req category msg`.
|
||||
- `dream-flash-messages req` — returns list of `(category, msg)`.
|
||||
- [ ] **Forms + CSRF** in `lib/dream/form.sx`:
|
||||
- `dream-form req` — returns `(Ok fields)` or `(Err :csrf-token-invalid)`.
|
||||
- `dream-multipart req` — streaming multipart form data.
|
||||
- CSRF middleware: stateless signed tokens, session-scoped.
|
||||
- `dream-csrf-tag req` — returns hidden input fragment for SX templates.
|
||||
- [ ] **WebSockets** in `lib/dream/websocket.sx`:
|
||||
- `dream-websocket handler` — upgrades request; handler `(fn (ws) ...)`.
|
||||
- `dream-send ws msg`, `dream-receive ws`, `dream-close ws`.
|
||||
- [ ] **Static files:** `dream-static root-path` — serves files, ETags, range requests.
|
||||
- [ ] **`dream-run`**: wires root handler into SX's `perform (:http-listen ...)`.
|
||||
- [ ] **Demos** in `lib/dream/demos/`:
|
||||
- `hello.ml` → `lib/dream/demos/hello.sx`: "Hello, World!" route.
|
||||
- `counter.ml` → `lib/dream/demos/counter.sx`: in-memory counter with sessions.
|
||||
- `chat.ml` → `lib/dream/demos/chat.sx`: multi-room WebSocket chat.
|
||||
- `todo.ml` → `lib/dream/demos/todo.sx`: CRUD list with forms + CSRF.
|
||||
- [ ] Tests in `lib/dream/tests/`: routing dispatch, middleware composition,
|
||||
session round-trip, CSRF accept/reject, flash read-after-write — 60+ tests.
|
||||
**Trimmed from the original 150+ functions to ~30** — only what HM tests, the Phase 5.1 testsuite slice, and the oracle role need. Full stdlib (`Hashtbl.iter`, `Map.Make`, `Set.Make`, `Format`, `Sys`, `Bytes`, …) becomes a conditional follow-on if a target user appears.
|
||||
|
||||
### Phase 8 — ReasonML syntax variant (`lib/reasonml/`)
|
||||
- [ ] `List`: `map`, `filter`, `fold_left`, `fold_right`, `length`, `rev`, `append`, `iter`, `for_all`, `exists`, `find_opt`, `mem`.
|
||||
- [ ] `Option`: `map`, `bind`, `get`, `value`, `is_none`, `is_some`.
|
||||
- [ ] `Result`: `map`, `bind`, `get_ok`, `get_error`, `is_ok`, `is_error`.
|
||||
- [ ] `String`: `length`, `sub`, `concat`, `split_on_char`, `trim`.
|
||||
- [ ] `Printf`: `sprintf` only — wires to SX `(format ...)`.
|
||||
- [ ] `Hashtbl`: `create`, `add`, `find_opt`, `replace`, `mem` — backed by SX mutable dict.
|
||||
- [ ] Tests in `lib/ocaml/tests/stdlib.sx` — 40+ tests across the slice. Phase 5.1 testsuite slice exercises these in real programs.
|
||||
|
||||
ReasonML is OCaml with a JS-friendly surface: semicolons, `let` with `=` everywhere,
|
||||
`=>` for lambdas, `switch` for match, `{j|...|j}` string interpolation. Same semantics —
|
||||
different tokenizer + parser, same `lib/ocaml/transpile.sx` output.
|
||||
### Phase 7 — Dream web framework
|
||||
|
||||
- [ ] **Tokenizer** in `lib/reasonml/tokenizer.sx`:
|
||||
- `let x = e;` binding syntax (semicolons required).
|
||||
- `(x, y) => e` arrow function syntax.
|
||||
- `switch (x) { | Pat => e | ... }` for match.
|
||||
- JSX: `<Comp prop=val />`, `<div>children</div>`.
|
||||
- String interpolation: `{j|hello $(name)|j}`.
|
||||
- Type annotations: `x : int`, `let f : int => int = x => x + 1`.
|
||||
- [ ] **Parser** in `lib/reasonml/parser.sx`:
|
||||
- Produce same OCaml AST nodes as `lib/ocaml/parser.sx`.
|
||||
- JSX → SX component calls: `<Comp x=1 />` → `(~comp :x 1)`.
|
||||
- Multi-arg functions: `(x, y) => e` → auto-curried pair.
|
||||
- [ ] Shared transpiler: `lib/reasonml/transpile.sx` delegates to
|
||||
`lib/ocaml/transpile.sx` (parse → ReasonML AST → OCaml AST → SX AST).
|
||||
- [ ] Tests in `lib/reasonml/tests/`: tokenizer, parser, eval, JSX — 40+ tests.
|
||||
- [ ] ReasonML Dream demos: translate Phase 7 demos to ReasonML syntax.
|
||||
**Moved to `plans/dream-on-sx.md`.** Spins up only if a target user appears. The plan there inherits OCaml-on-SX Phases 1–5 + the Phase 6 slice plus whatever additional stdlib Dream needs (likely `Bytes`, `Format`, more `String`, `Sys.argv`).
|
||||
|
||||
### Phase 8 — ReasonML syntax variant `[deferred]`
|
||||
|
||||
`[deferred — depends on Phases 1–2 landing + decision to ship a user-facing OCaml]`.
|
||||
|
||||
ReasonML is OCaml with a JS-friendly surface: semicolons, `let` with `=` everywhere, `=>` for lambdas, `switch` for match, `{j|...|j}` string interpolation. Same semantics — different tokenizer + parser, same `lib/ocaml/transpile.sx` output.
|
||||
|
||||
The cheapest user-facing payoff in the plan but only worthwhile if there's a concrete user goal (e.g. JSX-flavoured frontend syntax for SX components, attracting React refugees). Don't start without that target.
|
||||
|
||||
- [ ] **Tokenizer** in `lib/reasonml/tokenizer.sx`: `let x = e;`, `(x, y) => e`, `switch (x) { | Pat => e | ... }`, JSX, `{j|hello $(name)|j}`, `let f : int => int = x => x + 1`.
|
||||
- [ ] **Parser** in `lib/reasonml/parser.sx`: produce same OCaml AST nodes; JSX → SX component calls (`<Comp x=1 />` → `(~comp :x 1)`); auto-curry multi-arg.
|
||||
- [ ] Shared transpiler delegates to `lib/ocaml/transpile.sx`.
|
||||
- [ ] Tests in `lib/reasonml/tests/` — 40+.
|
||||
|
||||
## The meta-circular angle
|
||||
|
||||
SX is bootstrapped to OCaml (`hosts/ocaml/`). Running OCaml inside SX running on OCaml is
|
||||
the "mother tongue" closure: OCaml → SX → OCaml. This means:
|
||||
SX is bootstrapped to OCaml (`hosts/ocaml/`). Running OCaml inside SX running on OCaml is the "mother tongue" closure: OCaml → SX → OCaml. This means:
|
||||
|
||||
- The OCaml host's native pattern matching and ADTs are exact reference semantics for
|
||||
the SX-level implementation — any mismatch is a bug.
|
||||
- The SX `match` / `define-type` primitives (Phase 6 of the primitives roadmap) were
|
||||
built knowing OCaml was the intended target.
|
||||
- The OCaml host's native pattern matching and ADTs are exact reference semantics for the SX-level implementation — any mismatch is a bug.
|
||||
- The SX `match` / `define-type` primitives were built knowing OCaml was the intended target.
|
||||
- When debugging the transpiler, the OCaml REPL is always available as oracle.
|
||||
- Dream running in SX can serve the sx.rose-ash.com docs site — the framework that
|
||||
describes the runtime it runs on.
|
||||
- The vendored testsuite slice (Phase 5.1) makes the oracle role mechanical, not just rhetorical.
|
||||
|
||||
## Key dependencies
|
||||
|
||||
- **Phase 6 ADT primitive** (`define-type`/`match`) — required before Phase 3.
|
||||
- **`perform`/`cek-resume`** IO suspension — required before Phase 7 (Dream async).
|
||||
- **lib-guest Steps 0–7** — must complete before OCaml-on-SX starts. OCaml consumes `lib/guest/lex.sx`, `lib/guest/pratt.sx`, `lib/guest/match.sx`. Hand-rolling defeats the substrate-validation goal.
|
||||
- **Phase 6 ADT primitive** (`define-type`/`match`) in the SX core — required before Phase 3.
|
||||
- **HO forms** and first-class lambdas — already in spec, no blocker.
|
||||
- **Module system** (Phase 4) is independent of type inference (Phase 5) — can overlap.
|
||||
- **ReasonML** (Phase 8) can start once OCaml parser is stable (after Phase 2).
|
||||
- **lib-guest Step 8** (HM extraction) — *waits on this plan's Phase 5*. The two are paired.
|
||||
|
||||
## Progress log
|
||||
|
||||
_Newest first._
|
||||
|
||||
_(awaiting phase 1)_
|
||||
_(awaiting lib-guest Steps 0–7)_
|
||||
|
||||
## Blockers
|
||||
|
||||
|
||||
126
plans/probabilistic-on-sx.md
Normal file
126
plans/probabilistic-on-sx.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# Probabilistic-on-SX: weighted nondeterminism + traces + inference
|
||||
|
||||
Programs declare distributions; the runtime infers. The most orthogonal addition to the set — every existing guest treats execution as deterministic-or-resumable. Probabilistic programming requires *weighted, traceable* executions with explicit posterior-inference machinery on top. **Anglican** (Wood et al.) or **Church** (Goodman et al.) is the closest reference; we'll target a Church-flavoured core.
|
||||
|
||||
**The chisel:** *trace*. What does it mean to record an execution? What's a probability weight? How do branches in `conde`-like nondeterminism differ from `sample`/`observe` choices? The substrate has multi-shot continuations (a prerequisite for any decent inference algorithm) but doesn't articulate weights or traces — implementing a probabilistic language forces it to.
|
||||
|
||||
**What this exposes about the substrate:**
|
||||
- Whether `cek-resume` can be invoked many times per `perform` with different values (multi-shot we know works; *parameterised* multi-shot is the question).
|
||||
- Whether traces — sequences of (random-variable-id, sampled-value, log-weight) — fit naturally in the value space.
|
||||
- Whether the substrate can support efficient *trace replay* (start a fresh execution but force certain random choices to specific values).
|
||||
- Whether handler/effect machinery (lib/guest/effects/ when it exists) can host inference-as-handler.
|
||||
|
||||
**End-state goal:** **Anglican-style probabilistic Scheme** — `sample`, `observe`, basic distribution library, importance sampling, MCMC (Metropolis-Hastings), and a path to variational inference. Programs are distributions; `query expr` returns a distribution over outcomes.
|
||||
|
||||
## Ground rules
|
||||
- Scope: `lib/probabilistic/**` and `plans/probabilistic-on-sx.md` only. Substrate gaps → `sx-improvements.md`.
|
||||
- Consumes from `lib/guest/`: `core/lex`, `core/pratt`, `core/ast`, `core/match`. Possibly `effects/` once that sub-layer exists (inference algorithms are naturally handlers over `sample`/`observe`).
|
||||
- **May propose** `lib/guest/probabilistic/` sub-layer — trace-recording infrastructure, weight-algebra primitives (log-domain arithmetic), inference combinators, distribution constructors. Second consumer would be a future Pyro-style language or a Bayesian DSL.
|
||||
- Branch: `loops/probabilistic`. Standard worktree pattern.
|
||||
|
||||
## Architecture sketch
|
||||
|
||||
```
|
||||
Probabilistic source text (Church-flavoured: scheme + sample/observe)
|
||||
│
|
||||
▼
|
||||
lib/probabilistic/parser.sx — s-expression reader
|
||||
│
|
||||
▼
|
||||
lib/probabilistic/eval.sx — pure evaluator (deterministic except at sample/observe)
|
||||
│ sample/observe are perform-shaped: suspend execution,
|
||||
│ let inference algorithm decide what to do
|
||||
▼
|
||||
lib/probabilistic/inference/ — handlers that interpret sample/observe:
|
||||
│ importance.sx importance sampling, likelihood-weighting
|
||||
│ mh.sx Metropolis-Hastings (proposal kernels)
|
||||
│ variational.sx mean-field VI
|
||||
│
|
||||
▼
|
||||
lib/probabilistic/distributions.sx — uniform, normal, gamma, beta, dirichlet,
|
||||
mixture, conditional, etc.
|
||||
```
|
||||
|
||||
## Semantic mappings
|
||||
|
||||
| Probabilistic construct | SX mapping |
|
||||
|------------------------|-----------|
|
||||
| `(sample (uniform 0 1))` | `(perform (:sample (uniform 0 1)))` — inference handler decides actual value |
|
||||
| `(observe (normal 0 1) 0.5)` | `(perform (:observe (normal 0 1) 0.5))` — adds log-prob to weight |
|
||||
| `(query body)` | run `body` under inference handler; return weighted samples |
|
||||
| `(uniform a b)` | distribution value: `{:type :dist :family :uniform :params (a b)}` |
|
||||
| `(score lpdf x)` | accumulate log-prob; equivalent to observe |
|
||||
| Trace | `(list (:choice id sampled-value log-weight) ...)` — first-class value |
|
||||
|
||||
The key trick: `sample` and `observe` aren't primitives — they're effect requests. The inference algorithm is a handler that interprets them. Importance sampling samples each `sample` from the prior and accumulates weights from each `observe`. MH proposes changes to the trace and accepts/rejects.
|
||||
|
||||
## Roadmap
|
||||
|
||||
### Phase 1 — Parser + deterministic core
|
||||
- [ ] Scheme-flavoured parser (s-expressions, `let`, `lambda`, `if`, arithmetic, lists).
|
||||
- [ ] Deterministic evaluator running on SX CEK.
|
||||
- [ ] Tests: standard Scheme programs run.
|
||||
|
||||
### Phase 2 — `sample` / `observe` as effects
|
||||
- [ ] `sample dist` → `perform :sample`.
|
||||
- [ ] `observe dist value` → `perform :observe`.
|
||||
- [ ] Default handler: forward sampling, no inference (just produce a draw).
|
||||
- [ ] Tests: simple stochastic programs (coin flip, sum-of-dice) produce different results across runs.
|
||||
|
||||
### Phase 3 — Distribution library
|
||||
- [ ] `uniform`, `normal`, `gamma`, `beta`, `bernoulli`, `categorical`, `dirichlet`, `poisson`.
|
||||
- [ ] Each carries `(sample-fn, log-prob-fn)`.
|
||||
- [ ] Tests: log-prob of known density values matches reference.
|
||||
|
||||
### Phase 4 — Trace recording + replay
|
||||
- [ ] Tracing handler: every `sample` records `{:id :value :log-weight}` in a trace value.
|
||||
- [ ] Replay handler: given a trace, force `sample` to return the recorded value when called with the same `id`.
|
||||
- [ ] Tests: record a trace, replay it, get identical outputs.
|
||||
|
||||
### Phase 5 — Importance sampling
|
||||
- [ ] `importance-sample n query` runs `query` `n` times under sampling handler.
|
||||
- [ ] Each run accumulates log-weights from `observe` calls.
|
||||
- [ ] Returns weighted samples.
|
||||
- [ ] Tests: posterior over a coin's bias given Bernoulli observations.
|
||||
|
||||
### Phase 6 — Metropolis-Hastings
|
||||
- [ ] `mh n query` runs MH for `n` steps.
|
||||
- [ ] Each step: pick a random choice in the current trace, propose a new value, accept/reject by Hastings ratio.
|
||||
- [ ] Multi-shot continuation usage: re-execute from the proposed-changed point onward.
|
||||
- [ ] Tests: gaussian regression, change-point detection, mixture clustering.
|
||||
|
||||
### Phase 7 — Mean-field variational inference
|
||||
- [ ] Approximate posterior as product of independent simple distributions.
|
||||
- [ ] Optimise ELBO via gradient ascent.
|
||||
- [ ] Requires automatic differentiation — `lib/probabilistic/autodiff.sx` (forward-mode minimum).
|
||||
- [ ] Tests: normal-normal model, ELBO converges to known truth.
|
||||
|
||||
### Phase 8 — Standard library + idioms
|
||||
- [ ] Mixture models, Gaussian processes, hidden Markov models, change-point models.
|
||||
- [ ] Tests: each as an end-to-end test that should give roughly known posteriors.
|
||||
|
||||
### Phase 9 — Propose `lib/guest/probabilistic/`
|
||||
- [ ] Identify reusable trace + weight infrastructure (log-domain arithmetic, ESS, sample weighting).
|
||||
- [ ] Wait for a second consumer before extracting.
|
||||
|
||||
## lib/guest feedback loop
|
||||
|
||||
**Consumes:** `core/lex`, `core/pratt`, `core/ast`, `core/match`. Future: `effects/` for handler-based inference.
|
||||
|
||||
**Stresses substrate:** parameterised multi-shot continuations (each MH step replays from a chosen point with a new value); efficient trace storage; whether `perform`/`cek-resume` survives nesting (handler within handler — inference inside another inference).
|
||||
|
||||
**May propose:** `lib/guest/probabilistic/` — trace primitives, weight algebra (log-sum-exp etc.), distribution interfaces.
|
||||
|
||||
**What it teaches:** whether SX's effect/continuation machinery is up to *real* multi-shot work, not just textbook examples. Inference algorithms call `cek-resume` thousands of times per query; if the substrate has hidden quadratic costs in continuation manipulation, this surfaces them.
|
||||
|
||||
## References
|
||||
- Goodman, Mansinghka, Roy, Bonawitz, Tenenbaum, "Church: a language for generative models" (UAI 2008).
|
||||
- Wood, van de Meent, Mansinghka, "A new approach to probabilistic programming inference" (AISTATS 2014) — Anglican.
|
||||
- van de Meent, Paige, Yang, Wood, "An Introduction to Probabilistic Programming" (arXiv 2018).
|
||||
- Bingham et al., "Pyro: Deep Universal Probabilistic Programming" (JMLR 2019).
|
||||
|
||||
## Progress log
|
||||
_(awaiting Phase 1 — depends on multi-shot continuation stability)_
|
||||
|
||||
## Blockers
|
||||
_(none yet — main concern is hidden substrate costs in continuation manipulation)_
|
||||
160
plans/restore-datalog.sh
Executable file
160
plans/restore-datalog.sh
Executable file
@@ -0,0 +1,160 @@
|
||||
#!/usr/bin/env bash
|
||||
# restore-datalog.sh — print recovery state for the Datalog-on-SX loop.
|
||||
#
|
||||
# The loop runs as a Claude Code instance inside a tmux session named `datalog`,
|
||||
# operating in a git worktree at /root/rose-ash-loops/datalog on branch
|
||||
# loops/datalog. This script shows you where things stand. To respawn, see the
|
||||
# bottom of the output.
|
||||
#
|
||||
# Usage:
|
||||
# bash plans/restore-datalog.sh # status snapshot
|
||||
# bash plans/restore-datalog.sh --print # also cat the briefing
|
||||
#
|
||||
set -uo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
WT="/root/rose-ash-loops/datalog"
|
||||
|
||||
echo "=== datalog loop state ==="
|
||||
echo
|
||||
if [ -d "$WT" ]; then
|
||||
echo "Worktree: $WT"
|
||||
echo "Branch: $(git -C "$WT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '?')"
|
||||
echo "HEAD: $(git -C "$WT" log -1 --oneline 2>/dev/null || echo '?')"
|
||||
else
|
||||
echo "Worktree: MISSING ($WT)"
|
||||
echo " Recreate with:"
|
||||
echo " git worktree add /root/rose-ash-loops/datalog -b loops/datalog architecture"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Recent commits on lib/datalog/ + plan ==="
|
||||
if [ -d "$WT" ]; then
|
||||
git -C "$WT" log -15 --oneline -- lib/datalog/ plans/datalog-on-sx.md plans/agent-briefings/datalog-loop.md 2>/dev/null \
|
||||
|| echo " (none yet)"
|
||||
else
|
||||
echo " (worktree missing)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== lib/datalog/ contents ==="
|
||||
if [ -d "$WT/lib/datalog" ]; then
|
||||
ls -1 "$WT/lib/datalog/" 2>/dev/null | sed 's/^/ /'
|
||||
else
|
||||
echo " (lib/datalog/ does not exist yet — Phase 1 not started)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== lib/guest/ prerequisites ==="
|
||||
for f in lib/guest/lex.sx lib/guest/pratt.sx lib/guest/match.sx lib/guest/ast.sx; do
|
||||
if [ -f "$f" ]; then
|
||||
printf " ✓ %s (%d lines)\n" "$f" "$(wc -l < "$f")"
|
||||
else
|
||||
printf " ✗ %s MISSING\n" "$f"
|
||||
fi
|
||||
done
|
||||
echo
|
||||
|
||||
echo "=== Plan progress (phase checkboxes) ==="
|
||||
if [ -f plans/datalog-on-sx.md ]; then
|
||||
awk '/^### Phase / {phase=$0; print " " phase; phase_seen=1; next}
|
||||
/^- \[/ && phase_seen { print " " $0 }
|
||||
/^## [^#]/ {phase_seen=0}' plans/datalog-on-sx.md \
|
||||
| head -80
|
||||
else
|
||||
echo " plans/datalog-on-sx.md NOT found"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Tests + scoreboard ==="
|
||||
if [ -d "$WT/lib/datalog/tests" ]; then
|
||||
ls -1 "$WT/lib/datalog/tests/" 2>/dev/null | sed 's/^/ /'
|
||||
else
|
||||
echo " (no tests yet)"
|
||||
fi
|
||||
if [ -f "$WT/lib/datalog/scoreboard.json" ]; then
|
||||
echo " ✓ scoreboard.json present"
|
||||
python3 -c "import json
|
||||
try:
|
||||
d=json.load(open('$WT/lib/datalog/scoreboard.json'))
|
||||
t=d.get('totals',d.get('overall',{}))
|
||||
print(f\" totals: pass={t.get('pass','?')} fail={t.get('fail','?')}\")
|
||||
except Exception as e: print(f' (read error: {e})')" 2>/dev/null
|
||||
else
|
||||
echo " (no scoreboard yet)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== sx_server.exe ==="
|
||||
if [ -x hosts/ocaml/_build/default/bin/sx_server.exe ]; then
|
||||
echo " ✓ built"
|
||||
else
|
||||
echo " ✗ NOT built — loop conformance runs need it. Run: sx_build target=ocaml"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== tmux session 'datalog' ==="
|
||||
if command -v tmux >/dev/null && tmux has-session -t datalog 2>/dev/null; then
|
||||
echo " ✓ session live"
|
||||
echo " Attach: tmux attach -t datalog"
|
||||
echo " Last 8 visible lines:"
|
||||
tmux capture-pane -t datalog -p 2>/dev/null \
|
||||
| grep -v '^[[:space:]]*$' \
|
||||
| tail -8 \
|
||||
| sed 's/^/ /'
|
||||
else
|
||||
echo " ✗ session not running"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Remote loops/datalog ==="
|
||||
if git ls-remote --exit-code origin loops/datalog >/dev/null 2>&1; then
|
||||
echo " ✓ origin/loops/datalog exists"
|
||||
if [ -d "$WT" ]; then
|
||||
AHEAD=$(git -C "$WT" rev-list --count origin/loops/datalog..HEAD 2>/dev/null || echo "?")
|
||||
BEHIND=$(git -C "$WT" rev-list --count HEAD..origin/loops/datalog 2>/dev/null || echo "?")
|
||||
echo " local ahead: $AHEAD, local behind: $BEHIND"
|
||||
fi
|
||||
else
|
||||
echo " (origin/loops/datalog not yet pushed)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Briefing ==="
|
||||
[ -f plans/agent-briefings/datalog-loop.md ] \
|
||||
&& echo " plans/agent-briefings/datalog-loop.md" \
|
||||
|| echo " briefing NOT found"
|
||||
echo
|
||||
|
||||
echo "=== To respawn ==="
|
||||
cat <<'EOF'
|
||||
If the worktree is missing:
|
||||
|
||||
git worktree add /root/rose-ash-loops/datalog -b loops/datalog architecture
|
||||
# ALWAYS patch .mcp.json immediately — fresh worktrees have no _build/,
|
||||
# so the relative-path mcp_tree.exe will fail and won't reconnect from
|
||||
# inside a running claude. Use the main repo's binary via absolute path:
|
||||
sed -i 's|"./hosts/ocaml/_build/default/bin/mcp_tree.exe"|"/root/rose-ash/hosts/ocaml/_build/default/bin/mcp_tree.exe"|' \
|
||||
/root/rose-ash-loops/datalog/.mcp.json
|
||||
|
||||
If the tmux session died:
|
||||
|
||||
tmux new-session -d -s datalog -c /root/rose-ash-loops/datalog
|
||||
tmux send-keys -t datalog 'claude' Enter
|
||||
# wait until the Claude UI box appears, then:
|
||||
tmux send-keys -t datalog 'You are the Datalog-on-SX loop runner. Read /root/rose-ash/plans/agent-briefings/datalog-loop.md in full and follow the iteration protocol indefinitely. lib-guest is complete; consume lib/guest/lex.sx, lib/guest/pratt.sx, lib/guest/match.sx, lib/guest/ast.sx wherever they fit — you are the natural first real consumer of ast.sx. Worktree: /root/rose-ash-loops/datalog on branch loops/datalog. Push to origin/loops/datalog after every commit. Never push to main or architecture. Resume from the first unchecked [ ] in plans/datalog-on-sx.md.' Enter Enter
|
||||
|
||||
Note: on first run the loop will hit a permission prompt to read the briefing
|
||||
outside the worktree. Press "2" to allow agent-briefings/ for the session.
|
||||
|
||||
If the session is alive but stuck, attach with `tmux attach -t datalog` and
|
||||
unstick manually. The plan file is the source of truth — the loop reads it
|
||||
fresh every iteration and picks up wherever the queue left off.
|
||||
EOF
|
||||
|
||||
if [ "${1:-}" = "--print" ]; then
|
||||
echo
|
||||
echo "=== Briefing contents ==="
|
||||
[ -f plans/agent-briefings/datalog-loop.md ] && cat plans/agent-briefings/datalog-loop.md
|
||||
fi
|
||||
159
plans/restore-jit-perf.sh
Executable file
159
plans/restore-jit-perf.sh
Executable file
@@ -0,0 +1,159 @@
|
||||
#!/usr/bin/env bash
|
||||
# restore-jit-perf.sh — print recovery state for the JIT perf regression investigation.
|
||||
#
|
||||
# This is a substrate investigation, not a steady-state loop. It runs as a Claude
|
||||
# Code instance inside a tmux session named `jit-perf`, operating in a git worktree
|
||||
# at /root/rose-ash-bugs/jit-perf on branch bugs/jit-perf. Unlike language loops,
|
||||
# this one does NOT push (per the plan, push to architecture only after Phase 5
|
||||
# passes; never push to main).
|
||||
#
|
||||
# Usage:
|
||||
# bash plans/restore-jit-perf.sh # status snapshot
|
||||
# bash plans/restore-jit-perf.sh --print # also cat the plan
|
||||
#
|
||||
set -uo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
WT="/root/rose-ash-bugs/jit-perf"
|
||||
|
||||
echo "=== jit-perf investigation state ==="
|
||||
echo
|
||||
if [ -d "$WT" ]; then
|
||||
echo "Worktree: $WT"
|
||||
echo "Branch: $(git -C "$WT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '?')"
|
||||
echo "HEAD: $(git -C "$WT" log -1 --oneline 2>/dev/null || echo '?')"
|
||||
else
|
||||
echo "Worktree: MISSING ($WT)"
|
||||
echo " Recreate with:"
|
||||
echo " git worktree add /root/rose-ash-bugs/jit-perf -b bugs/jit-perf architecture"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Recent commits on substrate paths + plan ==="
|
||||
if [ -d "$WT" ]; then
|
||||
git -C "$WT" log -15 --oneline -- spec/ hosts/ocaml/lib/ hosts/javascript/ lib/tcl/test.sh plans/jit-perf-regression.md 2>/dev/null \
|
||||
|| echo " (none yet)"
|
||||
else
|
||||
echo " (worktree missing)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Current phase progress ==="
|
||||
if [ -f plans/jit-perf-regression.md ]; then
|
||||
awk '/^### Phase / {phase=$0; print " " phase; phase_seen=1; next}
|
||||
/^- \[/ && phase_seen { print " " $0 }
|
||||
/^## [^#]/ {phase_seen=0}' plans/jit-perf-regression.md \
|
||||
| head -60
|
||||
else
|
||||
echo " plans/jit-perf-regression.md NOT found"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Phase 1 perf-table progress (look for entries in plan Progress log) ==="
|
||||
if [ -f plans/jit-perf-regression.md ]; then
|
||||
awk '/^## Progress log/{flag=1;next} /^## /{flag=0} flag{print " "$0}' plans/jit-perf-regression.md \
|
||||
| grep -v '^ *$' \
|
||||
| head -20
|
||||
else
|
||||
echo " (no plan)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Bisect state (Phase 2) ==="
|
||||
if [ -d "$WT" ] && [ -f "$WT/.git/BISECT_LOG" ]; then
|
||||
echo " ✓ bisect in progress"
|
||||
git -C "$WT" bisect log 2>/dev/null | tail -10 | sed 's/^/ /'
|
||||
else
|
||||
echo " (no bisect underway)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Pre-regression baseline candidate ==="
|
||||
# Heuristic: the architecture→loops/tcl merge that brought R7RS+JIT+env-as-value
|
||||
# (commit a32561a0 per the plan's hypothesis section). The first-bad commit will
|
||||
# be at or after this point.
|
||||
echo " Suggested BASELINE_GOOD anchor (per plan hypotheses): pre-a32561a0"
|
||||
git log --oneline a32561a0^..a32561a0 2>/dev/null | sed 's/^/ /' || echo " (anchor commit not found locally)"
|
||||
echo
|
||||
|
||||
echo "=== Tcl test.sh watchdog (the 30× witness) ==="
|
||||
if [ -f "$WT/lib/tcl/test.sh" ]; then
|
||||
grep -E 'timeout|TIMEOUT|deadline' "$WT/lib/tcl/test.sh" 2>/dev/null | head -3 | sed 's/^/ /'
|
||||
else
|
||||
echo " (test.sh not found)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Substrate (sx_server.exe) ==="
|
||||
if [ -x hosts/ocaml/_build/default/bin/sx_server.exe ]; then
|
||||
echo " ✓ main repo build present"
|
||||
fi
|
||||
if [ -x "$WT/hosts/ocaml/_build/default/bin/sx_server.exe" ]; then
|
||||
echo " ✓ worktree build present (good — bisect needs per-commit builds)"
|
||||
else
|
||||
echo " ✗ worktree has no _build yet (Phase 1 can use main; Phase 2 bisect needs its own)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Other active loops (perf measurements will be noisy while these run) ==="
|
||||
for s in lib-guest minikanren ocaml datalog; do
|
||||
if tmux has-session -t "$s" 2>/dev/null; then
|
||||
echo " ⚠ $s session running"
|
||||
fi
|
||||
done | head -10
|
||||
echo
|
||||
|
||||
echo "=== tmux session 'jit-perf' ==="
|
||||
if command -v tmux >/dev/null && tmux has-session -t jit-perf 2>/dev/null; then
|
||||
echo " ✓ session live"
|
||||
echo " Attach: tmux attach -t jit-perf"
|
||||
echo " Last 8 visible lines:"
|
||||
tmux capture-pane -t jit-perf -p 2>/dev/null \
|
||||
| grep -v '^[[:space:]]*$' \
|
||||
| tail -8 \
|
||||
| sed 's/^/ /'
|
||||
else
|
||||
echo " ✗ session not running"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Plan ==="
|
||||
[ -f plans/jit-perf-regression.md ] \
|
||||
&& echo " plans/jit-perf-regression.md" \
|
||||
|| echo " plan NOT found"
|
||||
echo
|
||||
|
||||
echo "=== To respawn ==="
|
||||
cat <<'EOF'
|
||||
If the worktree is missing:
|
||||
|
||||
git worktree add /root/rose-ash-bugs/jit-perf -b bugs/jit-perf architecture
|
||||
# patch .mcp.json — fresh worktrees have no _build/, so the relative
|
||||
# mcp_tree path fails. Use the main repo's binary:
|
||||
sed -i 's|"./hosts/ocaml/_build/default/bin/mcp_tree.exe"|"/root/rose-ash/hosts/ocaml/_build/default/bin/mcp_tree.exe"|' \
|
||||
/root/rose-ash-bugs/jit-perf/.mcp.json
|
||||
|
||||
If the tmux session died:
|
||||
|
||||
tmux new-session -d -s jit-perf -c /root/rose-ash-bugs/jit-perf
|
||||
tmux send-keys -t jit-perf 'claude' Enter
|
||||
# wait for the Claude UI box, accept MCP servers, then:
|
||||
tmux send-keys -t jit-perf 'You are the JIT perf regression investigation runner. Read /root/rose-ash/plans/jit-perf-regression.md in full. Resume from the first unchecked phase. Worktree: /root/rose-ash-bugs/jit-perf on branch bugs/jit-perf. Never push to main or architecture (push only after Phase 5 passes per the plan). Other loops (minikanren, ocaml, datalog) may be running — measurements will be noisy; if noise obscures signal, stop and ask before pausing them.' Enter Enter
|
||||
|
||||
This is an investigation, not a loop — phases need human-in-the-loop decisions
|
||||
(which hypothesis to chase, what fix to apply). The agent should stop and
|
||||
report at phase boundaries, not push through autonomously.
|
||||
|
||||
If you need a quiet machine for measurements, pause the language loops:
|
||||
tmux send-keys -t minikanren C-c
|
||||
tmux send-keys -t ocaml C-c
|
||||
tmux send-keys -t datalog C-c
|
||||
Resume them after phase completion by attaching and unsticking each.
|
||||
EOF
|
||||
|
||||
if [ "${1:-}" = "--print" ]; then
|
||||
echo
|
||||
echo "=== Plan contents ==="
|
||||
[ -f plans/jit-perf-regression.md ] && cat plans/jit-perf-regression.md
|
||||
fi
|
||||
107
plans/restore-lib-guest.sh
Executable file
107
plans/restore-lib-guest.sh
Executable file
@@ -0,0 +1,107 @@
|
||||
#!/usr/bin/env bash
|
||||
# restore-lib-guest.sh — print recovery state for the lib/guest extraction loop.
|
||||
#
|
||||
# The loop runs as a Claude Code instance inside a tmux session named `lib-guest`.
|
||||
# This script shows you where things stand. To respawn, see the bottom of the output.
|
||||
#
|
||||
# Usage:
|
||||
# bash plans/restore-lib-guest.sh # status snapshot
|
||||
# bash plans/restore-lib-guest.sh --print # also cat the briefing
|
||||
#
|
||||
set -uo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
echo "=== lib/guest loop state ==="
|
||||
echo
|
||||
echo "Branch: $(git rev-parse --abbrev-ref HEAD)"
|
||||
echo "HEAD: $(git log -1 --oneline)"
|
||||
echo
|
||||
|
||||
echo "=== Recent commits on lib/guest/, canaries, and plan ==="
|
||||
git log -15 --oneline -- lib/guest/ lib/lua/ lib/prolog/ lib/common-lisp/ lib/haskell/ lib/tcl/ plans/lib-guest.md plans/agent-briefings/lib-guest-loop.md 2>/dev/null \
|
||||
|| echo " (none yet)"
|
||||
echo
|
||||
|
||||
echo "=== lib/guest/ contents ==="
|
||||
if [ -d lib/guest ]; then
|
||||
ls -1 lib/guest/ 2>/dev/null | sed 's/^/ /'
|
||||
else
|
||||
echo " (lib/guest/ does not exist yet — Step 0 not started)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Baseline snapshots ==="
|
||||
if [ -d lib/guest/baseline ]; then
|
||||
for f in lib/guest/baseline/*.json; do
|
||||
[ -f "$f" ] || continue
|
||||
name=$(basename "$f" .json)
|
||||
totals=$(python3 -c "import json,sys
|
||||
try:
|
||||
d=json.load(open('$f'))
|
||||
t=d.get('totals',d.get('overall',{}))
|
||||
if t: print(f\"pass={t.get('pass','?')} fail={t.get('fail','?')}\")
|
||||
else: print('(no totals)')
|
||||
except Exception as e: print(f'(read error: {e})')" 2>/dev/null)
|
||||
printf " %-14s %s\n" "$name" "$totals"
|
||||
done
|
||||
else
|
||||
echo " (lib/guest/baseline/ does not exist yet — Step 0 not done)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Plan progress (status column) ==="
|
||||
if [ -f plans/lib-guest.md ]; then
|
||||
awk '/^\| Step \|/,/^$/' plans/lib-guest.md | grep -E '^\| [0-9]' | sed 's/^/ /' || true
|
||||
else
|
||||
echo " plans/lib-guest.md NOT found"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== sx_server.exe ==="
|
||||
if [ -x hosts/ocaml/_build/default/bin/sx_server.exe ]; then
|
||||
echo " ✓ built"
|
||||
else
|
||||
echo " ✗ NOT built — guest conformance runners need it. Run: sx_build target=ocaml"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== tmux session 'lib-guest' ==="
|
||||
if command -v tmux >/dev/null && tmux has-session -t lib-guest 2>/dev/null; then
|
||||
echo " ✓ session live"
|
||||
echo " Attach: tmux attach -t lib-guest"
|
||||
echo " Last 8 visible lines:"
|
||||
tmux capture-pane -t lib-guest -p 2>/dev/null \
|
||||
| grep -v '^[[:space:]]*$' \
|
||||
| tail -8 \
|
||||
| sed 's/^/ /'
|
||||
else
|
||||
echo " ✗ session not running"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Briefing ==="
|
||||
[ -f plans/agent-briefings/lib-guest-loop.md ] \
|
||||
&& echo " plans/agent-briefings/lib-guest-loop.md" \
|
||||
|| echo " briefing NOT found"
|
||||
echo
|
||||
|
||||
echo "=== To respawn ==="
|
||||
cat <<'EOF'
|
||||
If the tmux session died:
|
||||
|
||||
tmux new-session -d -s lib-guest -c /root/rose-ash
|
||||
tmux send-keys -t lib-guest 'claude' Enter
|
||||
# wait until the Claude UI box appears, then:
|
||||
tmux send-keys -t lib-guest 'You are the lib/guest extraction loop runner. Read /root/rose-ash/plans/agent-briefings/lib-guest-loop.md in full and follow the iteration protocol indefinitely. Resume from the first pending step in the plan. Branch: architecture. Never push, never touch main.' Enter Enter
|
||||
|
||||
If the session is alive but stuck, attach with `tmux attach -t lib-guest` and
|
||||
unstick manually. The plan file is the source of truth — the loop reads it
|
||||
fresh every iteration and picks up wherever the queue left off.
|
||||
EOF
|
||||
|
||||
if [ "${1:-}" = "--print" ]; then
|
||||
echo
|
||||
echo "=== Briefing contents ==="
|
||||
[ -f plans/agent-briefings/lib-guest-loop.md ] && cat plans/agent-briefings/lib-guest-loop.md
|
||||
fi
|
||||
145
plans/restore-minikanren.sh
Executable file
145
plans/restore-minikanren.sh
Executable file
@@ -0,0 +1,145 @@
|
||||
#!/usr/bin/env bash
|
||||
# restore-minikanren.sh — print recovery state for the miniKanren-on-SX loop.
|
||||
#
|
||||
# The loop runs as a Claude Code instance inside a tmux session named `minikanren`,
|
||||
# operating in a git worktree at /root/rose-ash-loops/minikanren on branch
|
||||
# loops/minikanren. This script shows you where things stand. To respawn, see the
|
||||
# bottom of the output.
|
||||
#
|
||||
# Usage:
|
||||
# bash plans/restore-minikanren.sh # status snapshot
|
||||
# bash plans/restore-minikanren.sh --print # also cat the briefing
|
||||
#
|
||||
set -uo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
WT="/root/rose-ash-loops/minikanren"
|
||||
|
||||
echo "=== minikanren loop state ==="
|
||||
echo
|
||||
if [ -d "$WT" ]; then
|
||||
echo "Worktree: $WT"
|
||||
echo "Branch: $(git -C "$WT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '?')"
|
||||
echo "HEAD: $(git -C "$WT" log -1 --oneline 2>/dev/null || echo '?')"
|
||||
else
|
||||
echo "Worktree: MISSING ($WT)"
|
||||
echo " Recreate with:"
|
||||
echo " git worktree add /root/rose-ash-loops/minikanren -b loops/minikanren architecture"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Recent commits on lib/minikanren/ + plan ==="
|
||||
if [ -d "$WT" ]; then
|
||||
git -C "$WT" log -15 --oneline -- lib/minikanren/ plans/minikanren-on-sx.md plans/agent-briefings/minikanren-loop.md 2>/dev/null \
|
||||
|| echo " (none yet)"
|
||||
else
|
||||
echo " (worktree missing)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== lib/minikanren/ contents ==="
|
||||
if [ -d "$WT/lib/minikanren" ]; then
|
||||
ls -1 "$WT/lib/minikanren/" 2>/dev/null | sed 's/^/ /'
|
||||
else
|
||||
echo " (lib/minikanren/ does not exist yet — Phase 1 not started)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== lib/guest/ prerequisites ==="
|
||||
for f in lib/guest/lex.sx lib/guest/pratt.sx lib/guest/match.sx; do
|
||||
if [ -f "$f" ]; then
|
||||
printf " ✓ %s (%d lines)\n" "$f" "$(wc -l < "$f")"
|
||||
else
|
||||
printf " ✗ %s MISSING\n" "$f"
|
||||
fi
|
||||
done
|
||||
echo
|
||||
|
||||
echo "=== Plan progress (phase checkboxes) ==="
|
||||
if [ -f plans/minikanren-on-sx.md ]; then
|
||||
awk '/^### Phase [0-9]/ {phase=$0; next}
|
||||
/^- \[/ && phase {
|
||||
if (!shown[phase]++) print " " phase
|
||||
print " " $0
|
||||
}
|
||||
/^### Phase / && !/^### Phase [0-9]/ {phase=""}
|
||||
/^## / && !/^### / {phase=""}' plans/minikanren-on-sx.md \
|
||||
| head -60
|
||||
else
|
||||
echo " plans/minikanren-on-sx.md NOT found"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Tests (if Phase 1+ shipped) ==="
|
||||
if [ -d "$WT/lib/minikanren/tests" ]; then
|
||||
ls -1 "$WT/lib/minikanren/tests/" 2>/dev/null | sed 's/^/ /'
|
||||
else
|
||||
echo " (no tests yet)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== sx_server.exe ==="
|
||||
if [ -x hosts/ocaml/_build/default/bin/sx_server.exe ]; then
|
||||
echo " ✓ built"
|
||||
else
|
||||
echo " ✗ NOT built — loop conformance runs need it. Run: sx_build target=ocaml"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== tmux session 'minikanren' ==="
|
||||
if command -v tmux >/dev/null && tmux has-session -t minikanren 2>/dev/null; then
|
||||
echo " ✓ session live"
|
||||
echo " Attach: tmux attach -t minikanren"
|
||||
echo " Last 8 visible lines:"
|
||||
tmux capture-pane -t minikanren -p 2>/dev/null \
|
||||
| grep -v '^[[:space:]]*$' \
|
||||
| tail -8 \
|
||||
| sed 's/^/ /'
|
||||
else
|
||||
echo " ✗ session not running"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Remote loops/minikanren ==="
|
||||
if git ls-remote --exit-code origin loops/minikanren >/dev/null 2>&1; then
|
||||
echo " ✓ origin/loops/minikanren exists"
|
||||
if [ -d "$WT" ]; then
|
||||
AHEAD=$(git -C "$WT" rev-list --count origin/loops/minikanren..HEAD 2>/dev/null || echo "?")
|
||||
BEHIND=$(git -C "$WT" rev-list --count HEAD..origin/loops/minikanren 2>/dev/null || echo "?")
|
||||
echo " local ahead: $AHEAD, local behind: $BEHIND"
|
||||
fi
|
||||
else
|
||||
echo " (origin/loops/minikanren not yet pushed)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Briefing ==="
|
||||
[ -f plans/agent-briefings/minikanren-loop.md ] \
|
||||
&& echo " plans/agent-briefings/minikanren-loop.md" \
|
||||
|| echo " briefing NOT found"
|
||||
echo
|
||||
|
||||
echo "=== To respawn ==="
|
||||
cat <<'EOF'
|
||||
If the worktree is missing:
|
||||
|
||||
git worktree add /root/rose-ash-loops/minikanren -b loops/minikanren architecture
|
||||
|
||||
If the tmux session died:
|
||||
|
||||
tmux new-session -d -s minikanren -c /root/rose-ash-loops/minikanren
|
||||
tmux send-keys -t minikanren 'claude' Enter
|
||||
# wait until the Claude UI box appears, then:
|
||||
tmux send-keys -t minikanren 'You are the miniKanren-on-SX loop runner. Read /root/rose-ash/plans/agent-briefings/minikanren-loop.md in full and follow the iteration protocol indefinitely. Run the pre-flight check first; if lib/guest/match.sx is missing or lib-guest Step 6 has regressed, stop and report. Worktree: /root/rose-ash-loops/minikanren on branch loops/minikanren. Push to origin/loops/minikanren after every commit. Never push to main or architecture. Resume from the first unchecked [ ] in plans/minikanren-on-sx.md.' Enter Enter
|
||||
|
||||
If the session is alive but stuck, attach with `tmux attach -t minikanren` and
|
||||
unstick manually. The plan file is the source of truth — the loop reads it
|
||||
fresh every iteration and picks up wherever the queue left off.
|
||||
EOF
|
||||
|
||||
if [ "${1:-}" = "--print" ]; then
|
||||
echo
|
||||
echo "=== Briefing contents ==="
|
||||
[ -f plans/agent-briefings/minikanren-loop.md ] && cat plans/agent-briefings/minikanren-loop.md
|
||||
fi
|
||||
160
plans/restore-ocaml.sh
Executable file
160
plans/restore-ocaml.sh
Executable file
@@ -0,0 +1,160 @@
|
||||
#!/usr/bin/env bash
|
||||
# restore-ocaml.sh — print recovery state for the OCaml-on-SX loop.
|
||||
#
|
||||
# The loop runs as a Claude Code instance inside a tmux session named `ocaml`,
|
||||
# operating in a git worktree at /root/rose-ash-loops/ocaml on branch
|
||||
# loops/ocaml. This script shows you where things stand. To respawn, see the
|
||||
# bottom of the output.
|
||||
#
|
||||
# Usage:
|
||||
# bash plans/restore-ocaml.sh # status snapshot
|
||||
# bash plans/restore-ocaml.sh --print # also cat the briefing
|
||||
#
|
||||
set -uo pipefail
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
WT="/root/rose-ash-loops/ocaml"
|
||||
|
||||
echo "=== ocaml loop state ==="
|
||||
echo
|
||||
if [ -d "$WT" ]; then
|
||||
echo "Worktree: $WT"
|
||||
echo "Branch: $(git -C "$WT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '?')"
|
||||
echo "HEAD: $(git -C "$WT" log -1 --oneline 2>/dev/null || echo '?')"
|
||||
else
|
||||
echo "Worktree: MISSING ($WT)"
|
||||
echo " Recreate with:"
|
||||
echo " git worktree add /root/rose-ash-loops/ocaml -b loops/ocaml architecture"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Recent commits on lib/ocaml/ + plan ==="
|
||||
if [ -d "$WT" ]; then
|
||||
git -C "$WT" log -15 --oneline -- lib/ocaml/ plans/ocaml-on-sx.md plans/agent-briefings/ocaml-loop.md 2>/dev/null \
|
||||
|| echo " (none yet)"
|
||||
else
|
||||
echo " (worktree missing)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== lib/ocaml/ contents ==="
|
||||
if [ -d "$WT/lib/ocaml" ]; then
|
||||
ls -1 "$WT/lib/ocaml/" 2>/dev/null | sed 's/^/ /'
|
||||
else
|
||||
echo " (lib/ocaml/ does not exist yet — Phase 1 not started)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== lib/guest/ prerequisites ==="
|
||||
for f in lib/guest/lex.sx lib/guest/pratt.sx lib/guest/match.sx lib/guest/layout.sx lib/guest/hm.sx; do
|
||||
if [ -f "$f" ]; then
|
||||
printf " ✓ %s (%d lines)\n" "$f" "$(wc -l < "$f")"
|
||||
else
|
||||
printf " ✗ %s MISSING\n" "$f"
|
||||
fi
|
||||
done
|
||||
echo
|
||||
|
||||
echo "=== Plan progress (phase checkboxes) ==="
|
||||
if [ -f plans/ocaml-on-sx.md ]; then
|
||||
awk '/^### Phase / {phase=$0; print " " phase; phase_seen=1; next}
|
||||
/^- \[/ && phase_seen { print " " $0 }
|
||||
/^## [^#]/ {phase_seen=0}' plans/ocaml-on-sx.md \
|
||||
| head -80
|
||||
else
|
||||
echo " plans/ocaml-on-sx.md NOT found"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Tests + scoreboard (Phase 5.1+) ==="
|
||||
if [ -d "$WT/lib/ocaml/tests" ]; then
|
||||
ls -1 "$WT/lib/ocaml/tests/" 2>/dev/null | sed 's/^/ /'
|
||||
else
|
||||
echo " (no tests yet)"
|
||||
fi
|
||||
if [ -f "$WT/lib/ocaml/scoreboard.json" ]; then
|
||||
echo " ✓ scoreboard.json present"
|
||||
python3 -c "import json
|
||||
try:
|
||||
d=json.load(open('$WT/lib/ocaml/scoreboard.json'))
|
||||
t=d.get('totals',d.get('overall',{}))
|
||||
print(f\" totals: pass={t.get('pass','?')} fail={t.get('fail','?')}\")
|
||||
except Exception as e: print(f' (read error: {e})')" 2>/dev/null
|
||||
else
|
||||
echo " (no scoreboard yet — Phase 5.1 not landed)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== sx_server.exe ==="
|
||||
if [ -x hosts/ocaml/_build/default/bin/sx_server.exe ]; then
|
||||
echo " ✓ built"
|
||||
else
|
||||
echo " ✗ NOT built — loop conformance runs need it. Run: sx_build target=ocaml"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== tmux session 'ocaml' ==="
|
||||
if command -v tmux >/dev/null && tmux has-session -t ocaml 2>/dev/null; then
|
||||
echo " ✓ session live"
|
||||
echo " Attach: tmux attach -t ocaml"
|
||||
echo " Last 8 visible lines:"
|
||||
tmux capture-pane -t ocaml -p 2>/dev/null \
|
||||
| grep -v '^[[:space:]]*$' \
|
||||
| tail -8 \
|
||||
| sed 's/^/ /'
|
||||
else
|
||||
echo " ✗ session not running"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Remote loops/ocaml ==="
|
||||
if git ls-remote --exit-code origin loops/ocaml >/dev/null 2>&1; then
|
||||
echo " ✓ origin/loops/ocaml exists"
|
||||
if [ -d "$WT" ]; then
|
||||
AHEAD=$(git -C "$WT" rev-list --count origin/loops/ocaml..HEAD 2>/dev/null || echo "?")
|
||||
BEHIND=$(git -C "$WT" rev-list --count HEAD..origin/loops/ocaml 2>/dev/null || echo "?")
|
||||
echo " local ahead: $AHEAD, local behind: $BEHIND"
|
||||
fi
|
||||
else
|
||||
echo " (origin/loops/ocaml not yet pushed)"
|
||||
fi
|
||||
echo
|
||||
|
||||
echo "=== Briefing ==="
|
||||
[ -f plans/agent-briefings/ocaml-loop.md ] \
|
||||
&& echo " plans/agent-briefings/ocaml-loop.md" \
|
||||
|| echo " briefing NOT found"
|
||||
echo
|
||||
|
||||
echo "=== To respawn ==="
|
||||
cat <<'EOF'
|
||||
If the worktree is missing:
|
||||
|
||||
git worktree add /root/rose-ash-loops/ocaml -b loops/ocaml architecture
|
||||
# ALWAYS patch .mcp.json immediately — fresh worktrees have no _build/,
|
||||
# so the relative-path mcp_tree.exe will fail and won't reconnect from
|
||||
# inside a running claude. Use the main repo's binary via absolute path:
|
||||
sed -i 's|"./hosts/ocaml/_build/default/bin/mcp_tree.exe"|"/root/rose-ash/hosts/ocaml/_build/default/bin/mcp_tree.exe"|' \
|
||||
/root/rose-ash-loops/ocaml/.mcp.json
|
||||
|
||||
If the tmux session died:
|
||||
|
||||
tmux new-session -d -s ocaml -c /root/rose-ash-loops/ocaml
|
||||
tmux send-keys -t ocaml 'claude' Enter
|
||||
# wait until the Claude UI box appears, then:
|
||||
tmux send-keys -t ocaml 'You are the OCaml-on-SX loop runner. Read /root/rose-ash/plans/agent-briefings/ocaml-loop.md in full and follow the iteration protocol indefinitely. Run the pre-flight check first; partial-kit-shipped status on lib-guest Steps 5-8 is expected and fine. Worktree: /root/rose-ash-loops/ocaml on branch loops/ocaml. Push to origin/loops/ocaml after every commit. Never push to main or architecture. Resume from the first unchecked [ ] in plans/ocaml-on-sx.md.' Enter Enter
|
||||
|
||||
Note: on first run the loop will hit a permission prompt to read the briefing
|
||||
outside the worktree. Press "2" to allow agent-briefings/ for the session.
|
||||
|
||||
If the session is alive but stuck, attach with `tmux attach -t ocaml` and
|
||||
unstick manually. The plan file is the source of truth — the loop reads it
|
||||
fresh every iteration and picks up wherever the queue left off.
|
||||
EOF
|
||||
|
||||
if [ "${1:-}" = "--print" ]; then
|
||||
echo
|
||||
echo "=== Briefing contents ==="
|
||||
[ -f plans/agent-briefings/ocaml-loop.md ] && cat plans/agent-briefings/ocaml-loop.md
|
||||
fi
|
||||
Reference in New Issue
Block a user