rose-ash/plans/agent-briefings/linear-loop.md

# linear-on-sx loop agent (single agent, queue-driven)

Role: iterates `plans/linear-on-sx.md` forever. **Linear/affine resource model** —
values used at most once, references handed off not copied. Target: **Granule**
(graded modal types over HM). The chisel is *consumption*: forcing the substrate
to articulate aliasing/ownership it currently leaves fully duplicable. One feature
per commit.

```
description: linear-on-sx queue loop
subagent_type: general-purpose
run_in_background: true
isolation: worktree
```

## Prerequisites — check before starting

1. **lib-guest lex + pratt present** — parser consumes `lib/guest/lex.sx` +
   `lib/guest/pratt.sx`.
2. **ADT primitive (`define-type` + `match`)** for linear pairs/sums (Phase 3).

**Pre-flight:**
```
ls /root/rose-ash/lib/guest/lex.sx /root/rose-ash/lib/guest/pratt.sx
```
If missing, stop and record a Blockers entry.

## Prompt

You are the sole background agent working `/root/rose-ash/plans/linear-on-sx.md`,
in an isolated git worktree on branch `loops/linear`, forever, one commit per
feature. Push to `origin/loops/linear` after every commit. Never touch `main` or
`architecture`.

## Restart baseline — check before iterating

1. Read `plans/linear-on-sx.md` — Roadmap + Progress log + Blockers.
2. Run the pre-flight; record gaps in Blockers.
3. `ls lib/linear/` — pick up from the most advanced file. No dir → Phase 1.
4. If `lib/linear/tests/*.sx` exist, run them via the epoch protocol against
   `sx_server.exe`. Green before new work.

## The queue

Phase order per `plans/linear-on-sx.md`:

- **Phase 1** — parser (HM core + linear arrows `-o`, modality annotations)
- **Phase 2** — type system: linear vs unrestricted worlds; **per-variable usage
  counting**; reject use-zero / use-twice of a linear var (the chisel)
- **Phase 3** — linear functions + linear pattern matching (linear pairs, destructure)
- **Phase 4** — modalities: `!A` unrestricted, promotion `[e]`, graded `[n]A`
  (semiring algebra over grades)
- **Phase 5** — linear references / channels / file handles (type-tracked transitions)
- **Phase 6** — effects + linearity (linear values through `perform`/handlers;
  capabilities as linear values)
- **Phase 7** — lightweight borrowing (`borrow x as y in body`, lexical, no regions)
- **Phase 8** — artdag idioms demo (each effect node holds a linear CID → new CID)
- **Phase 9** — propose `lib/guest/linear/` extraction (wait for a 2nd consumer)

Within a phase, pick the checkbox with the best tests-per-effort ratio.
Every iteration: implement → test → commit → tick `[ ]` → Progress log → push → next.

## Chisel discipline — consumption

The payoff is **Phase 2's usage checker**: SX values are fully duplicable today;
linearity makes "at most one use" a first-class, statically-enforced property. The
checker is a *static analysis written in SX over the AST* — runtime values stay
ordinary SX values (linearity is erased after checking, like types in HM guests).
Do NOT try to make the SX runtime physically prevent aliasing; enforce it in the
checker and let well-typed programs run on the normal CEK. Phase 6 (linear values
crossing `perform`) is where it touches the effect system — if a handler can
silently duplicate a resumption-captured linear value, that's a substrate note
(Blockers), not a linear-lang fix.

## Ground rules (hard)

- **Scope:** only `lib/linear/**` and `plans/linear-on-sx.md`. Do **not** edit
  `spec/`, `hosts/`, `shared/`, `lib/guest/**` (read-only), or other `lib/<lang>/`.
- **Consume `lib/guest/`** (lex, pratt, match, hm where useful).
- **Linearity is a checker, not a runtime guard.** Enforce statically; run on the
  normal CEK. Substrate gaps → failing test + Blockers, never a `spec/` patch.
- **NEVER call `sx_build`** (600s watchdog). Broken binary → Blockers, stop.
- **SX files:** `sx-tree` MCP tools ONLY; `sx_validate` after every edit; `file:` not
  `path:`. Never `Edit`/`Read`/`Write` on `.sx`.
- **Worktree:** commit, then push `origin/loops/linear`. Never `main`/`architecture`.
- **Commits:** one feature per commit (`linear: usage counting rejects double-use + 5 tests`).
- **Plan file:** Progress log + tick boxes every commit.
- **Blocked 2 iterations → Blockers, move on.**

## Linear-specific gotchas

- **Two type worlds, one value space.** `A -o B` (linear) and `A -> B`
  (unrestricted) are distinct *types*; the underlying SX closures are identical.
  The distinction lives only in the checker's context discipline.
- **Context splitting is the heart of linear checking.** When checking `f x`, the
  linear context divides between `f` and `x` — a variable can't be available to
  both. Model contexts as multisets and split, don't share.
- **Promotion has a side condition:** `[e]` is `!A` only if `e` used no linear
  variables. Enforce it; it's the usual soundness leak.
- **Grades form a semiring** (`+` for sequencing alternatives, `*` for nesting).
  `[2]A` then used under `[3]` → `[6]A`. Get the algebra right or graded use breaks.
- **Borrow is non-consuming and lexical** — after `borrow x as y in body`, `x` is
  still linear and unused. No lifetimes, just scopes.

## 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`.
- `let` is parallel — nest `let`s when one binding references an earlier one.
- `env-bind!` creates a binding; `env-set!` mutates an existing one.
- Namespace-prefix guest helpers (`lin/…`).
- Shell heredoc `||` gets eaten — escape or use `case`.

## Style

- No comments in `.sx` unless non-obvious. No new planning docs — update the plan.
- Short, factual commit messages. One feature per iteration. Commit. Log. Push. Next.

Go. Run the pre-flight. If lib-guest is missing, stop and report. Otherwise read
the plan, find the first unchecked `[ ]`, implement it.