#2793 gatorwalk-factory: separate engine and tracker code behind a seam module the tests enforce
Opened by skunk-ape · 9/30/2026· Shipped 9/30/2026
Part of the tracker-seam decision (https://claude.ai/artifact/TDidgyVjxKXU7JsNH1baNy): tracker functionality stays in gatorwalk-factory, but behind a seam the tests enforce, not a separate extension. Read gatorwalk-factory/DESIGN.md "Trackers" (:1092) first.
Today
No engine file imports tracker code (lifecycle.ts, work_item.ts, run_ops, run_store, gates, journal, work_item_ops, cel_context, metrics, summary and the report import none of tracker, tracker_methods, projection, claim, linear, swamp_club). Tracker code reaches into engine internals from many places:
_lib/tracker_methods.ts:18-49: digestOf, parseRun, RUN_SPEC, payloadName, checkPinned, LIFECYCLE_SPEC, MethodOutput_lib/claim.ts:29-37: freshKey, loadHolderLifecycle, WORK_ITEM_TYPE_lib/projection.ts:17-24: journal types, ProjectionEntry, triggerKey, the template rendererswamp_club.ts:40-44,linear.ts:20: stringMapFrom, typeNameOf, MethodOutput
Nothing stops the next change from crossing the line in either direction.
Change
- Move files into
_lib/engine/and_lib/tracker/core/plus_lib/tracker/backends/(Lab and Linear clients and their fakes). - Add
_lib/seam.ts, re-exporting exactly what tracker code uses from the engine today. It is the only engine module tracker code may import. - Add
seam_test.ts: engine code imports nothing undertracker/, and tracker code imports from the engine only throughseam.ts. The one current exception,fake_swamp.ts:18importing claim types, moves to test support or goes through the seam. - No behaviour change. Model types, method names and data names stay the same.
- DESIGN.md: a short "The seam" decision under "Trackers", saying what the rule is and why it is a test rather than a package boundary (no consumer besides gatorwalk; the tracker reads the run record, journal and pinned lifecycle, which a package split would turn into a cross-package API).
Order
After #2767 (template removal), which edits work_item_ops, lifecycle_schema and graph. Before #2771, #2772 and #2711, which edit tracker files. Every later issue in this series builds on it.
Done when
- The seam test passes, and fails on an added import that crosses the line in either direction (shown in the test).
- All existing unit and integration tests pass unchanged, apart from import paths.
Shipped
Click a lifecycle step above to view its details.