feat(gatorwalk-factory): a factory chooses its tracker, and status shows the lag (swamp-club #2795) #399

Merged

seth merged 2 commits from cue/2795-gatorwalk-factory-lifecycle into main

2026-10-01 00:10:24 +00:00

seth commented

2026-10-01 00:07:00 +00:00

Owner

Closes swamp-club #2795, and takes over part 2 of #2771 (making publish lag visible).

What changes

A factory definition names the kind of tracker it is written for: tracker: { kind: builtin | swamp-club | linear }, defaulting to the built-in tracker.
The factory names the tracker instance in a new required tracker argument. Tracker settings (prefix, statuses, types, Linear's teamId) stay on the instance.
validate and start check the binding. They refuse a factory with no tracker, a tracker instance that doesn't exist, or one of the wrong type for the kind (for example, a Lab definition bound to a Linear instance).
start pins { instance, kind } in the run record. It also refuses externalRefs whose tickets are all on another kind of tracker.
status shows how far behind the ticket is: tracker '<instance>' behind by N event(s): run publish on it. It reads the bound instance's publish cursor as data, with no network call.
publish runs only on the pinned tracker instance.
Rename: the stage-level projection block is now tracker, and the code and docs follow. projection.ts is now ticket_view.ts, and "the projection publisher" is now "the publisher".
The seam: the engine now knows the bound instance and its kind, through _lib/engine/tracker_binding.ts, and still imports no tracker code. DESIGN.md's seam section and a new "The factory's tracker" section say so.

Checking stage status keys and entries against the bound tracker is a follow-up: a tracker-side method, #2847.

Docs and skill

driving.md: setup creates and binds a tracker, and the per-step loop runs status, then publish when the ticket is behind.
The build-swamp-extension walkthrough and authoring.md bind a tracker.
README and DESIGN are updated, including a decision-log entry.

Verification

verify-build and verify-reviews both passed on d9a55172 (609 unit tests, 38 integration tests). Both reviews gave a pass verdict. The attestation is posted (617df9ac).

🤖 Generated with Claude Code

Closes swamp-club #2795, and takes over part 2 of #2771 (making publish lag visible). ## What changes - **A factory definition names the kind of tracker it is written for:** `tracker: { kind: builtin | swamp-club | linear }`, defaulting to the built-in tracker. - **The factory names the tracker instance** in a new required `tracker` argument. Tracker settings (`prefix`, `statuses`, `types`, Linear's `teamId`) stay on the instance. - **`validate` and `start` check the binding.** They refuse a factory with no tracker, a tracker instance that doesn't exist, or one of the wrong type for the kind (for example, a Lab definition bound to a Linear instance). - **`start` pins `{ instance, kind }` in the run record.** It also refuses `externalRefs` whose tickets are all on another kind of tracker. - **`status` shows how far behind the ticket is:** `tracker '<instance>' behind by N event(s): run publish on it`. It reads the bound instance's publish cursor as data, with no network call. - **`publish` runs only on the pinned tracker instance.** - **Rename:** the stage-level `projection` block is now `tracker`, and the code and docs follow. `projection.ts` is now `ticket_view.ts`, and "the projection publisher" is now "the publisher". - **The seam:** the engine now knows the bound instance and its kind, through `_lib/engine/tracker_binding.ts`, and still imports no tracker code. DESIGN.md's seam section and a new "The factory's tracker" section say so. Checking stage status keys and entries against the bound tracker is a follow-up: a tracker-side method, #2847. ## Docs and skill - driving.md: setup creates and binds a tracker, and the per-step loop runs `status`, then `publish` when the ticket is behind. - The build-swamp-extension walkthrough and authoring.md bind a tracker. - README and DESIGN are updated, including a decision-log entry. ## Verification verify-build and verify-reviews both passed on d9a55172 (609 unit tests, 38 integration tests). Both reviews gave a pass verdict. The attestation is posted (617df9ac). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

seth added 2 commits

2026-10-01 00:07:00 +00:00

feat(gatorwalk-factory): a factory chooses its tracker, and status shows the lag (swamp-club #2795 ) 9eb412b30c

A factory definition names the kind of tracker it is written for
(tracker: { kind }, the built-in tracker by default), and the factory
names the tracker instance in a required tracker argument. validate and
start refuse a missing instance or one of another type than the kind
needs; start pins { instance, kind } in the run record; status reads
the bound instance's publish cursor as data and says how many journal
events the ticket is behind. publish runs only on the pinned instance.
Tracker settings (prefix, statuses, types, teamId) stay on the instance.

The stage-level projection block is renamed tracker, and the code and
docs follow: projection.ts is ticket_view.ts, and "the projection
publisher" is "the publisher".

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

fix(gatorwalk-factory): start refuses a ticket on another tracker than the factory's (swamp-club #2795 )

CI / Validate Attestation (pull_request) Successful in 1m29s

Details

CI / Review Integrity (pull_request) Successful in 1m58s

Details

d9a55172bb

A ticket claimed on one tracker and started under a factory bound to
another could be published by neither, while status reported it as never
behind. start now refuses externalRefs whose tickets are all on another
tracker kind. Also moves withRepo's doc comment back above it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

seth merged commit 9c8931f38b into main

2026-10-01 00:10:24 +00:00

seth referenced this pull request from a commit

2026-10-01 00:10:28 +00:00

feat(gatorwalk-factory): a factory chooses its tracker, and status shows the lag (swamp-club #2795) (#399)

seth deleted branch cue/2795-gatorwalk-factory-lifecycle

2026-10-01 00:10:28 +00:00