Shrink the Promise run loop to a small core with four internal extension points

[usirin]

Stories: 7
TDD: yes

What to build

Replace the body of the Promise engine's loop with a small core, as in spike #264. The core does serial transitions, save before effects, reconcile subs, run Cmds and dispatch outcomes, and has no special case for any built-in. Rebuild the built-ins on four internal extension points:

• update middleware (returns null for "no transition"): identity filter, supervision, dev checks
• interpret middleware: the ok-schema check, clock stamping
• store wrapper: fenced store
• commit observer: events, terminal / done

Fix the extension order in code (the identity filter sits inside supervision). Model the stop() drain / discard gate and ctx contributions, which #264 left out. These stay internal, not a user plugin API (#268). withTelemetry moves here as an internal extension.

Acceptance criteria

• The core loop file contains no reference to identity, events, terminal, supervision, fencing, schema checks or clock stamping
• Each built-in keeps today's behaviour: spike: can tea's run loop shrink to a small core (serial transitions, save before effects, reconcile subs, run Cmds) with today's built-ins (identity filter, events, terminal/done, supervision, fence… #264's 11 cases pass against the new loop
• stop() still drains and discards as today (DispatchDiscardedError), and handlers composed inside other handlers still settle through the same edge
• pnpm typecheck && pnpm lint && pnpm test pass

[usirin]

build-deviations: #280

Deviations

• Out-of-scope change — Said: the issue says withTelemetry moves into the loop as an internal extension, and no criterion covers it. Did: removed withTelemetry and its types from ./resilience (battery tier) and added a telemetry sink option to run, built as a commit extension. The event is now a fixed { seq, msgType, at }; seq counts per run and is not saved; there is no { base, $telemetry } Model wrap; a failing sink reaches onError under "observer" where the wrapper swallowed it; the sink fires after commit, not as a Cmd during interpret. Why: the issue body and ruling does demlik keep a battery or plugin layer for reusable logic, or does reusable logic live only in plain functions and Cmd defs that users call from their own update, as in Elm? #268 R1.1 place the move in this slice, and a loop extension cannot keep a Model slice or a custom projector over the wrapped Model. Disposition: stated here and in .changeset/small-core-loop.md, which names the successor for each removed name.
• Pre-existing test or fixture changed — Said: keep today's behaviour. Did: deleted with-telemetry.test.ts; moved the tests that used withTelemetry as a sample wrapper (machine-shape, msg-keys-union) onto withDeadline, so machine-shape now also expects $deadline:exceeded; dropped the telemetry cases in apply-cell-tracer and typed-cmd-channels-wrapped (the withDeadline / withResilience cases stay); updated the $telemetry:emit names in the constructor-built scan test. Why: the wrapper those tests exercised is gone. Disposition: stated here; telemetry is now covered in src/promise/small-core.test.ts.
• Scope narrowing — Said: spike: can tea's run loop shrink to a small core (serial transitions, save before effects, reconcile subs, run Cmds) with today's built-ins (identity filter, events, terminal/done, supervision, fence… #264's 11 cases pass against the new loop. Did: re-wrote the 11 cases from the spike's written decision as src/promise/small-core.test.ts against the real run, plus sub reconcile, the stop() drain/discard gate and a composed handler settling through cmdEdgeOf(ctx). Why: the spike's harness (spike.ts, run 53fc187c) is not in the repo. Disposition: stated here.
• Guard or gate bypassed — Said: build check green before commit. Did: committed with build check --surface code and --surface prose red only on the codeowners-cp guard, which lists control-plane paths (.claude-plugin/, packages/fabrika-cli/src/ci/, biome-plugins/, and others) missing from .github/CODEOWNERS. Why: this diff touches neither .github/CODEOWNERS nor any listed path, so the red stands on the base too; pnpm typecheck, typecheck:test, typecheck:consumers, lint, test, build and verify-exports are green here. Disposition: left for the epic driver; not fixable from this lane.

[usirin]

Built on local branch build/280-small-core-5e669ed1 (commit 2b8dc9a, off epic/273), unpushed for the epic fold.

Look first at:

• src/promise/loop.ts: the core. Five extension points (update, interpret, store, commit, ctx) plus handle methods. The stop() gate stays here.
• src/promise/run.ts: builds the extensions in a fixed order. Supervision sits outside the identity filter, which sits outside the dev checks.
• src/promise/builtins.ts: the built-ins as extensions.
• src/promise/small-core.test.ts: the spike: can tea's run loop shrink to a small core (serial transitions, save before effects, reconcile subs, run Cmds) with today's built-ins (identity filter, events, terminal/done, supervision, fence… #264 cases, a scan of loop.ts for built-in names, the stop() drain/discard gate, a composed handler settling through cmdEdgeOf(ctx), and telemetry.

withTelemetry is gone from ./resilience; run's telemetry option replaces it (see the changeset and the build-deviations comment).

[usirin]

governance: PASS range:6fb8304af92aa0d267728baf9daee85b76fc8f08..2b8dc9a content:c74e19b09698 — no contradiction, no weakening

Range 6fb8304..2b8dc9a (epic #273 child #280), round 1. governance scope over the range: required, one governed root touched (.patterns/, 1 file), self false, so the self fence does not apply.

No decision record in this diff. Nothing to sweep; the corpus half is a hand read. sweep and guards have no range form, so both halves were read by hand over the range's diff.

Questions this change decides, and the live law read against each (adr resolve: 0016, 0017, 0018, 0020, 0021, 0022 all live/accepted):

1. May withTelemetry leave ./resilience (battery tier) in this change, with no deprecated re-export? ADR 0016 plus MAINTAINING.md "Removal, while 0.x": yes, if the removal, the import rewrites and a minor changeset naming where each name went land together. .changeset/small-core-loop.md is minor, flags the break, and maps every removed name (withTelemetry, TelemetryEvent, TelemetryPorts, TelemetryConfig, TelemetryModel, TelemetrySlice, telemetryEmit, TelemetryEmitCmd) to its successor or to "nothing". No contradiction.
2. Does a public telemetry option on run contradict ADR 0022 item 4 ("withTelemetry moves inside tea as one of tea's internal extensions ... no longer a user-facing wrapper")? No. The extension (telemetry in src/promise/builtins.ts) is internal, and the user reaches it through a run option, not a machine wrapper. It is none of 0022's banned shapes (mount, with* wrapper, defineBattery, plug, wrap, composeMachines).
3. Do the extension points count as a plugin layer, which ADR 0022 bans? No. Extension / ExtensionFactory live in src/promise/loop.ts. run builds a fixed list and takes no user extensions, and nothing new is exported for them (docs/reference/tea.md gains only TelemetryEvent and TelemetrySink).
4. Do a transition's Cmds still run one at a time (ADR 0018)? Yes. runCmds in loop.ts awaits each interpret(cmd) in order.
5. Does the handler still return an outcome that the engine mints (ADR 0021)? Yes. cmdDefinitions wraps interpret with cmdEdgeOver, and the same edge rides on ctx under cmdEdge.
6. Does ctx stay plain with no DI (ADR 0020)? Yes. Extensions add the same keys the old augmentedCtx held (emit, ok, err, cmdEdge, detachWork). No service graph.
7. Is fencing still a property of the store and not a flag (ADR 0017)? Yes. fencing() wraps the store only when isFencedStore(store) holds. The boot save, every transition save and the stop() final save all go through the wrapped store.

Gate half. The one governed path touched is .patterns/tea/elm-canon.md. It changes a single pointer, src/promise/run.ts:reconcileSubs → src/promise/loop.ts:reconcileSubs, and that pointer is correct at the tip. No anchored invariant and no guard-bearing file is in this diff's reach. The deleted with-telemetry.test.ts and the rewritten telemetry test cases cover a removed export, not a gate, and small-core.test.ts now covers telemetry. No invariant is in this diff's reach.

[usirin]

review-code: PASS range:6fb8304af92aa0d267728baf9daee85b76fc8f08..2b8dc9a content:c74e19b09698 — criteria met over the range

Range 6fb8304..2b8dc9a (epic #273 child #280, one commit, 2b8dc9a), round 1. review seat put the worktree at 2b8dc9a, detached, and every run below used that tree. review criteria 280: 4 body criteria, no rulings. lane prove derives review-code, review-doc and governance for this range.

Execution evidence. A child has no PR and no CI run, so I ran the gate's commands on the seated tree: pnpm typecheck exit 0, pnpm typecheck:test exit 0, pnpm lint exit 0 (2 warnings, both in the untouched src/pure/__fixtures__/impure-reducer.fixture.ts), pnpm test exit 0 (142 files, 2169 passed, 3 skipped, 11 todo). The tail PR's CI still has to confirm this.

Criteria

• [PASS] The core loop file names no built-in. src/promise/loop.ts has no match for identity, event(s), terminal, supervis, fenc, schema, clock or stamp. The only hit on done is the prose "teardown is done" at line 306. small-core.test.ts:32-46 checks this against the file text. Each built-in is in src/promise/builtins.ts: supervision, identityFilter, devChecks, cmdDefinitions (ok-schema and clock), fencing, observation, semanticEvents, terminality, telemetry and ports.
• [PASS] Each built-in keeps today's behaviour, and spike: can tea's run loop shrink to a small core (serial transitions, save before effects, reconcile subs, run Cmds) with today's built-ins (identity filter, events, terminal/done, supervision, fence… #264's 11 cases pass against the new loop. small-core.test.ts:147-351 runs every case from spike: can tea's run loop shrink to a small core (serial transitions, save before effects, reconcile subs, run Cmds) with today's built-ins (identity filter, events, terminal/done, supervision, fence… #264's written decision against the real run: identity drop, a throwing ofMsg supervised, events, terminal and done (including a boot that lands terminal), supervision stop, escalate and restart, the fenced second writer, the malformed ok, clock stamping and dev checks. The spike harness is not in the repo, so the builder rewrote the cases; that is disclosed. I also compared the old run.ts (at base) with the new code path by path, with these results:
  • The commit order is unchanged: listeners, then observers or boot, then events, then done.
  • Boot saves only when a store exists.
  • Restart commits the rehydrated State under the throwing Msg with no dev check, as before.
  • Stop mode closes the gate.
  • A handler that throws synchronously for a defined Cmd is still reported under interpret.
  • A defined Cmd with no handler still yields no Msg: cmdEdgeOver maps undefined to undefined.
  • The fenced version is read at load and compare-and-swapped on every save, including the save in stop().
  • Handler ctx carries the same keys: emit, ok, err, cmdEdge, detachWork.
  • The extension order is fixed in run.ts:134-145, with the identity filter inside supervision, as spike: can tea's run loop shrink to a small core (serial transitions, save before effects, reconcile subs, run Cmds) with today's built-ins (identity filter, events, terminal/done, supervision, fence… #264 run 3 requires.
    The full existing suite passes unchanged apart from the telemetry tests disclosed below.
• [PASS] stop() still drains and discards, and composed handlers settle through the same edge. The open → draining → closed gate stays in the core (loop.ts:233, 545-561, 615-644). small-core.test.ts:397-445 checks that RuntimeDiscardedError and then DispatchDiscardedError are reported under discard, the follow-up is not applied, and a later dispatch gets "runtime stopped". small-core.test.ts:447-503 shows a handler that runs another handler inside its own settling through cmdEdgeOf(ctx), parsed and stamped once ({ n: 5, ats: [9] }). The ctx contribution is the fifth extension point that spike: can tea's run loop shrink to a small core (serial transitions, save before effects, reconcile subs, run Cmds) with today's built-ins (identity filter, events, terminal/done, supervision, fence… #264 did not model.
• [PASS] pnpm typecheck && pnpm lint && pnpm test pass. See the execution evidence above.

Sweep (silent failures, type design, test gaps)

• Silent failures: a telemetry sink that throws synchronously or rejects goes to onError under "observer", and small-core.test.ts:530-546 checks it. A commit callback's own throw is not isolated by the core. Every built-in isolates through loop.fanout or report, and user code can reach no commit callback, so nothing is lost.
• Type design: the Extension / ExtensionFactory types are not exported from any door, so they stay internal, as does demlik keep a battery or plugin layer for reusable logic, or does reusable logic live only in plain functions and Cmd defs that users call from their own update, as in Elm? #268 requires.
• Test honesty: the deleted and rewritten tests all cover the removed withTelemetry, and the deviations comment names each one. machine-shape now expects $deadline:exceeded because it uses withDeadline as the sample wrapper, which is a real change of subject and not a weakened assertion.
• Non-blocking leftovers I chose not to route as criteria:
  • tsconfig.test.json:91 still lists the deleted with-telemetry.test.ts. tsc ignores it, as the green typecheck:test shows.
  • Comments in with-deadline/index.ts:22,325, with-deadline.test.ts:494 and with-resilience/index.ts:12,642 still compare against withTelemetry. Those wrappers are removed later in this epic.
    The epic's tail review should check that both are gone.

Deviations

build-deviations marker on #280 (#280 (comment)): 4 entries, each checked against the diff.

Entry	Matches diff	Note
Out-of-scope change: withTelemetry → run's telemetry option	yes	Required by the issue body and #268 R1.1. The changeset names a successor for each removed name.
Pre-existing tests changed	yes	Matches the diff of apply-cell-tracer, machine-shape, msg-keys-union, typed-cmd-channels-wrapped and constructor-built-cmds, and the deleted test file.
Scope narrowing: the 11 cases rewritten	yes	The cases are in small-core.test.ts.
Gate bypassed: codeowners-cp red	yes	The diff touches neither .github/CODEOWNERS nor a listed path.

deviation-disclosure: PASS. Nothing undisclosed that this gate could see.

[usirin]

review-doc: PASS range:6fb8304af92aa0d267728baf9daee85b76fc8f08..2b8dc9a content:c74e19b09698 — doc slice well-formed

Range 6fb8304..2b8dc9a (epic #273 child #280), round 1, with the worktree seated at the tip. The doc-class slice is .changeset/small-core-loop.md, .patterns/tea/elm-canon.md, docs/reference/resilience.md and docs/reference/tea.md. The issue's criteria are graded in review-code. This verdict covers the doc rubric.

• Right surface. Each change sits in its own home. The release note is in .changeset/. The code-shape pointer is in .patterns/. The generated reference is in docs/reference/.
• Generated reference is not hand-edited. I ran pnpm docs:reference on the seated tree and the worktree showed no changes afterwards, so both reference pages match what the generator writes. resilience.md drops the 8 telemetry exports (134 → 126). tea.md adds TelemetryEvent and TelemetrySink (146 → 148).
• One Diátaxis mode per doc. The changeset is reference: what changed, then a before/after snippet and a removed-name → successor list. The patterns edit is a one-line pointer inside an existing explanation. Neither page mixes modes.
• Supersession is explicit. The changeset names what replaces each removed name (withTelemetry → the telemetry option, and so on), which is the same map MAINTAINING.md's removal rule asks for.
• Claims trace. I checked each changeset claim against the code:
  • The event shape is { seq, msgType, at } (builtins.ts:364).
  • seq counts per run and is not saved: it is a closure counter.
  • A failing sink goes to "observer" (builtins.ts:365-371).
  • The Model is no longer wrapped.
  • "run behaves as before" holds apart from telemetry, per the review-code comparison.
    The .patterns pointer to src/promise/loop.ts:reconcileSubs resolves at the tip (loop.ts:362).
• Portability guard. Not applicable: nothing under claude-plugins/fabrika/ or packages/fabrika-cli/src/ is touched.
• Prose craft. Plain words and short sentences. Nothing needs a re-read.

No findings.