Skip to content

✨ Workflow models: simulate an issue/PR against a model - #17686

Closed
clubanderson wants to merge 4 commits into
workflowmodel/v5-p3b-workflows-tabfrom
workflowmodel/v5-p3c-simulate
Closed

clubanderson wants to merge 4 commits into
workflowmodel/v5-p3b-workflows-tabfrom
workflowmodel/v5-p3c-simulate

Conversation

@clubanderson

Copy link
Copy Markdown
Member

RFC phase 3c — Simulate of the workflow-models RFC (#17620), on v5, stacked on the Settings → Workflows tab PR #17681 (base workflowmodel/v5-p3b-workflows-tab).

"Simulate: paste or pick a real issue/PR and see which state the model puts it in and why, using the same Facts the engine would use. This is the operator's confidence check before binding."

What

API — POST /api/workflows/{name}/{version}/simulate (read-only, any logged-in role)

Request:

{ "kind": "issue"|"pr", "facts": { ...SimulateFacts... }, "repo": "owner/repo", "number": 123 }
  • facts is a lowerCamel JSON mirror of stageengine.Facts (labels, open, merged, draft, origin, author{login,kind,selfAuthored,role}, park{holds,needsHuman,…}, issue{bucket,…}, pr{checks,review,dco,conflicting,changesRequested,humanApprover,lane,…}). Enumerations use the engine's name helpers (author.kind hive|clanker|human|unknown, pr.checks green|red|pending|unknown, pr.review approved|changes_requested|pending|unavailable|requires_human, pr.dco yes|no|unknown); new exported stageengine.ParseAuthorKind/ParseChecks/ParseReview/ParseDCO are their inverses, so a response's facts can be pasted back as a request.
  • repo+number without facts → best-effort fill through the hive's GitHub client (new github.Client.WorkflowItemSnapshot: issue, PR, mergeable state, head check summary). kind may be omitted (taken from the item; mismatch → 400). No client wired → 422, never invented.

Response:

{ "decision": { "state", "column", "stage", "label", "reason", "abstain", "covered", "terminal" },
  "trace": [ { "id", "state", "kind", "evaluated", "matched", "skipped", "builtin", "reason",
               "predicates": [ { "fact", "op", "value", "holds", "known", "actual" } ] } ],
  "facts": { …normalized echo… }, "filled": [...], "unknown": [...], "notes": [...] }
  • New stageengine.Explain(profile, kind, facts) (Decision, []RuleTrace) shares holds() with the rules evaluator; Derive is untouched. Rules mode: every rule in order, other-kind rules skipped, evaluated until the first match (predicate verdicts + actual value), the rest evaluated:false; uncovered → abstain:true, covered:false, reason "workflow: not covered…". Builtin mode: single {builtin:true, state, reason} entry.
  • Built-in PR derivation needs lane facts; when none are given stageengine.SimulatedLane synthesizes one from the other facts and says so in notes (pass pr.lane to override).

UI — Simulate panel on the model detail page

Collapsed Simulate <details> in Settings → Workflows → detail: owner/repo#123 picker + Fetch facts, issue/PR radio, facts form generated from the declarative WF_SIM_FIELDS table, Run. Result: decision chip (state · column · stage/NNN · reason, or Not covered), the trace as an ordered list with the matched rule highlighted and each predicate as fact op value → ✓/✗/?, fetched/unknown lists, and the resulting state's chip highlighted in the diagram (.wf-dg-state.simulated). Tokens-only CSS, no raw px/colours, no downloads, no toLocaleString.

Guards

  • dashboard/openapi.json path + WorkflowSimulateRequest/Facts/Result schemas (route-parity test).
  • Go: TestWorkflowSimulateHiveDefaultPR, TestWorkflowSimulateRulesTrace, TestWorkflowSimulateErrors, TestWorkflowSimulateFetchesItem (dashboard); TestExplainRulesTrace, TestExplainBuiltinTrace (stageengine).
  • Node: TestWorkflowsSimulateWiring, TestWorkflowsSimulateNode (form kind-awareness + round-trip, matched-rule highlight, predicate verdicts, Not covered, diagram marking).
  • pkg/dashboard, pkg/dashboard/webstatic, pkg/stageengine, pkg/workflowmodel/... green locally (apart from the known macOS-only TestConfigExportReportsPersistedPath / TestKnowledgeDrainLegacyMemory); style/download/timezone/import ratchets unchanged; webstatic/gen -check clean.

Docs

  • docs/design/workflow-models.md → new "Simulate (RFC phase 3c)" section (API shape, trace semantics, best-effort fill caveats).
  • changelog.d/added-workflowmodel-simulate.md.

Refs #17620

Add POST /api/workflows/{name}/{version}/simulate. It loads a stored
model, compiles it, converts a JSON Facts mirror into stageengine.Facts
and runs the same deriver the engine uses, returning the decision
(state, column, stage, reason) and a per-rule trace from the new
stageengine.Explain. repo+number without facts best-effort fills from
the forge and reports which facts were filled vs unknown.

Refs #17620

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Settings → Workflows → model detail grows a Simulate section: pick a
real owner/repo#N to fetch its facts, or describe one with a form
generated from WF_SIM_FIELDS, then Run to see the decision chip
(state · column · stage · reason), the ordered rule trace with the
matched rule highlighted and each predicate's verdict, and the
resulting state marked in the diagram.

Refs #17620

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Refs #17620

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Refs #17620

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 11, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Nov 11, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: workflowmodel/v5-p3b-workflows-tab

Conflicts are checked with every PR merged onto the current tip of workflowmodel/v5-p3b-workflows-tab, so a PR that only needs a rebase is not reported as conflicting with its siblings.

No conflicting open PRs or same-file overlaps were found.

@kubestellar-prow
kubestellar-prow Bot deleted the branch workflowmodel/v5-p3b-workflows-tab November 11, 2026 15:23
@kubestellar-prow kubestellar-prow Bot closed this Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant