docs(spec): one loop, seven lanes — a design path for single-place turn-loop assembly

[macanderson]

What

A design proposal, not an implementation: docs/spec/turn-lane-assembly.md.

Why

The premise that prompted it — "Stella should only have 1 loop" — turns out to be already true, and that inverts the diagnosis. crates/stella-core/src/driver/drive.rs:111 is the only loop { over Engine::run_step in the workspace; a sweep for run_step( outside driver/ returns one hit and it is a doc comment. Fleet does not have its own loop. It has the loop, assembled differently.

What is duplicated is lane assembly: twelve optional capability slots, bound through three unrelated vocabularies (EngineConfig fields, Engine::with_* builders, TurnControls published to the registry), decided by hand at seven production sites, with nothing checking the matrix.

Consequences already paid for:

• #3232 (fleet has no step-level durability) and #3233 (sub-sessions have none) are two cells of one table, found months apart, each by tripping over it.
• #3242 is a third cell found as damage — a sub-session inheriting the lead's sink and destroying its resume point.
• stella-core/src/subagent.rs:61 documents a structural hole in its own module doc: Engine::with_sleeper cannot carry gate/steering/hooks, so a fork drops three capabilities by signature rather than by decision.
• The pause gate must be bound twice, through two mechanisms, at every site that wants it.

The doc reconstructs the current lane × capability matrix by reading all seven sites. That table did not exist before; building it required tracing bind_session callers × three engine_config_for* variants × seven with_sleeper sites. That difficulty is the finding.

The proposal

Four moves, each independently shippable, all reusing instruments this repo already proved (invariant #8's provider parity matrix, invariant #10's consumer ledger):

1. TurnLane in stella-protocol — name the seven lanes so a matrix can have rows.
2. TurnCapabilities in stella-core — collapse three vocabularies into one struct with no Default, so adding a capability is a compile error at every lane. This is the whole design: make forgetting a lane a build error.
3. A lane matrix in stella-parity, enforced from both sides, with #3232/#3233 as Deferred rows.
4. Lane resolution in stella-runtime, which already owns the assembly bottom half.

§6 raises the one question that needs a human decision — a ResumeAuthority split (Own / Parent / Redispatch) that would unblock #3232 and #3233 by observing that non-primary lanes need a terminal frame, not a per-step resume point. That is much cheaper than the write side an earlier fix declined, and it has a reader by construction.

Witness

None — this is a documentation-only PR. Per CONTRIBUTING's carve-out, docs changes need no witness. Move 2 in the proposal names a real witness that fails on main for a structural reason (a fork carrying gate/steering/hooks), but no code ships here.

Gate

make guards-fast passes (exit 0), including check-doc-links, check-invariants, check-file-size and check-brand-case. docs/manifest.json refreshed via make doc-links-fix.

Refs #3232
Refs #3233
Refs #3242

Summary by Sourcery

Add a new design-spec document describing a unified assembly model for turn-loop capabilities across multiple execution lanes and register it in the docs manifest.

Documentation:

• Introduce the turn-lane-assembly spec documenting the current turn-loop lane/capability matrix and proposing a single-place assembly design.
• Update docs/manifest.json to include the new turn-lane-assembly specification entry.

---

Review round 2 — §9 and §10 added

Answering the three inline comments.

§6 ResumeAuthority is accepted and PR 5 in §8 is now scheduled rather than open.

§9 — plugin-owned lanes. The requirement that plugins contribute their own lane is compatible with this design, but it forces one decision now: TurnLane is open from the first commit (Builtin(BuiltinLane) closed so the compile-error property survives, Plugin(LaneId) open so a manifest can contribute a row). Retrofitting that after seven lanes and a parity matrix are written against a closed enum is a rewrite. §9 also states the thing a plugin lane genuinely breaks — compile-time totality is only available in-tree — and replaces it with load-time validation plus a stella plugins doctor report, rather than pretending the two guarantees are equal. Plus: participation is derived from the capability vector rather than separately authored; granted = requested ∩ authorized, with #2716 as the missing half; and two constraints that bite Move 2 now (TurnCapabilities must admit owned slots, and a blocking plugin cannot live on the sync HookBus).

§10 — now, later, or never. Seam now, extraction later, merge never. With one correction to the premise: the pipeline has already left stella-core — that crate declares no stella-pipeline dependency and holds no witness/ladder/flip-oracle code. The coupling is stella-cli (169 references across 41 files), stella-serve (4 files), and stella-runtime (declared, referenced nowhere — filed as #3280).

stella-serve is the existence proof that makes the plugin half feasible: its engine holds no ambient authority and remotes every model and tool call to a host, so a plugin-driven lane is that seam pointed the other way.

Note for reviewers: two sessions wrote a plugin-lanes section against this branch concurrently, and 67a260016 captured both — two §9s and two §10s. 55495aa68 deletes the duplicate pair, re-attaches §8's closing sentence, and grafts forward the two mechanics #2456 had already settled (builtin-first resolution; nested [lanes.custom.<id>], never #[serde(flatten)]). No test was deleted; this is a docs-only PR.

Refs #3246
Refs #2716
Refs #2456
Refs #3280

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
stella-cli-docs	Ready	Preview	Aug 14, 2026 8:00pm

[sourcery-ai]

Reviewer's Guide

Documentation-only PR that adds a detailed design/specification for centralizing turn-loop capability assembly into a single, typed matrix across seven "lanes", plus wires it into the docs manifest.

File-Level Changes

Change	Details	Files
Add a new spec describing the current turn-loop lane × capability matrix and a proposed refactor to centralize lane capability assembly.	Document that there is a single turn loop and identify seven distinct execution lanes with their assembly sites. Reconstruct and tabulate the existing lane-by-capability matrix across three vocabularies (EngineConfig, Engine::with_*, TurnControls) and highlight existing bugs/regressions (fleet: worker turns are never checkpointed — the whole fan-out has no step-level durability #3232, deck sub-sessions have no step-level durability — a killed lane loses its whole transcript #3233, fix(stella-cli): a deck sub-session no longer destroys the lead turn's resume point #3242). Propose introducing TurnLane, a unified TurnCapabilities struct with no Default, a parity-enforced lane matrix, and lane resolution in stella-runtime. Outline an open design question around ResumeAuthority (Own / Parent / Redispatch) and how terminal-frame durability could close fleet: worker turns are never checkpointed — the whole fan-out has no step-level durability #3232 and deck sub-sessions have no step-level durability — a killed lane loses its whole transcript #3233. Clarify out-of-scope items and sequencing for the eventual implementation PRs.	docs/spec/turn-lane-assembly.md
Register the new spec document in the documentation manifest.	Add a turn-lane-assembly entry pointing to the new spec file, listing sections 1–8, and marking its status as proposed. Set the spec title in the manifest to match the document heading.	docs/manifest.json

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery