diff --git a/internal/app/agentworker/step_vocabulary_test.go b/internal/app/agentworker/step_vocabulary_test.go new file mode 100644 index 000000000..30894a5cb --- /dev/null +++ b/internal/app/agentworker/step_vocabulary_test.go @@ -0,0 +1,61 @@ +package agentworker + +import ( + "slices" + "testing" + + "gopkg.in/yaml.v3" + + "github.com/samcharles93/archie-core/internal/domain/workflow" +) + +// stepVocabularyProbe is a provider set of one, used only to prove the +// manager a root builds is live: registering through it must reach its +// vocabulary. +type stepVocabularyProbe struct{} + +func (stepVocabularyProbe) Name() string { return "probe" } + +func (stepVocabularyProbe) StepTypes() []workflow.StepType { + return []workflow.StepType{{Name: "probe.registered", Factory: func(yaml.Node) (workflow.Stage, error) { + return workflow.Stage{Name: "probe.registered"}, nil + }}} +} + +// TestProductionWorkerDependenciesRegisterTheSharedStepVocabulary pins the +// executing side's composition root. productionWorkerDependencies is reached +// only by Run, so nothing else fails if it stops registering the shared +// provider set (internal/infrastructure/workflowsteps) and hands the worker a +// manager with no shipped stage: every compile then fails at run time, in a +// container, per task. +func TestProductionWorkerDependenciesRegisterTheSharedStepVocabulary(t *testing.T) { + dependencies, err := productionWorkerDependencies() + if err != nil { + t.Fatalf("productionWorkerDependencies: %v", err) + } + requireSharedStepVocabulary(t, dependencies.steps) +} + +// 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") + } + 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("the composition root 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 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") + } +} diff --git a/internal/app/agentworker/task_execution.go b/internal/app/agentworker/task_execution.go index 57098fe2f..8531d7e8e 100644 --- a/internal/app/agentworker/task_execution.go +++ b/internal/app/agentworker/task_execution.go @@ -327,6 +327,12 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen // onto req and req.Task: the run's TaskContext carries that task record, so the // pin has to land on the request the caller handed in. func CompilePinnedWorkflow(req *taskrun.Request, steps *workflow.Manager) (workflow.Workflow, error) { + // steps is this process's required step vocabulary, so a nil one is a wiring + // mistake at the composition root (productionWorkerDependencies) rather than + // a runtime condition: name it instead of dereferencing it. + if steps == nil { + return workflow.Workflow{}, errors.New("compile pinned workflow: no step vocabulary: the composition root must register the provider set (infrastructure/workflowsteps.NewManager) before the first compile") + } // One resolution for the whole function: both compiles below read the // vocabulary the composition root registered, never the builtin registry. vocabulary := steps.Registry() diff --git a/internal/app/agentworker/worker.go b/internal/app/agentworker/worker.go index 26bcaa779..5d279d8ad 100644 --- a/internal/app/agentworker/worker.go +++ b/internal/app/agentworker/worker.go @@ -64,6 +64,12 @@ type workerDependencies struct { steps *workflow.Manager } +// productionWorkerDependencies builds the worker's process dependencies. The +// workflow step vocabulary is registered here, at the executing side's +// composition root, before the first task is served: +// internal/app/agentworker's step_vocabulary_test.go calls this function and +// fails if it stops using the shared provider set +// (internal/infrastructure/workflowsteps). func productionWorkerDependencies() (workerDependencies, error) { steps, err := workflowsteps.NewManager() if err != nil { diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index 7c40b9cc8..a630caa34 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -54,7 +54,6 @@ import ( "github.com/samcharles93/archie-core/internal/infrastructure/skillcurator" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" "github.com/samcharles93/archie-core/internal/infrastructure/taskactions" - "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" "github.com/samcharles93/archie-core/internal/logging" "github.com/samcharles93/archie-core/internal/plugin" "github.com/samcharles93/archie-core/internal/plugin/pluginextract" @@ -117,6 +116,10 @@ type boot struct { stateStoreGrants *staterpc.GrantIssuer stateStoreToken string controlPlane *controlplane.Client + // 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. + workflowDefinitions *controlplane.WorkflowDefinitionsClient // executionSettings is the last workflow execution settings the control // plane published. They arrive on a watch rather than in the file // document, so reloadConfig re-applies them from here. @@ -359,15 +362,23 @@ func (b *boot) openStateStoreAdapter() error { } b.stateStore = client // The daemon reads and replaces workflow definitions through the - // control-plane client, so it resolves the same step vocabulary the State - // Store server validates against: registered here, at the composition - // root, before the first read. - steps, err := workflowsteps.NewManager() + // 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(), steps) + 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 + } 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) @@ -1252,7 +1263,7 @@ func (b *boot) buildDaemon() { AgentStatus: b.agentStatus, KindWorkflows: b.kindWorkflows, LabelWorkflows: b.labelWorkflows, - WorkflowDefinitions: b.controlPlane, + WorkflowDefinitions: b.workflowDefinitions, } if identities, ok := b.stateStore.(identity.Repository); ok { b.d.IdentityRepository = identities diff --git a/internal/app/archied/control_plane_reload_test.go b/internal/app/archied/control_plane_reload_test.go index d90785de5..348db1e66 100644 --- a/internal/app/archied/control_plane_reload_test.go +++ b/internal/app/archied/control_plane_reload_test.go @@ -14,20 +14,8 @@ import ( pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/infrastructure/configuration" - "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" ) -// reloadSteps builds the production workflow step vocabulary the reload tests' -// control-plane client resolves definitions against. -func reloadSteps(t *testing.T) *workflow.Manager { - t.Helper() - steps, err := workflowsteps.NewManager() - if err != nil { - t.Fatalf("build workflow step vocabulary: %v", err) - } - return steps -} - // controlPlaneStub answers Query from a fixed resource map. queryErr, when // set, fails every Query so a test can drive the unreachable-State-Store // path. @@ -99,7 +87,7 @@ func newReloadBoot(t *testing.T, stub *controlPlaneStub) *boot { b := &boot{ cfg: fileConfig(), log: slog.New(slog.DiscardHandler), - controlPlane: controlplane.NewRPCClient(stub, reloadSteps(t)), + controlPlane: controlplane.NewRPCClient(stub), } b.cfgHolder = config.NewHolder(b.cfg) return b diff --git a/internal/app/archied/state_store.go b/internal/app/archied/state_store.go index 34c79632e..d2a1da380 100644 --- a/internal/app/archied/state_store.go +++ b/internal/app/archied/state_store.go @@ -30,7 +30,6 @@ import ( "github.com/samcharles93/archie-core/internal/infrastructure/cronstore" "github.com/samcharles93/archie-core/internal/infrastructure/readiness" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" - "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" "github.com/samcharles93/archie-core/internal/store" ) @@ -101,16 +100,12 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error { if !ok { return fmt.Errorf("state store does not support control-plane resources") } - // The validating side's step vocabulary, registered here at the - // composition root before the first definition is read or replaced. The - // same provider set (internal/infrastructure/workflowsteps) is what - // archie-agent registers before it compiles one, so a definition this - // server admits is compilable there. - steps, err := workflowsteps.NewManager() + // The validating side's control plane, built here at the composition root + // before the first definition is read or replaced. + control, err := openStateStoreControlPlane(resources) if err != nil { - return fmt.Errorf("register workflow step vocabulary: %w", err) + return err } - control := controlplane.NewServer(resources, steps) versions, err := control.ImportConfig(ctx, b.cfg) if err != nil { return fmt.Errorf("import control-plane resources: %w", err) @@ -147,6 +142,29 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error { return serveStateStore(ctx, listener, deps, opts) } +// openStateStoreControlPlane builds the State Store's control plane server: the +// validating side of the workflow step vocabulary, registered here at the +// composition root before the first definition is read or replaced. The same +// provider set (internal/infrastructure/workflowsteps) is what archie-agent +// registers before it compiles one, so within one build a definition this +// server admits is compilable there; a skewed deploy is only fixed by a +// matching deploy. +// +// It is separate from RunStateStore so that function stays within its +// complexity budget, and step_vocabulary_test.go pins both the call to +// stepVocabulary below and RunStateStore's call to this function. +func openStateStoreControlPlane(resources controlplane.ResourceStore) (*controlplane.Server, error) { + steps, err := stepVocabulary() + if err != nil { + return nil, fmt.Errorf("register workflow step vocabulary: %w", err) + } + server, err := controlplane.NewServer(resources, steps) + if err != nil { + return nil, fmt.Errorf("build control plane server: %w", err) + } + return server, nil +} + func migrateLegacySchedules(ctx context.Context, control *controlplane.Server, dbPath string, version int64) error { if version != 1 { return nil diff --git a/internal/app/archied/step_vocabulary.go b/internal/app/archied/step_vocabulary.go new file mode 100644 index 000000000..a59c1ba7e --- /dev/null +++ b/internal/app/archied/step_vocabulary.go @@ -0,0 +1,24 @@ +package archied + +import ( + "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. +// +// 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. +// +// 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() } diff --git a/internal/app/archied/step_vocabulary_test.go b/internal/app/archied/step_vocabulary_test.go new file mode 100644 index 000000000..a1f63a085 --- /dev/null +++ b/internal/app/archied/step_vocabulary_test.go @@ -0,0 +1,98 @@ +package archied + +import ( + "go/ast" + "go/parser" + "go/token" + "slices" + "testing" + + "gopkg.in/yaml.v3" + + "github.com/samcharles93/archie-core/internal/domain/workflow" +) + +// stepVocabularyProbe is a provider set of one, used only to prove the manager +// a root builds is live: registering through it must reach its vocabulary. +type stepVocabularyProbe struct{} + +func (stepVocabularyProbe) Name() string { return "probe" } + +func (stepVocabularyProbe) StepTypes() []workflow.StepType { + return []workflow.StepType{{Name: "probe.registered", Factory: func(yaml.Node) (workflow.Stage, error) { + return workflow.Stage{Name: "probe.registered"}, nil + }}} +} + +// 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. +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") + } +} + +// 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. +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"}, + } { + 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) + } + 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) + } + }) + } +} + +// 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 { + position := token.NoPos + ast.Inspect(body, func(node ast.Node) bool { + call, ok := node.(*ast.CallExpr) + if !ok { + return true + } + ident, ok := call.Fun.(*ast.Ident) + if ok && ident.Name == name && position == token.NoPos { + position = call.Pos() + } + return true + }) + return position +} diff --git a/internal/app/archiemessaging/run.go b/internal/app/archiemessaging/run.go index 5cc3593f7..96e230a58 100644 --- a/internal/app/archiemessaging/run.go +++ b/internal/app/archiemessaging/run.go @@ -11,7 +11,6 @@ import ( "github.com/samcharles93/archie-core/internal/domain/messaging" "github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" - "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" "github.com/samcharles93/archie-core/internal/secret" ) @@ -31,13 +30,6 @@ func Run(ctx context.Context, o Options) error { defer closeGateway() health := newReadinessRegistry(cfg.Options, chat) - // The messaging process reads control-plane resources through the client, so - // it registers the workflow step vocabulary at its composition root, before - // the first resolution, like every other process that resolves one. - steps, err := workflowsteps.NewManager() - if err != nil { - return fmt.Errorf("register workflow step vocabulary: %w", err) - } var settings *messaging.SettingsCommand var closeStateStore func() if cfg.Options.StateStore.Target != "" { @@ -47,7 +39,7 @@ func Run(ctx context.Context, o Options) error { } closeStateStore = closeClient defer closeStateStore() - chatSettings, channelVersion, settingsErr := controlplane.NewRPCClient(stateStore.ControlPlane(), steps).RuntimeChatConfig(ctx, config.ChatConfig{ + chatSettings, channelVersion, settingsErr := controlplane.NewRPCClient(stateStore.ControlPlane()).RuntimeChatConfig(ctx, config.ChatConfig{ Telegram: cfg.Telegram, Email: cfg.Email, Webhook: cfg.Webhook, WebhookAddr: cfg.WebhookAddr, ShowToolCalls: cfg.ShowToolCalls, }) if settingsErr != nil { diff --git a/internal/app/controlplane/client.go b/internal/app/controlplane/client.go index 1a10e109c..de3583b1d 100644 --- a/internal/app/controlplane/client.go +++ b/internal/app/controlplane/client.go @@ -17,19 +17,36 @@ import ( "github.com/samcharles93/archie-core/internal/infrastructure/cronstore" ) -type Client struct { - rpc pb.ControlPlaneServiceClient - // steps is the step vocabulary this client validates and decodes workflow - // definitions against, resolved once by stepRegistry. +// 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 -- +// needs no provider set and cannot be failed by one. +type Client struct{ rpc pb.ControlPlaneServiceClient } + +func NewClient(conn grpc.ClientConnInterface) *Client { + return &Client{rpc: pb.NewControlPlaneServiceClient(conn)} +} + +func NewRPCClient(client pb.ControlPlaneServiceClient) *Client { return &Client{rpc: client} } + +// WorkflowDefinitionsClient reads and replaces the workflow-definitions +// resource, the one control-plane surface whose stored values name workflow +// step types. Resolving those names needs the step vocabulary the process +// registered at its composition root, so the vocabulary is a constructor +// dependency of this surface and of no other: a caller that cannot reach +// workflow definitions cannot ask for one. +type WorkflowDefinitionsClient struct { + rpc pb.ControlPlaneServiceClient steps workflow.StepRegistry } -func NewClient(conn grpc.ClientConnInterface, steps *workflow.Manager) *Client { - return &Client{rpc: pb.NewControlPlaneServiceClient(conn), steps: stepRegistry(steps)} -} - -func NewRPCClient(client pb.ControlPlaneServiceClient, steps *workflow.Manager) *Client { - return &Client{rpc: client, steps: stepRegistry(steps)} +func NewWorkflowDefinitionsClient(client pb.ControlPlaneServiceClient, steps *workflow.Manager) (*WorkflowDefinitionsClient, error) { + registry, err := stepRegistry(steps) + if err != nil { + return nil, err + } + return &WorkflowDefinitionsClient{rpc: client, steps: registry}, nil } func (c *Client) Catalog(ctx context.Context) ([]*pb.ResourceDescriptor, error) { @@ -40,7 +57,7 @@ func (c *Client) Catalog(ctx context.Context) ([]*pb.ResourceDescriptor, error) return response.Resources, nil } -func (c *Client) WorkflowDefinitions(ctx context.Context) (workflow.WorkflowDefinitionCollection, int64, error) { +func (c *WorkflowDefinitionsClient) WorkflowDefinitions(ctx context.Context) (workflow.WorkflowDefinitionCollection, int64, error) { response, err := c.rpc.Query(ctx, &pb.QueryRequest{Kind: WorkflowDefinitionsKind}) if err != nil { return workflow.WorkflowDefinitionCollection{}, 0, clientError(err) @@ -52,7 +69,7 @@ func (c *Client) WorkflowDefinitions(ctx context.Context) (workflow.WorkflowDefi // ReplaceWorkflowDefinitions replaces the collection. Passing // workflow.ShippedDefinitions() restores all shipped definitions while keeping // the previous override in resource history. -func (c *Client) ReplaceWorkflowDefinitions(ctx context.Context, definitions workflow.WorkflowDefinitionCollection, expectedVersion int64, actor, source, requestID string) (int64, error) { +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 { return 0, err diff --git a/internal/app/controlplane/controlplane.go b/internal/app/controlplane/controlplane.go index ac4650ea6..47a11ad89 100644 --- a/internal/app/controlplane/controlplane.go +++ b/internal/app/controlplane/controlplane.go @@ -44,15 +44,19 @@ type Server struct { // NewServer builds the control plane server the State Store serves. steps is // the workflow step vocabulary the composition root registered; this is the -// validating side of the vocabulary archie-agent executes against. -func NewServer(resources ResourceStore, steps *workflow.Manager) *Server { - registry := stepRegistry(steps) +// validating side of the vocabulary archie-agent executes against in a +// matching build (see stepRegistry: a skewed deploy can still disagree). +func NewServer(resources ResourceStore, steps *workflow.Manager) (*Server, error) { + registry, err := stepRegistry(steps) + if err != nil { + return nil, err + } definitions := builtinDefinitions(registry) byKind := make(map[string]Definition, len(definitions)) for _, definition := range definitions { byKind[definition.Kind] = definition } - return &Server{store: resources, definitions: byKind, ordered: definitions} + return &Server{store: resources, definitions: byKind, ordered: definitions}, nil } func (s *Server) Catalog(context.Context, *pb.CatalogRequest) (*pb.CatalogResponse, error) { diff --git a/internal/app/controlplane/controlplane_test.go b/internal/app/controlplane/controlplane_test.go index a74fcc3e6..499ce2c61 100644 --- a/internal/app/controlplane/controlplane_test.go +++ b/internal/app/controlplane/controlplane_test.go @@ -29,12 +29,24 @@ func testSteps(t *testing.T) *workflow.Manager { return steps } +// testServer builds the State Store's control plane against the production +// vocabulary, so a test that is not about the vocabulary still exercises the +// constructor production uses. +func testServer(t *testing.T, resources ResourceStore) *Server { + t.Helper() + server, err := NewServer(resources, testSteps(t)) + if err != nil { + t.Fatalf("build control plane server: %v", err) + } + return server +} + func TestCatalogCarriesShippedWorkflowDefinitionsForRestore(t *testing.T) { t.Parallel() resources := store.OpenTest(t) defer resources.Close() - catalog, err := NewServer(resources, testSteps(t)).Catalog(t.Context(), &pb.CatalogRequest{}) + catalog, err := testServer(t, resources).Catalog(t.Context(), &pb.CatalogRequest{}) if err != nil { t.Fatal(err) } @@ -61,7 +73,7 @@ func TestImportConfigSeedsWorkflowDefinitionsWithoutOverwritingOverride(t *testi resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources, testSteps(t)) + server := testServer(t, resources) if _, err := server.ImportConfig(t.Context(), config.Config{}); err != nil { t.Fatal(err) } @@ -101,7 +113,7 @@ func TestImportConfigSeedsPersonasWithoutOverwritingEdits(t *testing.T) { resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources, testSteps(t)) + server := testServer(t, resources) if _, err := server.ImportConfig(t.Context(), config.Config{}); err != nil { t.Fatal(err) } @@ -139,7 +151,7 @@ func TestImportWorkflowExecutionSettingsDoesNotOverwriteExistingValue(t *testing resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources, testSteps(t)) + server := testServer(t, resources) first := workflow.ExecutionSettings{MaxModelToolSteps: 10, MaxRuntime: time.Minute, MaxConsecutiveGateFailures: 2} if _, err := server.ImportWorkflowExecutionSettings(t.Context(), first); err != nil { t.Fatal(err) @@ -165,7 +177,7 @@ func TestRegistryRoutesAndValidatesDefinitions(t *testing.T) { resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources, testSteps(t)) + server := testServer(t, resources) if _, err := server.ImportConfig(t.Context(), config.Config{Containers: config.ContainerConfig{PullPolicy: "missing"}}); err != nil { t.Fatal(err) } @@ -195,7 +207,7 @@ func TestProviderSeedKeepsReferencesAndNeverResolvedSecrets(t *testing.T) { resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources, testSteps(t)) + server := testServer(t, resources) cfg := config.Config{Providers: map[string]config.Provider{"openai": {Class: "openai", APIKeyEnv: "OPENAI_API_KEY", APIKey: config.SecretRef{Engine: "env", Key: "OPENAI_API_KEY"}}}} if _, err := server.ImportConfig(context.Background(), cfg); err != nil { t.Fatal(err) @@ -222,7 +234,7 @@ func TestHistoryCarriesEveryRevisionWithItsAudit(t *testing.T) { resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources, testSteps(t)) + server := testServer(t, resources) if _, err := server.ImportConfig(t.Context(), config.Config{}); err != nil { t.Fatal(err) } diff --git a/internal/app/controlplane/runtime_config_test.go b/internal/app/controlplane/runtime_config_test.go index 4d55c50ce..ec4c4ab4f 100644 --- a/internal/app/controlplane/runtime_config_test.go +++ b/internal/app/controlplane/runtime_config_test.go @@ -53,7 +53,7 @@ func TestRuntimeConfigUsesDatabaseResourcesAndPreservesBootstrapOnlySecrets(t *t ToolSettingsKind: map[string]any{"mcp_servers": []map[string]any{{"name": "docs", "transport": "http", "url": "https://mcp.example.com", "headers_configured": true}}, "policy": map[string]any{}, "web_fetch": map[string]any{}, "minimax": map[string]any{"enabled": false, "credential_configured": false}}, PluginSettingsKind: map[string]any{"plugin_dir": "/plugins", "module_dir": "/modules", "secret_engine_dir": "/secrets", "skills_dir": "/skills"}, ContainerRuntimePoliciesKind: config.ContainerConfig{LegacyEnabled: true, Image: "archie:next", PullPolicy: "missing"}, - }}, testSteps(t)) + }}) got, versions, err := client.RuntimeConfig(t.Context(), base) if err != nil { diff --git a/internal/app/controlplane/step_vocabulary_agreement_test.go b/internal/app/controlplane/step_vocabulary_agreement_test.go index 3626821fe..d4a4d9ab5 100644 --- a/internal/app/controlplane/step_vocabulary_agreement_test.go +++ b/internal/app/controlplane/step_vocabulary_agreement_test.go @@ -121,13 +121,16 @@ func TestEveryProductionResolutionSiteResolvesTheRegisteredStepType(t *testing.T } }) - t.Run("control-plane client", func(t *testing.T) { + t.Run("workflow-definitions client", func(t *testing.T) { value, err := json.Marshal(probeCollection(test.stepType)) if err != nil { t.Fatalf("encode definitions: %v", err) } rpc := &definitionsClient{value: value} - client := NewRPCClient(rpc, steps) + client, err := NewWorkflowDefinitionsClient(rpc, steps) + if err != nil { + t.Fatalf("build workflow-definitions client: %v", err) + } // Read path: the daemon decodes the stored collection here. collection, _, readErr := client.WorkflowDefinitions(t.Context()) @@ -173,6 +176,30 @@ func TestEveryProductionResolutionSiteResolvesTheRegisteredStepType(t *testing.T } } +// TestNilStepVocabularyFailsClosedAtEveryResolutionSite pins the guard on the +// manager every resolution site now requires. A nil manager is a wiring bug at +// the composition root, so each site must name it and refuse to resolve, rather +// than dereference it: a nil-pointer panic is the same failure with no clue in +// it. +func TestNilStepVocabularyFailsClosedAtEveryResolutionSite(t *testing.T) { + resources := store.OpenTest(t) + t.Cleanup(func() { + if err := resources.Close(); err != nil { + t.Errorf("close test store: %v", err) + } + }) + + if _, err := NewServer(resources, nil); err == nil || !strings.Contains(err.Error(), "no workflow step vocabulary") { + t.Errorf("NewServer with no step vocabulary: error = %v, want the missing-vocabulary refusal", err) + } + if _, err := NewWorkflowDefinitionsClient(&definitionsClient{}, nil); err == nil || !strings.Contains(err.Error(), "no workflow step vocabulary") { + t.Errorf("NewWorkflowDefinitionsClient with no step vocabulary: error = %v, want the missing-vocabulary refusal", err) + } + if _, err := agentworker.CompilePinnedWorkflow(probeRequest(probeStepType), nil); err == nil || !strings.Contains(err.Error(), "no step vocabulary") { + t.Errorf("CompilePinnedWorkflow with no step vocabulary: error = %v, want the missing-vocabulary refusal", err) + } +} + // TestAgentWorkerCompilesShippedDefinitionsFromTheInjectedVocabulary pins the // shipped-definition route inside CompilePinnedWorkflow. That route compiles // definitions whose steps are all shipped stages, so no plugin assertion can @@ -226,7 +253,10 @@ func admitThroughStateStore(t *testing.T, steps *workflow.Manager, stepType stri t.Errorf("close test store: %v", closeErr) } }) - server := NewServer(resources, steps) + server, err := NewServer(resources, steps) + if err != nil { + t.Fatalf("build control plane server: %v", err) + } if resource, resourceErr := resources.Resource(t.Context(), WorkflowDefinitionsKind); resourceErr == nil { before = resource.Version diff --git a/internal/app/controlplane/workflow_definitions.go b/internal/app/controlplane/workflow_definitions.go index 7dd175363..72c5dae20 100644 --- a/internal/app/controlplane/workflow_definitions.go +++ b/internal/app/controlplane/workflow_definitions.go @@ -2,6 +2,7 @@ package controlplane import ( "encoding/json" + "errors" "fmt" "github.com/samcharles93/archie-core/internal/config" @@ -11,12 +12,20 @@ import ( const WorkflowDefinitionsKind = "workflow-definitions" // stepRegistry is this package's single resolution site for the workflow step -// vocabulary. The manager is built at the composition root -// (infrastructure/workflowsteps.NewManager) and injected, so the State Store -// server -- the validating side -- and the control-plane client both resolve -// the vocabulary that composition root registered, and neither can validate a -// definition against a vocabulary the other does not have. -func stepRegistry(steps *workflow.Manager) workflow.StepRegistry { return steps.Registry() } +// vocabulary, and the guard on the manager it must be handed. The manager is +// built at the composition root (infrastructure/workflowsteps.NewManager) and +// injected, so the State Store server -- the validating side -- and the +// workflow-definitions client both resolve the vocabulary that composition +// root registered. 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 stepRegistry(steps *workflow.Manager) (workflow.StepRegistry, error) { + if steps == nil { + return nil, errors.New("control plane: no workflow step vocabulary: the composition root must register the provider set (infrastructure/workflowsteps.NewManager) before the first resolution") + } + return steps.Registry(), nil +} func workflowDefinitionsDefinition(steps workflow.StepRegistry) Definition { return Definition{ diff --git a/internal/domain/workflow/vocabulary.go b/internal/domain/workflow/vocabulary.go index 4158b4c3d..ca401f44f 100644 --- a/internal/domain/workflow/vocabulary.go +++ b/internal/domain/workflow/vocabulary.go @@ -12,8 +12,10 @@ import ( // stepTypeIdentifier is the shape a provider name and a step type name must // have: a lowercase, dotted identifier, so a contributed step type cannot -// smuggle whitespace or case into the vocabulary both sides of the process -// boundary compare, and cannot be misread as a shipped stage. +// smuggle whitespace or case into the vocabulary two processes compare, and so +// one step type has exactly one spelling. It reserves nothing: a contribution +// that spells a shipped stage's name is well formed, and what refuses it is +// Register's claimed-name check, not this rule. var stepTypeIdentifier = regexp.MustCompile(`^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$`) // StepType is one named workflow step type: the vocabulary word a YAML @@ -40,15 +42,19 @@ type StepTypeProvider interface { // parsed and compiled against. // // It is a constructed, injected value. There is deliberately no package-level -// registry and no init()-time registration: both sides of the process boundary -// — the validating side (the State Store's control plane) and the executing -// side (archie-agent) — build a Manager at their composition root from the same -// provider set (internal/infrastructure/workflowsteps) and inject it, so a -// definition that validates on one side is compilable on the other by -// construction rather than by convention. +// registry and no init()-time registration: each process builds a Manager at +// its composition root from the same provider set +// (internal/infrastructure/workflowsteps) and injects it, so within one build +// a definition that validates on the validating side is compilable on the +// executing side. That agreement is per build: the State Store and archie-agent +// are separately deployed binaries, so one built from newer source than the +// other can still disagree, and only a matching deploy fixes that. // -// Registration happens before the first resolution: a Manager handed to a -// consumer is not registered to afterwards. +// Registration is expected to finish before the first resolution, and that +// order is a documented constraint rather than an enforced one: Registry hands +// back a copy, so a Register that arrives after a consumer resolved is not +// observed by that consumer. Register every provider before injecting the +// manager. type Manager struct { mu sync.Mutex registry StepRegistry diff --git a/internal/infrastructure/workflowsteps/workflowsteps.go b/internal/infrastructure/workflowsteps/workflowsteps.go index cebc55256..ed51d52d7 100644 --- a/internal/infrastructure/workflowsteps/workflowsteps.go +++ b/internal/infrastructure/workflowsteps/workflowsteps.go @@ -1,10 +1,13 @@ // Package workflowsteps is the compiled-in workflow step-type provider set: // the one place a step type is bundled into every Archie binary. // -// Both composition roots import it — internal/app/archied (which serves the -// State Store's validating side) and internal/app/agentworker (the executing -// side) — so the two sides register the same vocabulary by construction rather -// than by convention. Neither root keeps a package-level registry 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. package workflowsteps import ( @@ -38,9 +41,13 @@ func (shippedStages) StepTypes() []workflow.StepType { // 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 -// is a Go factory, and the Yaegi-interpreted plugins internal/plugin loads -// satisfy plugin.Plugin's metadata contract but cannot hand the host a working -// workflow.StepFactory. archie-agent links its own binary in any case. +// is a Go factory, and no bridge has been built from the Yaegi-interpreted +// plugins internal/plugin loads to workflow.StepFactory -- those plugins +// satisfy plugin.Plugin's metadata contract only. Such a bridge is possible: +// internal/secret/secretextract wraps an interpreted Engine into the typed +// contract secret.Registry.LoadDir registers (internal/app/archied/ +// provider_secrets.go). Until one exists for step types, adding a step type +// means adding a provider here. func Providers() []workflow.StepTypeProvider { return []workflow.StepTypeProvider{shippedStages{}} } diff --git a/internal/infrastructure/workflowsteps/workflowsteps_test.go b/internal/infrastructure/workflowsteps/workflowsteps_test.go index a9fc1fe7e..33657931c 100644 --- a/internal/infrastructure/workflowsteps/workflowsteps_test.go +++ b/internal/infrastructure/workflowsteps/workflowsteps_test.go @@ -5,6 +5,8 @@ import ( "strings" "testing" + "gopkg.in/yaml.v3" + "github.com/samcharles93/archie-core/internal/domain/workflow" ) @@ -39,11 +41,12 @@ func TestShippedVocabularyCoversEveryShippedStage(t *testing.T) { // 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 -// carries 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. +// non-interpreted steps: each compiles to the stage the builtin registry's own +// factory builds for that step type -- the same name, and Run present or absent +// 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. func TestShippedStagesKeepTheirBehaviourThroughTheManager(t *testing.T) { t.Parallel() @@ -66,9 +69,19 @@ func TestShippedStagesKeepTheirBehaviourThroughTheManager(t *testing.T) { t.Fatalf("%s compiled %d stages, want %d", entry.ID, len(compiled.Stages), len(definition.Steps)) } for i, step := range definition.Steps { - want := strings.TrimPrefix(step.Type, entry.ID+".") - if compiled.Stages[i].Name != want { - t.Errorf("%s step %d (%s) compiled to stage %q, want the shipped stage %q: the registered factory is not the builtin one", entry.ID, i, step.Type, compiled.Stages[i].Name, want) + // The expectation is the stage the builtin registry's own factory + // builds for this step type, not a name derived from the step type: + // that is what "the registered factory is the builtin one" means + // for a Stage, which is a name plus an uncomparable func. + shipped, err := workflow.BuiltinStepRegistry()[step.Type](yaml.Node{}) + if err != nil { + t.Fatalf("build shipped stage %s: %v", step.Type, err) + } + if compiled.Stages[i].Name != shipped.Name { + t.Errorf("%s step %d (%s) compiled to stage %q, want the shipped stage %q: the registered factory is not the builtin one", entry.ID, i, step.Type, compiled.Stages[i].Name, shipped.Name) + } + if (compiled.Stages[i].Run != nil) != (shipped.Run != nil) { + t.Errorf("%s step %d (%s) compiled to a stage whose Run is present=%t, want the shipped stage's present=%t", entry.ID, i, step.Type, compiled.Stages[i].Run != nil, shipped.Run != nil) } } }