diff --git a/internal/app/agentworker/step_vocabulary_test.go b/internal/app/agentworker/step_vocabulary_test.go index 30894a5cb..8f64d5eef 100644 --- a/internal/app/agentworker/step_vocabulary_test.go +++ b/internal/app/agentworker/step_vocabulary_test.go @@ -7,6 +7,7 @@ import ( "gopkg.in/yaml.v3" "github.com/samcharles93/archie-core/internal/domain/workflow" + "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" ) // stepVocabularyProbe is a provider set of one, used only to prove the @@ -44,13 +45,27 @@ func requireSharedStepVocabulary(t *testing.T, steps *workflow.Manager) { if steps == nil { t.Fatal("the composition root registered no workflow step vocabulary") } - want := make([]string, 0, len(workflow.BuiltinStepRegistry())) + got := steps.StepTypes() + // Containment, not equality: adding a provider to the shared set + // (workflowsteps.Providers) is the documented way a step type arrives, and + // that must not have to edit this guard. What it holds is that the shipped + // stages are all present, which is what a root regressing to + // workflow.NewManager() loses. for name := range workflow.BuiltinStepRegistry() { - want = append(want, name) + if !slices.Contains(got, name) { + t.Errorf("the composition root resolves %v, which is missing the shipped stage %q", got, name) + } } - slices.Sort(want) - if got := steps.StepTypes(); !slices.Equal(got, want) { - t.Fatalf("the composition root resolves %v, want the shared provider set's shipped stages %v", got, want) + // The other half is provenance: every name the root resolves must be + // declared by the shared provider set, not by a near-identical provider of + // the root's own, because that set is what ties this process's vocabulary to + // the State Store that validates against it. It is content, not identity -- + // the shipped provider rebuilds its factories on every call. + declared := sharedStepTypeNames() + for _, name := range got { + if !slices.Contains(declared, name) { + t.Errorf("the composition root resolves %q, which no provider in the shared set declares", name) + } } if err := steps.Register(stepVocabularyProbe{}); err != nil { t.Fatalf("register a provider through the root's manager: %v", err) @@ -59,3 +74,16 @@ func requireSharedStepVocabulary(t *testing.T, steps *workflow.Manager) { t.Fatal("a provider registered through the root's manager did not reach its vocabulary") } } + +// sharedStepTypeNames returns the step types the shared provider set declares, +// read through the same Providers() seam the composition roots register. +func sharedStepTypeNames() []string { + names := make([]string, 0) + for _, provider := range workflowsteps.Providers() { + for _, stepType := range provider.StepTypes() { + names = append(names, stepType.Name) + } + } + slices.Sort(names) + return names +} diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index a630caa34..81d22d283 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -27,6 +27,7 @@ import ( "github.com/samcharles93/archie-core/internal/app/controlplane" "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/container" + controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" "github.com/samcharles93/archie-core/internal/daemon" "github.com/samcharles93/archie-core/internal/domain/applystatus" "github.com/samcharles93/archie-core/internal/domain/curator" @@ -116,6 +117,11 @@ type boot struct { stateStoreGrants *staterpc.GrantIssuer stateStoreToken string controlPlane *controlplane.Client + // controlPlaneRPC is the State Store's control-plane transport, kept so the + // daemon root can build its workflow-definitions client from it + // (openDaemonWorkflowDefinitions). The gateway root never builds that client: + // it resolves no workflow step type. + controlPlaneRPC controlpb.ControlPlaneServiceClient // workflowDefinitions is the one control-plane surface that resolves // workflow step types. It is separate from controlPlane because it is the // only surface that needs the process's step vocabulary. @@ -361,24 +367,15 @@ func (b *boot) openStateStoreAdapter() error { return err } b.stateStore = client - // The daemon reads and replaces workflow definitions through the - // workflow-definitions client, so it resolves the same step vocabulary the - // State Store server validates against: registered here, at the composition - // root, before the first read, through stepVocabulary (see - // step_vocabulary_test.go, which pins both archied roots to it). That - // agreement holds within one build: the State Store is a separate binary, - // and a skewed deploy is only fixed by a matching deploy. - steps, err := stepVocabulary() - if err != nil { - b.log.Error("register workflow step vocabulary", "err", err) - return err - } - b.controlPlane = controlplane.NewRPCClient(client.ControlPlane()) - b.workflowDefinitions, err = controlplane.NewWorkflowDefinitionsClient(client.ControlPlane(), steps) - if err != nil { - b.log.Error("workflow definitions client", "err", err) - return err - } + // The daemon reads workflow definitions through the workflow-definitions + // client, built by the daemon root (openDaemonWorkflowDefinitions) on this + // process's step vocabulary, so the daemon resolves the same vocabulary the + // State Store server validates against. It is not built here because the + // gateway root shares this adapter and resolves no step type. That agreement + // holds within one build: the State Store is a separate binary, and a skewed + // deploy is only fixed by a matching deploy. + b.controlPlaneRPC = client.ControlPlane() + b.controlPlane = controlplane.NewRPCClient(b.controlPlaneRPC) b.applyStatus = applystatus.New(b.processName, client, b.log) b.stateStoreGrants = &staterpc.GrantIssuer{Client: client} b.stateStoreToken = b.cfg.Services.ResolvedToken(config.ServiceNameState, b.secrets.Getenv) diff --git a/internal/app/archied/main.go b/internal/app/archied/main.go index 30fc84727..8ccca99c7 100644 --- a/internal/app/archied/main.go +++ b/internal/app/archied/main.go @@ -379,6 +379,15 @@ func Run() int { //nolint:cyclop,funlen // the composition root's setup sequence if err := b.openStateStoreAdapter(); err != nil { return 1 } + // The daemon resolves workflow step types through its workflow-definitions + // client, so it registers the step vocabulary here, at its own composition + // root, before buildDaemon captures the client. The gateway root shares + // openStateStoreAdapter and resolves no step type, so the vocabulary is built + // by this root alone (step_vocabulary_test.go pins the cut). + if err := b.openDaemonWorkflowDefinitions(); err != nil { + b.log.Error("workflow definitions client", "err", err) + return 1 + } if err := b.loadRuntimeConfig(ctx); err != nil { b.log.Error("runtime settings unavailable", "err", err) return 1 diff --git a/internal/app/archied/step_vocabulary.go b/internal/app/archied/step_vocabulary.go index a59c1ba7e..76eef2c2c 100644 --- a/internal/app/archied/step_vocabulary.go +++ b/internal/app/archied/step_vocabulary.go @@ -1,24 +1,57 @@ package archied import ( + "fmt" + + "github.com/samcharles93/archie-core/internal/app/controlplane" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" ) -// stepVocabulary builds the workflow step vocabulary this archied process -// resolves workflow definitions against: the shared provider set -// (internal/infrastructure/workflowsteps), registered here at the composition -// root, before the first resolution. +// stepVocabulary builds the workflow step vocabulary a process resolves +// workflow definitions against: the shared provider set +// (internal/infrastructure/workflowsteps), registered at the composition root, +// before the first resolution. // -// Both archied roots call it -- RunStateStore (the State Store's validating -// side) and openStateStoreAdapter (the daemon's control-plane client) -- so -// neither can register a vocabulary of its own. It is a named function so that -// step_vocabulary_test.go can fail if it stops using the shared provider set; -// the roots themselves own a SQLite file and dial gRPC, so the test asserts -// they call it by parsing their bodies. +// Two roots call it, and both are roots that resolve a step type: RunStateStore +// (the State Store's validating side) and openDaemonWorkflowDefinitions (the +// daemon's workflow-definitions client). A root that cannot reach a workflow +// definition registers no vocabulary and cannot be failed by one, which is why +// the gateway root and internal/app/archiemessaging are not here. +// +// It is a named function so that step_vocabulary_test.go can fail if a root +// stops resolving the shipped stages, or hands a constructor a manager other +// than the one this returns; the roots themselves own a SQLite file and dial +// gRPC, so the test asserts their wiring by parsing their bodies. // // Agreement is within one build: the State Store and archie-agent are // separately deployed binaries, so a State Store built from newer source than // the agent it dispatches to can still disagree, and only a matching deploy // fixes that. func stepVocabulary() (*workflow.Manager, error) { return workflowsteps.NewManager() } + +// openDaemonWorkflowDefinitions builds the daemon's workflow-definitions +// client on the process step vocabulary, and is called by the daemon root alone +// (main.go's Run) before buildDaemon captures the client. +// +// It is deliberately not part of openStateStoreAdapter, which the gateway root +// shares: the gateway reads catalog, runtime settings and personas, never a +// workflow definition, so registering a vocabulary there would be the dead +// vocabulary this shape removed from internal/app/archiemessaging -- a root that +// cannot consume it must not be failed by it. +// +// The daemon reads definitions through it; no production process replaces +// definitions yet (see controlplane.WorkflowDefinitionsClient. +// ReplaceWorkflowDefinitions). +func (b *boot) openDaemonWorkflowDefinitions() error { + steps, err := stepVocabulary() + if err != nil { + return fmt.Errorf("register workflow step vocabulary: %w", err) + } + definitions, err := controlplane.NewWorkflowDefinitionsClient(b.controlPlaneRPC, steps) + if err != nil { + return fmt.Errorf("build workflow definitions client: %w", err) + } + b.workflowDefinitions = definitions + return nil +} diff --git a/internal/app/archied/step_vocabulary_test.go b/internal/app/archied/step_vocabulary_test.go index a1f63a085..dca53146d 100644 --- a/internal/app/archied/step_vocabulary_test.go +++ b/internal/app/archied/step_vocabulary_test.go @@ -10,6 +10,7 @@ import ( "gopkg.in/yaml.v3" "github.com/samcharles93/archie-core/internal/domain/workflow" + "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" ) // stepVocabularyProbe is a provider set of one, used only to prove the manager @@ -24,61 +25,214 @@ func (stepVocabularyProbe) StepTypes() []workflow.StepType { }}} } -// TestStepVocabularyRegistersTheSharedProviderSet pins the unit both archied -// roots resolve their vocabulary from. Handing this function an empty manager -// (workflow.NewManager) would leave the State Store unable to admit any stored -// definition and the daemon unable to decode one. +// sharedStepTypeNames returns the step types the shared provider set +// (internal/infrastructure/workflowsteps) declares. It is read through the same +// Providers() seam the composition roots register, rather than from +// workflow.BuiltinStepRegistry(): the shipped stages arrive by registration, and +// a provider added to that set is the documented way a step type enters every +// binary at once. +func sharedStepTypeNames() []string { + names := make([]string, 0) + for _, provider := range workflowsteps.Providers() { + for _, stepType := range provider.StepTypes() { + names = append(names, stepType.Name) + } + } + slices.Sort(names) + return names +} + +// requireSharedStepVocabulary holds a composition root's manager to both halves +// of the contract: it resolves the shipped vocabulary, and it is live enough to +// take a provider registered through it. +func requireSharedStepVocabulary(t *testing.T, steps *workflow.Manager) { + t.Helper() + if steps == nil { + t.Fatal("the composition root registered no workflow step vocabulary") + } + got := steps.StepTypes() + // Containment, not equality: adding a provider to the shared set is the + // documented way a step type arrives, and that must not have to edit this + // guard. What the guard holds is that no shipped stage is missing, which is + // what a root regressing to workflow.NewManager() loses. + for name := range workflow.BuiltinStepRegistry() { + if !slices.Contains(got, name) { + t.Errorf("the composition root resolves %v, which is missing the shipped stage %q", got, name) + } + } + // The other half is provenance: every name the root resolves must be + // declared by the shared provider set, not by a near-identical provider of + // the root's own. That set is what ties this process's vocabulary to the + // other side of the contract. It is content, not identity -- the shipped + // provider rebuilds its factories on every call -- so a root that stopped + // importing the shared set and hand-rolled an equal one would still pass. + declared := sharedStepTypeNames() + for _, name := range got { + if !slices.Contains(declared, name) { + t.Errorf("the composition root resolves %q, which no provider in the shared set declares", name) + } + } + if err := steps.Register(stepVocabularyProbe{}); err != nil { + t.Fatalf("register a provider through the root's manager: %v", err) + } + if _, resolved := steps.Registry()["probe.registered"]; !resolved { + t.Fatal("a provider registered through the root's manager did not reach its vocabulary") + } +} + +// TestStepVocabularyRegistersTheSharedProviderSet pins the unit the daemon root +// resolves its vocabulary from. Handing this function an empty manager +// (workflow.NewManager) would leave the daemon unable to decode the stored +// definitions it pins onto tasks. func TestStepVocabularyRegistersTheSharedProviderSet(t *testing.T) { steps, err := stepVocabulary() if err != nil { t.Fatalf("stepVocabulary: %v", err) } - if steps == nil { - t.Fatal("stepVocabulary registered no workflow step vocabulary") - } - want := make([]string, 0, len(workflow.BuiltinStepRegistry())) - for name := range workflow.BuiltinStepRegistry() { - want = append(want, name) - } - slices.Sort(want) - if got := steps.StepTypes(); !slices.Equal(got, want) { - t.Fatalf("archied resolves %v, want the shared provider set's shipped stages %v", got, want) - } - if err := steps.Register(stepVocabularyProbe{}); err != nil { - t.Fatalf("register a provider through archied's manager: %v", err) - } - if _, resolved := steps.Registry()["probe.registered"]; !resolved { - t.Fatal("a provider registered through archied's manager did not reach its vocabulary") - } + requireSharedStepVocabulary(t, steps) } -// TestArchiedRootsResolveTheStepVocabularyFromThatFunction pins that reading -// through stepVocabulary is how both roots reach the vocabulary. Neither root -// can be executed in a unit test -- RunStateStore owns a SQLite file and -// listen address, openStateStoreAdapter dials the State Store -- so the calls -// are asserted by source position, the way composition_order_test.go pins the -// memory-engine ordering for the same reason. A root that built its own manager -// would resolve a vocabulary of its own and silently lose the shipped stages. +// TestArchiedRootsResolveTheStepVocabularyFromThatFunction pins both halves of +// each root's wiring: the root reaches the vocabulary through stepVocabulary, +// and the manager it returns is the one handed to the constructor that resolves +// a step type with it. Neither root can be executed in a unit test -- Run owns +// a SQLite file and a listen address, openDaemonWorkflowDefinitions dials the +// State Store -- so both are asserted by source position, the way +// composition_order_test.go pins the memory-engine ordering for the same +// reason. A root that built its own manager, or built one and handed the +// constructor a different one, would resolve a vocabulary without the shipped +// stages. func TestArchiedRootsResolveTheStepVocabularyFromThatFunction(t *testing.T) { - for _, link := range []struct{ file, function, resolves string }{ - {"state_store.go", "RunStateStore", "openStateStoreControlPlane"}, - // RunStateStore delegates to this function, which is where the shipped - // stages enter this process. - {"state_store.go", "openStateStoreControlPlane", "stepVocabulary"}, - {"bootstrap.go", "openStateStoreAdapter", "stepVocabulary"}, + for _, link := range []struct{ file, function, constructor string }{ + // The validating side: the State Store's control plane server. + {"state_store.go", "openStateStoreControlPlane", "NewServer"}, + // The executing side's client, built by the daemon root alone. + {"step_vocabulary.go", "openDaemonWorkflowDefinitions", "NewWorkflowDefinitionsClient"}, } { - t.Run(link.function+"->"+link.resolves, func(t *testing.T) { - file, err := parser.ParseFile(token.NewFileSet(), link.file, nil, 0) - if err != nil { - t.Fatal(err) + t.Run(link.function+"->stepVocabulary->"+link.constructor, func(t *testing.T) { + body := parsedBody(t, link.file, link.function) + manager := stepVocabularyAssignment(body) + if manager == "" { + t.Fatalf("%s does not build its step vocabulary through stepVocabulary()", link.function) } - if identCallPosition(methodBody(t, file, link.function), link.resolves) == token.NoPos { - t.Errorf("%s does not reach its step vocabulary through %s()", link.function, link.resolves) + if !callPassesIdent(body, link.constructor, manager) { + t.Errorf("%s does not hand the manager stepVocabulary() returned (%s) to %s()", link.function, manager, link.constructor) } }) } } +// TestOnlyTheDaemonRootRegistersAStepVocabulary pins the cut the shape applies +// to every other process: a root that cannot resolve a step type registers no +// vocabulary and cannot be failed by one. openStateStoreAdapter is shared by the +// daemon and the gateway, and the gateway resolves no step type -- its +// control-plane surfaces are catalog, runtime settings and personas -- so the +// vocabulary belongs to the daemon root alone, exactly as +// internal/app/archiemessaging's dead vocabulary was removed. Asserted by +// source position for the same reason as above. +func TestOnlyTheDaemonRootRegistersAStepVocabulary(t *testing.T) { + if pos := identCallPosition(parsedBody(t, "bootstrap.go", "openStateStoreAdapter"), "stepVocabulary"); pos != token.NoPos { + t.Error("openStateStoreAdapter registers a step vocabulary; it is shared with the gateway root, which never resolves a step type") + } + if fileMentionsIdent(t, "gateway.go", "stepVocabulary") { + t.Error("the gateway root file mentions stepVocabulary; the gateway resolves no workflow step type") + } + + run := parsedBody(t, "main.go", "Run") + adapter := methodCallPosition(run, "openStateStoreAdapter") + wiring := methodCallPosition(run, "openDaemonWorkflowDefinitions") + build := methodCallPosition(run, "buildDaemon") + if wiring == token.NoPos { + t.Fatal("Run never builds the daemon's workflow-definitions client; every task pin would fall back to the shipped definitions") + } + if adapter == token.NoPos || wiring < adapter { + t.Errorf("Run builds the workflow-definitions client at %v, at or before openStateStoreAdapter at %v: it would wrap the transport the adapter has not opened yet", wiring, adapter) + } + if build == token.NoPos || wiring > build { + t.Errorf("Run builds the workflow-definitions client at %v, after buildDaemon at %v: the daemon would capture no definitions surface", wiring, build) + } +} + +func parsedBody(t *testing.T, file, function string) *ast.BlockStmt { + t.Helper() + parsed, err := parser.ParseFile(token.NewFileSet(), file, nil, 0) + if err != nil { + t.Fatal(err) + } + return methodBody(t, parsed, function) +} + +// stepVocabularyAssignment returns the identifier assigned from a direct call +// to stepVocabulary() in body, or "" when body never calls it. +func stepVocabularyAssignment(body *ast.BlockStmt) string { + manager := "" + ast.Inspect(body, func(node ast.Node) bool { + assign, ok := node.(*ast.AssignStmt) + if !ok || len(assign.Lhs) == 0 || len(assign.Rhs) == 0 || manager != "" { + return true + } + call, ok := assign.Rhs[0].(*ast.CallExpr) + if !ok { + return true + } + callee, ok := call.Fun.(*ast.Ident) + if !ok || callee.Name != "stepVocabulary" { + return true + } + if lhs, ok := assign.Lhs[0].(*ast.Ident); ok { + manager = lhs.Name + } + return true + }) + return manager +} + +// callPassesIdent reports whether some call to name (bare or selected) passes an +// identifier called ident as an argument. +func callPassesIdent(body *ast.BlockStmt, name, ident string) bool { + found := false + ast.Inspect(body, func(node ast.Node) bool { + call, ok := node.(*ast.CallExpr) + if !ok || !callNameIs(call, name) { + return true + } + for _, argument := range call.Args { + if passed, ok := argument.(*ast.Ident); ok && passed.Name == ident { + found = true + } + } + return true + }) + return found +} + +func callNameIs(call *ast.CallExpr, name string) bool { + switch fun := call.Fun.(type) { + case *ast.Ident: + return fun.Name == name + case *ast.SelectorExpr: + return fun.Sel.Name == name + } + return false +} + +// fileMentionsIdent reports whether any declaration in file names ident. +func fileMentionsIdent(t *testing.T, file, ident string) bool { + t.Helper() + parsed, err := parser.ParseFile(token.NewFileSet(), file, nil, 0) + if err != nil { + t.Fatal(err) + } + mentions := false + ast.Inspect(parsed, func(node ast.Node) bool { + if found, ok := node.(*ast.Ident); ok && found.Name == ident { + mentions = true + } + return true + }) + return mentions +} + // identCallPosition returns the position of the first call to a bare function // name in body, or token.NoPos when the body never calls it. func identCallPosition(body *ast.BlockStmt, name string) token.Pos { diff --git a/internal/app/controlplane/client.go b/internal/app/controlplane/client.go index de3583b1d..f1e1e1c0d 100644 --- a/internal/app/controlplane/client.go +++ b/internal/app/controlplane/client.go @@ -20,7 +20,8 @@ import ( // Client is the control-plane client for every resource that does not resolve // a workflow step type: catalog, history, settings, personas, schedules. It // carries no step vocabulary, so a process that never reads or writes a -// workflow definition -- archie-messaging, which only loads channel settings -- +// workflow definition -- archie-messaging, which only loads channel settings, +// and archie-gateway, which reads catalog, runtime settings and personas -- // needs no provider set and cannot be failed by one. type Client struct{ rpc pb.ControlPlaneServiceClient } @@ -69,6 +70,10 @@ func (c *WorkflowDefinitionsClient) WorkflowDefinitions(ctx context.Context) (wo // ReplaceWorkflowDefinitions replaces the collection. Passing // workflow.ShippedDefinitions() restores all shipped definitions while keeping // the previous override in resource history. +// +// No production process calls it today: the daemon's only consumer of this +// surface reads (internal/daemon's WorkflowDefinitions interface), so this half +// is reached by tests until a writer exists. func (c *WorkflowDefinitionsClient) ReplaceWorkflowDefinitions(ctx context.Context, definitions workflow.WorkflowDefinitionCollection, expectedVersion int64, actor, source, requestID string) (int64, error) { value, err := encodeWorkflowDefinitions(definitions, c.steps) if err != nil { diff --git a/internal/app/controlplane/step_vocabulary_agreement_test.go b/internal/app/controlplane/step_vocabulary_agreement_test.go index d4a4d9ab5..4c8a37f4f 100644 --- a/internal/app/controlplane/step_vocabulary_agreement_test.go +++ b/internal/app/controlplane/step_vocabulary_agreement_test.go @@ -3,7 +3,11 @@ // side (archie-agent) compiles it. Two packages that each pass their own tests // and disagree with each other is the failure archie-core-fwmp exists to // prevent, so this is the one test that registers a provider through the -// production Manager and drives every production resolution site with it. +// production Manager and drives the production entry points that resolve a step +// type with it: the State Store server, the daemon's workflow-definitions +// client (its read path, and its write path, which no production caller reaches +// yet) and agentworker.CompilePinnedWorkflow. A site these do not enumerate is +// caught by TestNoProductionSiteReachesForTheBuiltinStepRegistry below. // // "Agreement" here means within one build: archie-state-store and archie-agent // are separately deployed binaries, so a State Store built from newer source @@ -15,6 +19,11 @@ package controlplane import ( "context" "encoding/json" + "go/ast" + "go/parser" + "go/token" + "io/fs" + "path/filepath" "strings" "testing" @@ -319,3 +328,70 @@ func (c *definitionsClient) Command(_ context.Context, request *pb.CommandReques func (c *definitionsClient) Watch(context.Context, *pb.WatchRequest, ...grpc.CallOption) (grpc.ServerStreamingClient[pb.WatchResponse], error) { panic("Watch is not part of the workflow-definitions path") } + +// TestNoProductionSiteReachesForTheBuiltinStepRegistry guards the class of +// defect archie-core-fwmp exists to remove: a call site that resolves workflow +// step types out of workflow.BuiltinStepRegistry() instead of the manager its +// composition root registered. The agreement test above can only drive the +// entry points it enumerates, so a sixth one added later would validate, or +// fail to compile, against a vocabulary no other process has. Exactly two +// non-test files may name it: the domain file that declares it, and the shipped +// provider that bundles the shipped stages through it. +func TestNoProductionSiteReachesForTheBuiltinStepRegistry(t *testing.T) { + allowed := map[string]string{ + filepath.Join("internal", "domain", "workflow", "definition.go"): "declares BuiltinStepRegistry", + filepath.Join("internal", "infrastructure", "workflowsteps", "workflowsteps.go"): "bundles the shipped stages as a provider", + } + // The module root, three levels up from this package. + root := filepath.Join("..", "..", "..") + scanned := 0 + walkErr := filepath.WalkDir(root, func(path string, entry fs.DirEntry, err error) error { + if err != nil { + return err + } + name := entry.Name() + if entry.IsDir() { + // The root is "../../..", whose own name starts with a dot: only + // directories below it are filtered. + if path == root { + return nil + } + // tools is a separate module, and the rest carry no Archie source. + if name == "tools" || name == "node_modules" || name == "testdata" || name == "vendor" || strings.HasPrefix(name, ".") { + return fs.SkipDir + } + return nil + } + if !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") { + return nil + } + relative, relErr := filepath.Rel(root, path) + if relErr != nil { + return relErr + } + if _, permitted := allowed[relative]; permitted { + return nil + } + file, parseErr := parser.ParseFile(token.NewFileSet(), path, nil, 0) + if parseErr != nil { + return parseErr + } + scanned++ + ast.Inspect(file, func(node ast.Node) bool { + if ident, ok := node.(*ast.Ident); ok && ident.Name == "BuiltinStepRegistry" { + t.Errorf("%s names BuiltinStepRegistry; only %s (%s) and %s (%s) may, or that resolution site keeps a step vocabulary of its own", + relative, + filepath.Join("internal", "domain", "workflow", "definition.go"), allowed[filepath.Join("internal", "domain", "workflow", "definition.go")], + filepath.Join("internal", "infrastructure", "workflowsteps", "workflowsteps.go"), allowed[filepath.Join("internal", "infrastructure", "workflowsteps", "workflowsteps.go")]) + } + return true + }) + return nil + }) + if walkErr != nil { + t.Fatalf("scan the module for BuiltinStepRegistry: %v", walkErr) + } + if scanned == 0 { + t.Fatal("the scan read no non-test Go file; it is not looking at the module") + } +} diff --git a/internal/infrastructure/workflowsteps/workflowsteps.go b/internal/infrastructure/workflowsteps/workflowsteps.go index ed51d52d7..7de185f22 100644 --- a/internal/infrastructure/workflowsteps/workflowsteps.go +++ b/internal/infrastructure/workflowsteps/workflowsteps.go @@ -1,13 +1,15 @@ // Package workflowsteps is the compiled-in workflow step-type provider set: -// the one place a step type is bundled into every Archie binary. +// the one place a step type is bundled into the Archie binaries that resolve +// one, so no such binary can keep a provider set of its own. // -// Three composition roots import it, and each resolves a workflow step type: -// archied's RunStateStore (the State Store's validating side), archied's -// openStateStoreAdapter (the daemon's workflow-definitions client) and -// agentworker's productionWorkerDependencies (the executing side). Sharing one -// package is what keeps them registering the same vocabulary rather than one -// of them keeping a provider set of its own. archie-messaging resolves no step -// type and does not import it. +// Two composition roots register it, both of them roots that resolve a step +// type: archied's RunStateStore (the State Store's validating side) and +// archied's daemon root (openDaemonWorkflowDefinitions, the executing side's +// workflow-definitions client, alongside agentworker's +// productionWorkerDependencies). Sharing one package is what keeps them +// registering the same vocabulary. Processes that resolve no step type do not +// import it and register nothing: archie-gateway, archie-messaging, +// archie-playbooks and archie-ui. package workflowsteps import ( @@ -36,8 +38,10 @@ func (shippedStages) StepTypes() []workflow.StepType { return stepTypes } -// Providers returns the provider set every Archie process registers at its -// composition root, before the first resolution. A step type added here becomes +// Providers returns the provider set the roots that resolve a workflow step +// type register at their composition root, before the first resolution: it is +// what NewManager registers, and what the roots' guards read to hold a +// registered vocabulary to the set it came from. A step type added here becomes // reachable from the validating side and the executing side at once. // // The set is a compiled-in constant rather than a directory scan: a step type diff --git a/internal/infrastructure/workflowsteps/workflowsteps_test.go b/internal/infrastructure/workflowsteps/workflowsteps_test.go index 33657931c..ee9ad4d70 100644 --- a/internal/infrastructure/workflowsteps/workflowsteps_test.go +++ b/internal/infrastructure/workflowsteps/workflowsteps_test.go @@ -22,13 +22,20 @@ func TestShippedVocabularyCoversEveryShippedStage(t *testing.T) { t.Fatalf("NewManager: %v", err) } - want := make([]string, 0, len(workflow.BuiltinStepRegistry())) + got := manager.StepTypes() + // Every shipped stage is present... for name := range workflow.BuiltinStepRegistry() { - want = append(want, name) + if !slices.Contains(got, name) { + t.Errorf("registered vocabulary %v is missing the shipped stage %q", got, name) + } } - slices.Sort(want) - if got := manager.StepTypes(); !slices.Equal(got, want) { - t.Fatalf("registered vocabulary = %v, want the shipped stages %v", got, want) + // ...and the vocabulary is exactly what the provider set declares. The + // expectation is derived from Providers() rather than from + // workflow.BuiltinStepRegistry(): adding a provider to this set is the + // documented way a step type arrives, and that must move both sides of this + // assertion together instead of having to edit it. + if want := declaredStepTypes(); !slices.Equal(got, want) { + t.Fatalf("registered vocabulary = %v, want the provider set's declared step types %v", got, want) } // The vocabulary arrives by registration, not by implication: a manager @@ -39,6 +46,19 @@ func TestShippedVocabularyCoversEveryShippedStage(t *testing.T) { } } +// declaredStepTypes returns every step type the provider set contributes, +// sorted, so a test can hold a manager to the set it was built from. +func declaredStepTypes() []string { + names := make([]string, 0) + for _, provider := range Providers() { + for _, stepType := range provider.StepTypes() { + names = append(names, stepType.Name) + } + } + slices.Sort(names) + return names +} + // TestShippedStagesKeepTheirBehaviourThroughTheManager pins that the provider // hands the builtin factories through unchanged. The shipped stages are typed, // non-interpreted steps: each compiles to the stage the builtin registry's own @@ -46,7 +66,8 @@ func TestShippedVocabularyCoversEveryShippedStage(t *testing.T) { // the same way -- and refuses settings. The one way this enumeration could keep // every name and lose that guard is to rebuild the factories instead of // forwarding them, and definition_test.go's assertion cannot see it -- that test -// drives BuiltinStepRegistry, which production no longer calls. +// drives BuiltinStepRegistry directly, which no resolution site does any more: +// production reaches it only inside the shipped provider below. func TestShippedStagesKeepTheirBehaviourThroughTheManager(t *testing.T) { t.Parallel()