Relationships
#3289 stagecraft: publish and claim as workflows over a tracker method contract (#3274 step 1)
Opened by skunk-ape · 10/12/2026
Part of swamp-club #3274 (let users build their own tracker as a separate extension). Design settled with Seth on 2026-10-12: Route B. stagecraft and a tracker share no code. A tracker extension implements primitive methods with fixed inputs and one result record each. stagecraft ships the publish and claim logic as workflows whose own steps hold the ledger, cursor and ticket index, and whose tracker steps call the bound tracker instance by name. Tested on a remote worker under swamp serve (see #3274): this works where runModel does not. A JSR package was ruled out.
This step (1 of 3)
Move publish and claim onto stagecraft-shipped workflows over the tracker's primitive methods, and move the built-in, Linear and Lab adapters onto that contract.
- The primitive contract: describe, fetch_issue, create, comment, set_status, relate and unrelate, plus optional post_entry, set_type, assign and link_pr. Each has fixed inputs and writes one result record with a documented schema. Adapters keep no state.
- A new @swamp/stagecraft/publisher model type, one instance per external tracker, naming the adapter instance. It holds the delivery ledger, publish cursor, ticket index and snapshots. The built-in, Linear and Lab instances keep their existing records where they are, read across models, so nothing is migrated.
- Workflow shape: plan reads, forEach fetch, plan writes, forEach apply (concurrency 1, with each write guarded on the previous write's ledger record so a failure stops the rest), then commit. A write that depends on an earlier result waits for the next run; the driver re-runs publish until it reports up to date.
- Conformance: the suite becomes a workflow or method a third party runs against their adapter instance and its local fake. The built-in, Linear and Lab adapters pass it at the method level on the real engine.
- Waits for #3216 to merge, since it touches tracker core and the built-in adapter.
No change to the definition format in this step.
Closed
No activity in this phase yet.
skunk-ape commented 10/12/2026, 2:47:31 PM
Closed unworked: Seth chose to land all of this on #3274, one slice at a time, instead of as separate issues. The slices are now (1) an invisible refactor of publish and claim into plan, apply and commit over the primitive contract; (2) the whole external-tracker feature in one release; (3) the example extension and the guide.
Sign in to post a ripple.