Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-workflowmodel-compiler.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Workflow models, RFC phase 1 ([#17620](https://github.com/hivecommons/hive/issues/17620)): the `workflow.hivecommons.dev/v1alpha1` schema gains the lifecycle half of the RFC — `columns`, `derivation`, `events`, `gates`, `roles`, `agents`, `checks`, `bookkeeping`, `labels`, `meta` and per-state `lifecycle` (column, stage number, item kinds, replies) — and `workflowmodel.Compile` turns a model into a `Profile` or refuses it with coded diagnostics (a non-terminal state with no exit, a gate with no releasing role, an agent-granted state with no human-released gate before a terminal outcome, two events bound to one fact, a state in no or two columns, duplicate stage numbers, an unknown fact or operator). `pkg/workflowmodel/hivedefault` generates the `hive-default` model from the live stage table and the engine's expected-edge table, so the monitor's seven columns and the stage numbers are now a compiled model rather than constants. `stageengine.DeriveFromModel` derives under a compiled profile: `hive-default` declares `derivation: builtin` and delegates to the existing derivers (the whole PR stage-golden corpus and the issue sweep derive identically), custom models declare `derivation: rules` (ordered first-match predicates over the fact vocabulary, uncovered items abstain `workflow: not covered`). New `workflow.enabled` config flag, default false; nothing changes for any hive until a repository is bound (phase 2).
33 changes: 32 additions & 1 deletion src/docs/design/workflow-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,9 @@ state it fills. One workflow serving several triggers binds to each role its tri

| Package | Role |
|---|---|
| `pkg/workflowmodel` | types, `Validate`, `Hash`, `HiveDefault`, `Bind`, topological `Levels` |
| `pkg/workflowmodel` | types, `Validate`, `Hash`, `HiveDefault`, `Bind`, topological `Levels`, `Compile` → `Profile` |
| `pkg/workflowmodel/hivedefault` | `Generate()` the `hive-default` model from `stagelabels.Table` + `stageengine.DiagramEdges()`; `Profile()` compiled |
| `pkg/stageengine` (`workflow.go`) | `DeriveFromModel(profile, kind)`: builtin delegation or the rules evaluator; `Options.Workflow` |
| `pkg/workflowmodel/githubactions` | `.github/workflows/*.y*ml` → pipelines |
| `pkg/workflowmodel/tekton` | Pipeline / PipelineRun / Task (+ Pipelines-as-Code annotations) → pipelines |
| `pkg/workflowmodel/ingest` | `Repository(scope, files)`: route files to ingesters, compose, bind |
Expand Down Expand Up @@ -62,6 +64,35 @@ golden summary per repository; `go test ./pkg/workflowmodel/ingest -update` rewr
after an intended change. The full 317-repository CNCF-landscape survey and its collector live
outside the repository; the results are on #17620.

## Lifecycle half and the compiler (RFC phase 1)

The RFC (#17620) asks for one engine that derives under any model. The decision that keeps v5/v6
byte-identical is that **`hive-default` derivation stays in Go**: `hivedefault.Generate()` builds
the model from the stage table, the engine's expected edges and the monitor's column anchors, and
declares `derivation: builtin`. `stageengine.DeriveFromModel` then delegates to `IssueDeriver` /
`PRDeriver` and only checks coverage — a stage the model has no state for abstains with
`workflow: not covered` instead of writing a label the model does not know. The parity test
(`TestDeriveFromModelHiveDefaultParity`) runs every PR stage golden and an issue sweep through both
and requires identical `Decision`s.

Custom models declare `derivation: rules`: ordered rules, each a conjunction of predicates over the
fact vocabulary in `workflowmodel.Facts` (`open`, `merged`, `draft`, `labels has stage/*`,
`author.kind is human`, `pr.checks is green`, `pr.review is approved`, `issue.covered`, …); the
first rule whose predicates all hold names the state, and an item no rule matches is not covered.
Rules reach only the facts the engine already computes; no LLM is ever in the derivation path.
`testdata/models/techdocs.json` is the hand-written reference model (cncf/techdocs engagement).

`Compile` refuses (error diagnostics, no profile): `state-no-exit`, `gate-no-owner`,
`agent-no-human-gate` (every path from an agent-granted state to a terminal outcome must cross a
transition gated by a role with `human: true`; closure edges — the item closed unmerged — are
observations and exempt), `duplicate-event-fact`, `state-no-column` / `unknown-column`,
`duplicate-stage-number`, `unknown-fact` / `bad-op`, `no-rules`, `no-version`. Elements marked
`confidence: inferred` compile with an `inferred-element` warning the editor shows.

Stage numbers in a model are Hive's label numbers (`stagelabels.Table`) for now, so a bound repo's
labels, tracker anchors and replies keep working; a state whose number does not apply to the item
kind is not covered. Models are whole (no inheritance) through phase 4.

## Known gaps (phase 1)

- Prow (`kubernetes/*`) is a third syntax not read; those repos render the default columns.
Expand Down
14 changes: 12 additions & 2 deletions src/pkg/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -82,8 +82,13 @@ type Config struct {
// Dedupe tunes the dedupe lane's follow-through on its checklists.
Dedupe DedupeLaneConfig `yaml:"dedupe,omitempty" json:"dedupe,omitempty"`
Contribute ContributeConfig `yaml:"contribute,omitempty" json:"contribute,omitempty"`
HiveID string `yaml:"hive_id"`
ACMMLevel *int `yaml:"acmm_level,omitempty" json:"acmm_level"`
// Workflow gates the workflow-model engine (hivecommons/hive#17620).
// Off by default: every repository derives stages with the built-in
// derivers exactly as before. On, repositories bound to a workflow
// model derive through it; unbound repositories are unchanged.
Workflow WorkflowConfig `yaml:"workflow,omitempty" json:"workflow,omitempty"`
HiveID string `yaml:"hive_id"`
ACMMLevel *int `yaml:"acmm_level,omitempty" json:"acmm_level"`
// ModelRoles is the named model-roles map (#9722): a small set of names,
// each naming a backend, a model and a reasoning effort, referenced as
// "@<role>" wherever hive asks for a model (today: agents' model and the
Expand Down Expand Up @@ -274,6 +279,11 @@ type Config struct {
ReviewerAutoscaleActive int `yaml:"-" json:"-"`
}

// WorkflowConfig is the `workflow:` block (hivecommons/hive#17620).
type WorkflowConfig struct {
Enabled bool `yaml:"enabled" json:"enabled"`
}

type DataConfig struct {
MetricsDir string `yaml:"metrics_dir"`
LogsDir string `yaml:"logs_dir"`
Expand Down
21 changes: 12 additions & 9 deletions src/pkg/config/testdata/agent_runtime_golden.json
Original file line number Diff line number Diff line change
Expand Up @@ -447,8 +447,8 @@
"BaseURL": "",
"AppAuthoredPRs": null,
"AppSignedCommits": null,
"attention": {},
"notifications": {},
"attention": {},
"OAuthBaseURLOverride": "",
"OAuthAPIURLOverride": ""
},
Expand All @@ -473,6 +473,7 @@
"Port": 8080,
"AuthToken": "",
"AgentPollIntervalS": 10,
"matrix": {},
"AuthorizedUsers": null,
"AuthorizedUserNames": null,
"HubProxied": false,
Expand All @@ -483,7 +484,6 @@
}
},
"issue_bands": {},
"matrix": {},
"stage_tracker": {}
},
"Data": {
Expand Down Expand Up @@ -686,6 +686,9 @@
"fleet": {},
"dedupe": {},
"contribute": {},
"workflow": {
"enabled": false
},
"HiveID": "",
"acmm_level": null,
"advisor": {},
Expand Down Expand Up @@ -723,6 +726,13 @@
},
"intent": {},
"sentinel": {},
"security": {},
"evidence": {
"complexity": {}
},
"compliance": {
"posture_checks": {}
},
"escalation": {
"email": {
"smtp": {},
Expand All @@ -734,10 +744,6 @@
"pagerduty": {}
}
},
"security": {},
"evidence": {
"complexity": {}
},
"jev": {},
"runs": {
"checkpoints": {},
Expand Down Expand Up @@ -776,9 +782,6 @@
"recommendations": {},
"plan_match": {}
},
"compliance": {
"posture_checks": {}
},
"auto_merge": {
"bot_takeover": {},
"trusted_authors": {},
Expand Down
44 changes: 44 additions & 0 deletions src/pkg/stageengine/export_parity_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
package stageengine

import (
"github.com/hivecommons/hive/pkg/claims"
"github.com/hivecommons/hive/pkg/stagelabels"
)

// ParityFacts hands the external parity test (workflow_parity_test.go,
// package stageengine_test — it imports hivedefault, which imports this
// package, so it cannot live here) the Facts corpus the built-in derivers
// are pinned by: every generated PR stage golden plus a sweep of issue
// facts reaching each issue stage. hivecommons/hive#17620.
func ParityFacts() []Facts {
var out []Facts
for _, cases := range generateStageGoldens() {
for _, c := range cases {
_, f := runStageGoldenWithFacts(c.Input)
out = append(out, f)
}
}
pr99 := &Ref{Owner: "acme", Repo: "widgets", Number: 99, Kind: stagelabels.PRItem}
for _, mut := range []func(f *Facts){
nil,
func(f *Facts) { f.Issue.Bucket = BucketDependencyDashboard; f.Park.NeedsHuman = true },
func(f *Facts) { f.Issue.TriageAwaiting = "carries needs-triage" },
func(f *Facts) {
f.Issue.Bucket = BucketClaimed
f.Issue.Claim = &ClaimFact{Holder: "bob", Kind: "human"}
},
func(f *Facts) {
f.Issue.Bucket = BucketClaimed
f.Issue.Claim = &ClaimFact{Kind: claims.KindAgent, PRStarted: true}
},
func(f *Facts) { f.Issue.Bucket = BucketCoveredByPR; f.Issue.CoveringPR = pr99 },
func(f *Facts) { f.Park.NeedsHuman = true },
func(f *Facts) { f.Park.PossiblyExists = true },
func(f *Facts) { f.Issue.DiscussionLabel = "proposal" },
func(f *Facts) { f.Open = false },
func(f *Facts) { f.Issue.Bucket = BucketFiltered },
} {
out = append(out, derivedIssueFacts(mut))
}
return out
}
24 changes: 16 additions & 8 deletions src/pkg/stageengine/reconciler.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import (
"time"

"github.com/hivecommons/hive/pkg/stagelabels"
"github.com/hivecommons/hive/pkg/workflowmodel"
)

// Transition is what Reconcile reports to its caller and the audit log.
Expand Down Expand Up @@ -38,14 +39,17 @@ type Reconciler interface {

// Options configures New.
type Options struct {
Mode Mode
Store *stagelabels.Store // stagelabels.Shared() by default; API unchanged
Writer StageWriter
Issue Deriver // defaults to DeriveIssue
PR Deriver // defaults to DerivePR
Now func() time.Time
Logger *slog.Logger
Metrics Metrics
Mode Mode
Store *stagelabels.Store // stagelabels.Shared() by default; API unchanged
Writer StageWriter
Issue Deriver // defaults to DeriveIssue
PR Deriver // defaults to DerivePR
// Workflow, when set, derives through the compiled workflow model
// (DeriveFromModel) and overrides Issue and PR. hivecommons/hive#17620.
Workflow *workflowmodel.Profile
Now func() time.Time
Logger *slog.Logger
Metrics Metrics
}

// ErrNoWriter is returned by an enforce-mode Reconcile with no Writer.
Expand Down Expand Up @@ -73,6 +77,10 @@ func New(o Options) Reconciler {
if o.Store == nil {
o.Store = stagelabels.Shared()
}
if o.Workflow != nil {
o.Issue = DeriveFromModel(o.Workflow, stagelabels.IssueItem)
o.PR = DeriveFromModel(o.Workflow, stagelabels.PRItem)
}
if o.Issue == nil {
o.Issue = IssueDeriver()
}
Expand Down
Loading
Loading