Repository navigation
Re-audit the op → workflow rename plan: every number in it is three months stale #716
Description
Epic: #451 · Plan: docs/plans/workflow-rename.md · Blocks: #715
The plan is status: draft with its Current State audited 2026-05-26. Its stated prerequisite —
"cannot start until refactor/extract-starlark-from-op.phase-8 merges" — has been satisfied for some time,
and the plan has not been revisited since. Every quantity in it is now wrong.
Measured against the tree, 2026-08-27
| Element | Plan | Today | |
|---|---|---|---|
pkg/op/ root .go files |
62 | 108 | +74% |
provider/ files |
76 | 238 | +213% |
starlarkbridge/ files |
5 | 8 | +60% |
Generated .gen.go |
29 | 48 | +66% |
Qualified op.X references |
~2,499 | 3,880 | +55% |
Files importing pkg/op |
~200 | 130 | methodology may differ; re-measure |
The subpackage list is wrong in both directions. The plan names provider/, starlarkbridge/,
inventory/, sops/. Today: claimcheck/, inventory/, provider/, server/, starlarkbridge/ —
sops/ has left, and claimcheck/ and server/ arrived after the audit.
Every line reference in the Current State table has shifted (ExecutableUnit 29→39, Graph 40→50,
Subgraph 28→32, RecoveryStack 16→37, GraphExecutor 32→44).
What still holds
All five renames remain well-formed — every source type exists and the mapping is unambiguous.
The collision claim survives. Step is declared only in internal/console (a TUI session step, different
package), and Block, Ledger, Definition, Executor, and Workflow are declared nowhere. Phase 1
before Phase 2 is still the only ordering constraint.
New evidence FOR the target
The tree has independently converged on the plan's vocabulary. plan.Provider now exposes
AssembleDefinition, LoadDefinition, and SaveDefinition — all returning *op.Graph — and the starlark
surface reads plan.assemble_definition(...), plan.save_definition(...). The API already calls a graph a
definition while the Go type is still Graph. The rename closes a gap that has widened on its own since the
audit, rather than imposing a new word.
What bringing it up to date requires
- Re-run the audit. Mechanical: the table above, plus fresh line references. The numbers matter because
they are the effort estimate, andop.Xreferences have grown 55%. - Decide the new subpackages.
claimcheck/andserver/did not exist when the phases were written.
claimcheckis a build-gate analyzer that reads the whole module — does it move with the package, and does
it need updating for the new package path?server/likewise. - Audit what the last three months added for rename impact. Method claims (
MethodClaims,
ClaimDeterministic,Method.Mutates), sealed provider resources,readAgainstField/losesMeaning/
explainRefusal, theRunStatustypes. None obviously collide, but none were weighed. - Fold in Rename the provider roles: surface=graph produces RoleAction, and the rename retires both words #715, the role rename. It belongs in the same window: doing it separately means renaming twice.
- Re-verify phase sequencing. Still collision-safe on paper; confirm against 108 root files rather than 62.
- Re-baseline the estimate and set
status. The plan cannot leavedraftwhile its own facts are stale.
Worth deciding at the same time
The plan predates several architecture documents that now describe pkg/op in detail — 3.6, 3.2, the
provider catalog, 4.5. A pure rename churns their prose. Whether that is in scope, or a follow-up, should be
stated rather than discovered mid-phase.
Acceptance
- Current State reflects the tree, with the date of its audit
-
claimcheck/andserver/have a stated disposition - Rename the provider roles: surface=graph produces RoleAction, and the rename retires both words #715 is folded into the phase plan
- Collision safety re-verified against today's files
- Documentation churn is in scope or explicitly deferred
-
statusleavesdraft
Activity
David-Noble-at-work commentedon Aug 27, 2026
Folding in a second deliverable: the plan needs an appendix mapping every current name to its new one. It does not have one, and the re-audit walks the same identifiers anyway, so producing the table is most of that work rather than an addition to it.
What exists today
The "Rename Mapping" section is five rows — one per phase, top-level types only. Nothing maps the derived identifiers.
What the table would carry
GraphSubgraphRecoveryStackExecutableUnitPlus 14 files whose names carry a renamed word:
graph.go,graph_executor.go,subgraph.go,nodeid.go,executable_unit.go,recovery_stack.go, and their tests.Why it is not bookkeeping
The plan's goal 4 promises "each phase is a pure rename so reviewers can verify by inspection." Without the table a reviewer has no reference to inspect the diff against.
And three classes need judgment rather than derivation:
Nodeis ambiguous by construction. It maps toStepand is the target ofExecutableUnit. Every identifier containing "Node" needs a decision about which sense it carries. The proof isGenerateNodeID, whose doc says "unique node IDs across all plan bindings" — andpkg/op/provider/flow/helpers.gocalls it as:It mints ids for subgraphs too, so it names the abstract vertex. Under the new taxonomy that is
Node, and the correct answer is that it keeps its name. A mechanicalNode → Stepsweep would rename itGenerateStepIDand quietly make it wrong — an identifier claiming to mint leaf ids while minting them forBlocks as well. Phase 1/Phase 2 ordering protects the types from this collision; nothing protects derived identifiers.File names. 14 of them, and not all are mechanical:
graph.go→definition.goandgraph_executor.go→executor.goare clear;nodeid.gofollows whateverGenerateNodeIDdecides.Prose inside identifiers.
SerializeGraphs,descendantNodes,SubgraphChild,NewGraphSpec— each reads differently after the swap, and some carry the ambiguity above.Added acceptance
Nodestates which sense it carries — leaf (Step) or abstract vertex (Node)David-Noble-at-work commentedon Aug 27, 2026
Recorded in the plan itself. It previously had no reference to either issue, still claimed its prerequisite was unmet, and presented three-month-old numbers as current — so a reader arriving there got stale facts with no sign that a re-audit was chartered.
docs/plans/workflow-rename.mdnow carries:AssembleDefinition/LoadDefinition/SaveDefinitionalready call a graph a definition)GenerateNodeIDcase worked through, and the requirement that unchanged identifiers be listed explicitlyThe plan stays
status: draft. Leaving draft is this issue's last acceptance item, and it should not happen until the numbers are re-measured rather than merely annotated.Root applies to every surface, and the rename plan says what is stale…
chore(op): the last artifacts carrying retired placement vocabulary (#…