diff --git a/internal/app/agentworker/task_execution.go b/internal/app/agentworker/task_execution.go index d65cbee77..57098fe2f 100644 --- a/internal/app/agentworker/task_execution.go +++ b/internal/app/agentworker/task_execution.go @@ -176,6 +176,11 @@ type taskDependencies struct { store workflow.Store trees remoteTrees events agentexec.EventPublisher + // steps is the workflow step vocabulary pinned definitions are compiled + // against, registered at the composition root and injected: this is the + // executing half of the contract whose validating half is the control + // plane's (archie-core-fwmp). + steps *workflow.Manager } type runnerFactory func(map[string]agentexec.Provider, *slog.Logger) agentexec.Runner @@ -212,7 +217,7 @@ func routeTask(req taskrun.Request, registry workflow.Registry) workflow.Workflo // runs it, and reports its terminal outcome. // Store remains archied's authority; Response.Task is a logging snapshot. func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependencies, newRunner runnerFactory, workDir string, log *slog.Logger) (*taskrun.Response, error) { - wf, err := resolvePinnedWorkflow(&req) + wf, err := CompilePinnedWorkflow(&req, dependencies.steps) if err != nil { return nil, err } @@ -311,18 +316,31 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen }, nil } -func resolvePinnedWorkflow(req *taskrun.Request) (workflow.Workflow, error) { +// CompilePinnedWorkflow resolves and compiles the immutable definition the task +// request carries, against this process's step vocabulary. Production execution +// and the workflow step-vocabulary contract test +// (internal/app/controlplane/step_vocabulary_agreement_test.go) both enter +// through it. +// +// A request that carries no definition is routed and pinned from the shipped +// definitions, which writes the resolved workflow name, YAML, and digest back +// 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) { + // One resolution for the whole function: both compiles below read the + // vocabulary the composition root registered, never the builtin registry. + vocabulary := steps.Registry() if req.WorkflowDefinition == "" { shipped := workflow.ShippedDefinitions() - registry := make(workflow.Registry, len(shipped.Definitions)) + routing := make(workflow.Registry, len(shipped.Definitions)) for _, definition := range shipped.Definitions { - compiled, compileErr := workflow.ParseAndCompile(definition.YAML, workflow.BuiltinStepRegistry()) + compiled, compileErr := workflow.ParseAndCompile(definition.YAML, vocabulary) if compileErr != nil { return workflow.Workflow{}, fmt.Errorf("compile shipped workflow definition: %w", compileErr) } - registry[definition.ID] = compiled + routing[definition.ID] = compiled } - selected := routeTask(*req, registry) + selected := routeTask(*req, routing) req.Task.Workflow = selected.Name entry, ok := shipped.DefinitionByID(selected.Name) if !ok { @@ -332,7 +350,7 @@ func resolvePinnedWorkflow(req *taskrun.Request) (workflow.Workflow, error) { req.Task.WorkflowDefinitionYAML = entry.YAML req.Task.WorkflowDefinitionDigest = workflow.DigestDefinition(entry.YAML) } - wf, err := workflow.ParseAndCompile(req.WorkflowDefinition, workflow.BuiltinStepRegistry()) + wf, err := workflow.ParseAndCompile(req.WorkflowDefinition, vocabulary) if err != nil { return workflow.Workflow{}, fmt.Errorf("compile pinned workflow definition: %w", err) } diff --git a/internal/app/agentworker/task_execution_test.go b/internal/app/agentworker/task_execution_test.go index 5b0eb7d95..d8f9d3eb8 100644 --- a/internal/app/agentworker/task_execution_test.go +++ b/internal/app/agentworker/task_execution_test.go @@ -31,6 +31,7 @@ import ( "github.com/samcharles93/archie-core/internal/forgerpc" agentnats "github.com/samcharles93/archie-core/internal/infrastructure/agenttransport/nats" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" + "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" "github.com/samcharles93/archie-core/internal/installtype" "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskrun" @@ -38,6 +39,18 @@ import ( "github.com/samcharles93/archie-core/internal/worktreerpc" ) +// testSteps builds the production workflow step vocabulary for tests that are +// not about the vocabulary itself (the composition-level agreement test in +// internal/app/controlplane is). +func testSteps(t *testing.T) *workflow.Manager { + t.Helper() + steps, err := workflowsteps.NewManager() + if err != nil { + t.Fatalf("build workflow step vocabulary: %v", err) + } + return steps +} + // ── regression: archie-core#520 -- worktree ownership must be // reconciled before push, since the agent commits as root inside the // container and the daemon reads those same loose objects as its own @@ -399,7 +412,7 @@ func TestRunTaskExecutesBootstrapWorkflowEndToEnd(t *testing.T) { Cfg: config.Config{BotUser: "archie-bot", BotEmail: "archie-bot@example.com"}.ForTask(), } fakeRunner := runnerFactory(func(map[string]agentexec.Provider, *slog.Logger) agentexec.Runner { return panicRunner{t} }) - response, err := runTask(ctx, req, taskDependencies{forge: fg, store: st, trees: remote}, fakeRunner, hostDir, slog.New(slog.DiscardHandler)) + response, err := runTask(ctx, req, taskDependencies{forge: fg, store: st, trees: remote, steps: testSteps(t)}, fakeRunner, hostDir, slog.New(slog.DiscardHandler)) if err != nil { t.Fatalf("runTask: %v", err) } @@ -531,7 +544,7 @@ func TestRunTaskRestoresWorktreeOwnershipOnEveryExit(t *testing.T) { _, err := runTask(t.Context(), taskrun.Request{ Task: &workflow.Task{ID: 77, Branch: "feat/77-probe", Workflow: "implement"}, Repo: config.Repo{Owner: "acme", Name: "widget", Base: "main"}, - }, taskDependencies{}, runnerFactory(func(map[string]agentexec.Provider, *slog.Logger) agentexec.Runner { + }, taskDependencies{steps: testSteps(t)}, runnerFactory(func(map[string]agentexec.Provider, *slog.Logger) agentexec.Runner { return nil }), workDir, slog.New(slog.DiscardHandler)) if err == nil { @@ -632,7 +645,7 @@ func TestExecuteTaskRequestUsesInfrastructureRPCDependencies(t *testing.T) { Cfg: config.Config{}.ForTask(), WorktreeGrant: grant, } - response, err := executeTaskRequest(ctx, request, transport, hostDir, slog.New(slog.DiscardHandler)) + response, err := executeTaskRequest(ctx, request, transport, hostDir, slog.New(slog.DiscardHandler), testSteps(t)) if err != nil { t.Fatal(err) } @@ -750,7 +763,7 @@ func TestExecuteTaskRequestForwardsWorkflowEventsOverNATS(t *testing.T) { Cfg: config.Config{}.ForTask(), WorktreeGrant: grant, } - response, err := executeTaskRequest(ctx, request, transport, hostDir, slog.New(slog.DiscardHandler)) + response, err := executeTaskRequest(ctx, request, transport, hostDir, slog.New(slog.DiscardHandler), testSteps(t)) if err != nil { t.Fatal(err) } diff --git a/internal/app/agentworker/worker.go b/internal/app/agentworker/worker.go index 341651c01..26bcaa779 100644 --- a/internal/app/agentworker/worker.go +++ b/internal/app/agentworker/worker.go @@ -11,6 +11,7 @@ import ( "github.com/samcharles93/archie-core/internal/infrastructure/agentboot" "github.com/samcharles93/archie-core/internal/infrastructure/agentgit" agentnats "github.com/samcharles93/archie-core/internal/infrastructure/agenttransport/nats" + "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" "github.com/samcharles93/archie-core/internal/storage" "github.com/samcharles93/archie-core/internal/taskrun" ) @@ -57,9 +58,17 @@ type workerDependencies struct { markSafe func(context.Context, string, *slog.Logger) bool bootID func(string) (int64, error) wait func(context.Context, *slog.Logger) + // steps is the workflow step vocabulary this process compiles pinned + // definitions against, registered by the composition root before the first + // task is served (infrastructure/workflowsteps is the provider set). + steps *workflow.Manager } -func productionWorkerDependencies() workerDependencies { +func productionWorkerDependencies() (workerDependencies, error) { + steps, err := workflowsteps.NewManager() + if err != nil { + return workerDependencies{}, err + } return workerDependencies{ connect: func(ctx context.Context, config agentnats.Config, log *slog.Logger) (workerTransport, error) { return agentnats.Connect(ctx, config, log) @@ -70,13 +79,18 @@ func productionWorkerDependencies() workerDependencies { <-ctx.Done() log.Info("archie-agent shutting down") }, - } + steps: steps, + }, nil } // Run starts the worker, serves full-task requests, and returns after ctx // cancellation or a startup failure. func Run(ctx context.Context, settings Settings, log *slog.Logger) error { - return run(ctx, settings, log, productionWorkerDependencies()) + dependencies, err := productionWorkerDependencies() + if err != nil { + return &StartupError{Operation: "register workflow step vocabulary", Err: err} + } + return run(ctx, settings, log, dependencies) } func run(ctx context.Context, settings Settings, log *slog.Logger, dependencies workerDependencies) error { @@ -112,7 +126,7 @@ func run(ctx context.Context, settings Settings, log *slog.Logger, dependencies log.Info("system log publisher attached", "task", taskID) subscription, err := transport.SubscribeTasks(ctx, taskID, func(ctx context.Context, request taskrun.Request) (*taskrun.Response, error) { - return executeTaskRequest(ctx, request, transport, workDir, log) + return executeTaskRequest(ctx, request, transport, workDir, log, dependencies.steps) }, log) if err != nil { log.Error("taskrun subscribe failed", "err", err) @@ -136,13 +150,14 @@ type taskServiceTransport interface { EventPublisher() agentexec.EventPublisher } -func executeTaskRequest(ctx context.Context, request taskrun.Request, transport taskServiceTransport, workDir string, log *slog.Logger) (*taskrun.Response, error) { +func executeTaskRequest(ctx context.Context, request taskrun.Request, transport taskServiceTransport, workDir string, log *slog.Logger, steps *workflow.Manager) (*taskrun.Response, error) { log.Info("running task", "task", request.Task.ID, "repo", request.Repo.FullName(), "issue", request.Task.IssueNumber) dependencies := taskDependencies{ forge: transport.Forger(request.Task.Identity, rpcTimeout), store: transport.Store(rpcTimeout), trees: transport.Trees(request.Task.Identity, request.WorktreeGrant, rpcTimeout), events: transport.EventPublisher(), + steps: steps, } response, err := runTask(ctx, request, dependencies, newTaskRunner, workDir, log) if err != nil { diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index 78923a510..7c40b9cc8 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -54,6 +54,7 @@ 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" @@ -357,7 +358,16 @@ func (b *boot) openStateStoreAdapter() error { return err } b.stateStore = client - b.controlPlane = controlplane.NewRPCClient(client.ControlPlane()) + // 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() + if err != nil { + b.log.Error("register workflow step vocabulary", "err", err) + return err + } + b.controlPlane = controlplane.NewRPCClient(client.ControlPlane(), steps) 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/control_plane_reload_test.go b/internal/app/archied/control_plane_reload_test.go index 348db1e66..d90785de5 100644 --- a/internal/app/archied/control_plane_reload_test.go +++ b/internal/app/archied/control_plane_reload_test.go @@ -14,8 +14,20 @@ 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. @@ -87,7 +99,7 @@ func newReloadBoot(t *testing.T, stub *controlPlaneStub) *boot { b := &boot{ cfg: fileConfig(), log: slog.New(slog.DiscardHandler), - controlPlane: controlplane.NewRPCClient(stub), + controlPlane: controlplane.NewRPCClient(stub, reloadSteps(t)), } 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 f59a26b6e..34c79632e 100644 --- a/internal/app/archied/state_store.go +++ b/internal/app/archied/state_store.go @@ -30,6 +30,7 @@ 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" ) @@ -100,7 +101,16 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error { if !ok { return fmt.Errorf("state store does not support control-plane resources") } - control := controlplane.NewServer(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() + if err != nil { + return fmt.Errorf("register workflow step vocabulary: %w", 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) diff --git a/internal/app/archiemessaging/run.go b/internal/app/archiemessaging/run.go index 96e230a58..5cc3593f7 100644 --- a/internal/app/archiemessaging/run.go +++ b/internal/app/archiemessaging/run.go @@ -11,6 +11,7 @@ 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" ) @@ -30,6 +31,13 @@ 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 != "" { @@ -39,7 +47,7 @@ func Run(ctx context.Context, o Options) error { } closeStateStore = closeClient defer closeStateStore() - chatSettings, channelVersion, settingsErr := controlplane.NewRPCClient(stateStore.ControlPlane()).RuntimeChatConfig(ctx, config.ChatConfig{ + chatSettings, channelVersion, settingsErr := controlplane.NewRPCClient(stateStore.ControlPlane(), steps).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 d08e5e2c7..1a10e109c 100644 --- a/internal/app/controlplane/client.go +++ b/internal/app/controlplane/client.go @@ -17,13 +17,20 @@ import ( "github.com/samcharles93/archie-core/internal/infrastructure/cronstore" ) -type Client struct{ rpc pb.ControlPlaneServiceClient } - -func NewClient(conn grpc.ClientConnInterface) *Client { - return &Client{rpc: pb.NewControlPlaneServiceClient(conn)} +type Client struct { + rpc pb.ControlPlaneServiceClient + // steps is the step vocabulary this client validates and decodes workflow + // definitions against, resolved once by stepRegistry. + steps workflow.StepRegistry } -func NewRPCClient(client pb.ControlPlaneServiceClient) *Client { return &Client{rpc: client} } +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 (c *Client) Catalog(ctx context.Context) ([]*pb.ResourceDescriptor, error) { response, err := c.rpc.Catalog(ctx, &pb.CatalogRequest{}) @@ -38,7 +45,7 @@ func (c *Client) WorkflowDefinitions(ctx context.Context) (workflow.WorkflowDefi if err != nil { return workflow.WorkflowDefinitionCollection{}, 0, clientError(err) } - definitions, err := workflow.DecodeDefinitionCollection(response.Resource.ValueJson, workflow.BuiltinStepRegistry()) + definitions, err := workflow.DecodeDefinitionCollection(response.Resource.ValueJson, c.steps) return definitions, response.Resource.Version, err } @@ -46,7 +53,7 @@ func (c *Client) WorkflowDefinitions(ctx context.Context) (workflow.WorkflowDefi // 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) { - value, err := encodeWorkflowDefinitions(definitions) + 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 e3d487788..ac4650ea6 100644 --- a/internal/app/controlplane/controlplane.go +++ b/internal/app/controlplane/controlplane.go @@ -11,6 +11,7 @@ import ( "google.golang.org/protobuf/types/known/timestamppb" pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" + "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/store" ) @@ -41,8 +42,12 @@ type Server struct { ordered []Definition } -func NewServer(resources ResourceStore) *Server { - definitions := builtinDefinitions() +// 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) + definitions := builtinDefinitions(registry) byKind := make(map[string]Definition, len(definitions)) for _, definition := range definitions { byKind[definition.Kind] = definition diff --git a/internal/app/controlplane/controlplane_test.go b/internal/app/controlplane/controlplane_test.go index fd3dd59a6..a74fcc3e6 100644 --- a/internal/app/controlplane/controlplane_test.go +++ b/internal/app/controlplane/controlplane_test.go @@ -13,15 +13,28 @@ import ( pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" "github.com/samcharles93/archie-core/internal/domain/agent" "github.com/samcharles93/archie-core/internal/domain/workflow" + "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" "github.com/samcharles93/archie-core/internal/store" ) +// testSteps builds the production workflow step vocabulary for tests that are +// not about the vocabulary itself; step_vocabulary_agreement_test.go is the one +// that registers a provider and drives every production resolution site. +func testSteps(t *testing.T) *workflow.Manager { + t.Helper() + steps, err := workflowsteps.NewManager() + if err != nil { + t.Fatalf("build workflow step vocabulary: %v", err) + } + return steps +} + func TestCatalogCarriesShippedWorkflowDefinitionsForRestore(t *testing.T) { t.Parallel() resources := store.OpenTest(t) defer resources.Close() - catalog, err := NewServer(resources).Catalog(t.Context(), &pb.CatalogRequest{}) + catalog, err := NewServer(resources, testSteps(t)).Catalog(t.Context(), &pb.CatalogRequest{}) if err != nil { t.Fatal(err) } @@ -48,7 +61,7 @@ func TestImportConfigSeedsWorkflowDefinitionsWithoutOverwritingOverride(t *testi resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources) + server := NewServer(resources, testSteps(t)) if _, err := server.ImportConfig(t.Context(), config.Config{}); err != nil { t.Fatal(err) } @@ -64,7 +77,7 @@ func TestImportConfigSeedsWorkflowDefinitionsWithoutOverwritingOverride(t *testi t.Fatal("seeded definitions omit remediate") } custom := workflow.WorkflowDefinitionCollection{Definitions: []workflow.WorkflowDefinitionEntry{{ID: "custom", YAML: "id: custom\nsteps:\n - type: bootstrap.apply\n"}}} - value, err := encodeWorkflowDefinitions(custom) + value, err := encodeWorkflowDefinitions(custom, testSteps(t).Registry()) if err != nil { t.Fatal(err) } @@ -88,7 +101,7 @@ func TestImportConfigSeedsPersonasWithoutOverwritingEdits(t *testing.T) { resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources) + server := NewServer(resources, testSteps(t)) if _, err := server.ImportConfig(t.Context(), config.Config{}); err != nil { t.Fatal(err) } @@ -126,7 +139,7 @@ func TestImportWorkflowExecutionSettingsDoesNotOverwriteExistingValue(t *testing resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources) + server := NewServer(resources, testSteps(t)) first := workflow.ExecutionSettings{MaxModelToolSteps: 10, MaxRuntime: time.Minute, MaxConsecutiveGateFailures: 2} if _, err := server.ImportWorkflowExecutionSettings(t.Context(), first); err != nil { t.Fatal(err) @@ -152,7 +165,7 @@ func TestRegistryRoutesAndValidatesDefinitions(t *testing.T) { resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources) + server := NewServer(resources, testSteps(t)) if _, err := server.ImportConfig(t.Context(), config.Config{Containers: config.ContainerConfig{PullPolicy: "missing"}}); err != nil { t.Fatal(err) } @@ -182,7 +195,7 @@ func TestProviderSeedKeepsReferencesAndNeverResolvedSecrets(t *testing.T) { resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources) + server := NewServer(resources, testSteps(t)) 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) @@ -209,7 +222,7 @@ func TestHistoryCarriesEveryRevisionWithItsAudit(t *testing.T) { resources := store.OpenTest(t) defer resources.Close() - server := NewServer(resources) + server := NewServer(resources, testSteps(t)) if _, err := server.ImportConfig(t.Context(), config.Config{}); err != nil { t.Fatal(err) } diff --git a/internal/app/controlplane/definitions.go b/internal/app/controlplane/definitions.go index 59e390b0c..a02921ca0 100644 --- a/internal/app/controlplane/definitions.go +++ b/internal/app/controlplane/definitions.go @@ -1,14 +1,17 @@ package controlplane -import pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" +import ( + pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" + "github.com/samcharles93/archie-core/internal/domain/workflow" +) const ( objectSchema = `{"type":"object"}` arraySchema = `{"type":"array"}` ) -func builtinDefinitions() []Definition { - definitions := []Definition{workflowDefinition(), workflowDefinitionsDefinition(), personaDefinition(), scheduleDefinition()} +func builtinDefinitions(steps workflow.StepRegistry) []Definition { + definitions := []Definition{workflowDefinition(), workflowDefinitionsDefinition(steps), personaDefinition(), scheduleDefinition()} definitions = append(definitions, modelDefinitions()...) definitions = append(definitions, operationalDefinitions()...) return definitions diff --git a/internal/app/controlplane/runtime_config_test.go b/internal/app/controlplane/runtime_config_test.go index ec4c4ab4f..4d55c50ce 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 new file mode 100644 index 000000000..3626821fe --- /dev/null +++ b/internal/app/controlplane/step_vocabulary_agreement_test.go @@ -0,0 +1,291 @@ +// The workflow step vocabulary is a contract between processes: the validating +// side (the State Store's control plane) admits a definition and the executing +// 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. +// +// "Agreement" here means within one build: archie-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. This file cannot reach across a deploy boundary and does +// not claim to. +package controlplane + +import ( + "context" + "encoding/json" + "strings" + "testing" + + "google.golang.org/grpc" + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" + "gopkg.in/yaml.v3" + + "github.com/samcharles93/archie-core/internal/app/agentworker" + 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/workflowsteps" + "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/taskrun" +) + +const ( + probeWorkflow = "probe" + // probeStepType is contributed by the provider this test registers through + // the production Manager, so no shared registry can hand it to one side and + // not the others. + probeStepType = "probe.registered" + // unregisteredStepType is declared by no provider, so every side must + // refuse it. + unregisteredStepType = "probe.unregistered" +) + +// probeProvider is a plugin set of one: a step type no shipped workflow +// registers, whose stage names itself so a side that merely failed to error +// cannot pass. +type probeProvider struct{} + +func (probeProvider) Name() string { return "probe" } + +func (probeProvider) StepTypes() []workflow.StepType { + return []workflow.StepType{{Name: probeStepType, Factory: func(yaml.Node) (workflow.Stage, error) { + return workflow.Stage{Name: probeStepType}, nil + }}} +} + +// probeSteps builds the process vocabulary the way a composition root does — +// through the production constructor — and registers the probe provider on top +// of it. +func probeSteps(t *testing.T) *workflow.Manager { + t.Helper() + steps, err := workflowsteps.NewManager() + if err != nil { + t.Fatalf("build workflow step vocabulary: %v", err) + } + if err := steps.Register(probeProvider{}); err != nil { + t.Fatalf("register the probe provider through the production Manager: %v", err) + } + return steps +} + +func probeDefinition(stepType string) string { + return "id: " + probeWorkflow + "\nsteps:\n - type: " + stepType + "\n" +} + +func probeCollection(stepType string) workflow.WorkflowDefinitionCollection { + return workflow.WorkflowDefinitionCollection{ + Definitions: []workflow.WorkflowDefinitionEntry{{ID: probeWorkflow, YAML: probeDefinition(stepType)}}, + } +} + +// TestEveryProductionResolutionSiteResolvesTheRegisteredStepType drives the +// State Store server, the control-plane client's read and write paths, and +// archie-agent with one vocabulary: a site that resolves the builtin registry +// instead of the manager fails its own assertion, because the probe step type +// exists nowhere else. +func TestEveryProductionResolutionSiteResolvesTheRegisteredStepType(t *testing.T) { + tests := []struct { + name string + stepType string + admitted bool + // wantStage is the stage a definition must compile to. It is empty for + // a shipped stage, whose factory keeps the workflow-local stage name. + wantStage string + }{ + {name: "step type registered through the manager", stepType: probeStepType, admitted: true, wantStage: probeStepType}, + {name: "shipped stage", stepType: "bootstrap.apply", admitted: true}, + {name: "step type no provider declares", stepType: unregisteredStepType}, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + steps := probeSteps(t) + + // Every side asserts against the same expectation, so a side that + // resolves a vocabulary other than the registered one fails its own + // subtest. That shared column is the agreement this file pins. + t.Run("state store server", func(t *testing.T) { + before, after, err := admitThroughStateStore(t, steps, test.stepType) + if !test.admitted { + if code := status.Code(err); code != codes.InvalidArgument { + t.Fatalf("State Store answered %v (code %s), want InvalidArgument: a refused definition is a validation failure, not a store failure", err, code) + } + requireRefusal(t, "the State Store server", test.stepType, err) + return + } + requireAdmission(t, "the State Store server", test.stepType, err) + if after != before+1 { + t.Errorf("store version moved %d -> %d, want exactly one write: a repeated request ID is replayed idempotently and would make this admission vacuous", before, after) + } + }) + + t.Run("control-plane 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) + + // Read path: the daemon decodes the stored collection here. + collection, _, readErr := client.WorkflowDefinitions(t.Context()) + // Write path: the client re-validates before it sends anything. + _, writeErr := client.ReplaceWorkflowDefinitions(t.Context(), probeCollection(test.stepType), 4, "test", "test", "replace:"+test.stepType) + + if !test.admitted { + requireRefusal(t, "the control-plane client read", test.stepType, readErr) + requireRefusal(t, "the control-plane client write", test.stepType, writeErr) + if rpc.command != nil { + t.Errorf("the client sent %q for a step type it does not resolve", rpc.command.ValueJson) + } + return + } + requireAdmission(t, "the control-plane client read", test.stepType, readErr) + if _, ok := collection.DefinitionByID(probeWorkflow); !ok { + t.Errorf("client read %#v, want the stored %q definition", collection.Definitions, probeWorkflow) + } + requireAdmission(t, "the control-plane client write", test.stepType, writeErr) + if rpc.command == nil { + t.Fatal("the client accepted the collection without sending a command") + } + if !strings.Contains(string(rpc.command.ValueJson), test.stepType) { + t.Errorf("the client sent %q, which does not carry step type %q", rpc.command.ValueJson, test.stepType) + } + }) + + t.Run("archie-agent", func(t *testing.T) { + compiled, err := agentworker.CompilePinnedWorkflow(probeRequest(test.stepType), steps) + if !test.admitted { + requireRefusal(t, "archie-agent", test.stepType, err) + return + } + requireAdmission(t, "archie-agent", test.stepType, err) + if compiled.Name != probeWorkflow || len(compiled.Stages) != 1 { + t.Fatalf("compiled workflow = %+v, want the single-stage %q definition", compiled, probeWorkflow) + } + if test.wantStage != "" && compiled.Stages[0].Name != test.wantStage { + t.Errorf("compiled stage = %q, want the provider's own stage %q", compiled.Stages[0].Name, test.wantStage) + } + }) + }) + } +} + +// TestAgentWorkerCompilesShippedDefinitionsFromTheInjectedVocabulary pins the +// shipped-definition route inside CompilePinnedWorkflow. That route compiles +// definitions whose steps are all shipped stages, so no plugin assertion can +// reach it; a vocabulary that carries the probe step type and nothing else must +// fail there, and it cannot fail if the route reaches for the builtin registry +// instead of the manager the composition root registered. +func TestAgentWorkerCompilesShippedDefinitionsFromTheInjectedVocabulary(t *testing.T) { + steps := workflow.NewManager() + if err := steps.Register(probeProvider{}); err != nil { + t.Fatalf("register the probe provider through the production Manager: %v", err) + } + + _, err := agentworker.CompilePinnedWorkflow(&taskrun.Request{Task: &workflow.Task{ID: 1}}, steps) + if err == nil { + t.Fatal("the shipped-definition route compiled against a vocabulary carrying no shipped stage") + } + if !strings.Contains(err.Error(), "compile shipped workflow definition") || !strings.Contains(err.Error(), "bootstrap.") { + t.Errorf("error = %v, want the shipped stage the injected vocabulary could not resolve", err) + } +} + +func requireAdmission(t *testing.T, side, stepType string, err error) { + t.Helper() + if err != nil { + t.Fatalf("%s refused step type %q: %v", side, stepType, err) + } +} + +// requireRefusal checks the error is a refusal *of this step type*: a store +// outage, a transport failure or an unrelated compile error must not be able to +// stand in for one. +func requireRefusal(t *testing.T, side, stepType string, err error) { + t.Helper() + if err == nil { + t.Fatalf("%s accepted step type %q, which no provider declares", side, stepType) + } + if !strings.Contains(err.Error(), stepType) { + t.Errorf("%s failed for %q with %v, which does not name the step type: that is not a refusal of it", side, stepType, err) + } +} + +// admitThroughStateStore writes one definition the way an operator does: a +// replace command against the workflow-definitions resource of a server built +// by the production constructor. +func admitThroughStateStore(t *testing.T, steps *workflow.Manager, stepType string) (before, after int64, err error) { + t.Helper() + + resources := store.OpenTest(t) + t.Cleanup(func() { + if closeErr := resources.Close(); closeErr != nil { + t.Errorf("close test store: %v", closeErr) + } + }) + server := NewServer(resources, steps) + + if resource, resourceErr := resources.Resource(t.Context(), WorkflowDefinitionsKind); resourceErr == nil { + before = resource.Version + } + value, err := json.Marshal(probeCollection(stepType)) + if err != nil { + t.Fatalf("encode definitions: %v", err) + } + written, err := server.Command(t.Context(), &pb.CommandRequest{ + Kind: WorkflowDefinitionsKind, Command: "replace", ValueJson: value, + ExpectedVersion: before, Actor: "test", Source: "test", + // A request ID per step type: the store replays a repeated one + // idempotently, and a replayed write would validate nothing. + RequestId: "admit:" + stepType, + }) + if err != nil { + return before, before, err + } + return before, written.Resource.Version, nil +} + +func probeRequest(stepType string) *taskrun.Request { + definition := probeDefinition(stepType) + return &taskrun.Request{ + Task: &workflow.Task{ + ID: 1, + Workflow: probeWorkflow, + WorkflowDefinitionDigest: workflow.DigestDefinition(definition), + }, + WorkflowDefinition: definition, + } +} + +// definitionsClient answers the control-plane RPCs the definitions client uses, +// so the production client path is driven without a live State Store. +type definitionsClient struct { + value []byte + command *pb.CommandRequest +} + +func (c *definitionsClient) Catalog(context.Context, *pb.CatalogRequest, ...grpc.CallOption) (*pb.CatalogResponse, error) { + panic("Catalog is not part of the workflow-definitions path") +} + +func (c *definitionsClient) Query(context.Context, *pb.QueryRequest, ...grpc.CallOption) (*pb.QueryResponse, error) { + return &pb.QueryResponse{Resource: &pb.Resource{ + Kind: WorkflowDefinitionsKind, Version: 4, ValueJson: c.value, + }}, nil +} + +func (c *definitionsClient) History(context.Context, *pb.HistoryRequest, ...grpc.CallOption) (*pb.HistoryResponse, error) { + panic("History is not part of the workflow-definitions path") +} + +func (c *definitionsClient) Command(_ context.Context, request *pb.CommandRequest, _ ...grpc.CallOption) (*pb.CommandResponse, error) { + c.command = request + return &pb.CommandResponse{Resource: &pb.Resource{Version: 5}}, nil +} + +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") +} diff --git a/internal/app/controlplane/workflow_definitions.go b/internal/app/controlplane/workflow_definitions.go index c4283b435..7dd175363 100644 --- a/internal/app/controlplane/workflow_definitions.go +++ b/internal/app/controlplane/workflow_definitions.go @@ -10,7 +10,15 @@ import ( const WorkflowDefinitionsKind = "workflow-definitions" -func workflowDefinitionsDefinition() Definition { +// 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() } + +func workflowDefinitionsDefinition(steps workflow.StepRegistry) Definition { return Definition{ Kind: WorkflowDefinitionsKind, Title: "Workflow definitions", @@ -23,14 +31,14 @@ func workflowDefinitionsDefinition() Definition { return workflow.ShippedDefinitions() }, Validate: func(input []byte) error { - _, err := workflow.DecodeDefinitionCollection(input, workflow.BuiltinStepRegistry()) + _, err := workflow.DecodeDefinitionCollection(input, steps) return err }, } } -func encodeWorkflowDefinitions(collection workflow.WorkflowDefinitionCollection) ([]byte, error) { - if err := workflow.ValidateDefinitionCollection(collection, workflow.BuiltinStepRegistry()); err != nil { +func encodeWorkflowDefinitions(collection workflow.WorkflowDefinitionCollection, steps workflow.StepRegistry) ([]byte, error) { + if err := workflow.ValidateDefinitionCollection(collection, steps); err != nil { return nil, fmt.Errorf("%w: %w", ErrValidation, err) } return json.Marshal(collection) diff --git a/internal/domain/workflow/vocabulary.go b/internal/domain/workflow/vocabulary.go new file mode 100644 index 000000000..4158b4c3d --- /dev/null +++ b/internal/domain/workflow/vocabulary.go @@ -0,0 +1,162 @@ +package workflow + +import ( + "errors" + "fmt" + "maps" + "reflect" + "regexp" + "slices" + "sync" +) + +// 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. +var stepTypeIdentifier = regexp.MustCompile(`^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$`) + +// StepType is one named workflow step type: the vocabulary word a YAML +// workflow names, plus the factory that builds its stage. +type StepType struct { + Name string + Factory StepFactory +} + +// StepTypeProvider is the typed extension point through which a plugin +// contributes workflow step types. StepTypes is the capability-specific +// operation — a provider exposing identity metadata alone would be a metadata +// entry, not a step-type provider — and it is the only method the family calls. +type StepTypeProvider interface { + // Name identifies the provider in registration diagnostics. + Name() string + // StepTypes returns every step type this provider contributes. The + // manager validates the whole contribution before applying any of it. + StepTypes() []StepType +} + +// Manager is the workflow step-type family owner: it controls registration, +// validation, and resolution of the vocabulary that workflow definitions are +// 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. +// +// Registration happens before the first resolution: a Manager handed to a +// consumer is not registered to afterwards. +type Manager struct { + mu sync.Mutex + registry StepRegistry + // owners names the provider that claimed each step type, so a collision is + // reported against the provider that is already there rather than as an + // anonymous duplicate. The stages of the shipped workflows are claimed by + // the provider that contributes them, which is how a contribution that + // shadows a shipped stage is refused. + owners map[string]string + providers []string +} + +// NewManager builds an empty family manager. It holds no vocabulary of its own: +// the shipped stages are a provider like any other, registered by the process's +// composition root, so the vocabulary every side resolves is the one that was +// actually registered. +func NewManager() *Manager { + return &Manager{registry: StepRegistry{}, owners: map[string]string{}} +} + +// Register validates one provider's contribution and applies it. Every way a +// contribution can be invalid is refused here, at the producer: a nil or +// unnamed provider, a malformed provider or step-type identifier, a step type +// with no factory, a step type another provider already claimed (including one +// that shadows a shipped stage), and a provider declaring one type twice. +// +// Validation is atomic: the whole contribution is checked before any of it is +// applied, so a refused provider contributes nothing. +func (m *Manager) Register(provider StepTypeProvider) error { + if isNilProvider(provider) { + return errors.New("workflow step type provider is nil") + } + name := provider.Name() + if !stepTypeIdentifier.MatchString(name) { + return fmt.Errorf("workflow step type provider name %q is not a stable identifier", name) + } + + contributed := provider.StepTypes() + pending := make(StepRegistry, len(contributed)) + order := make([]string, 0, len(contributed)) + for _, stepType := range contributed { + switch { + case !stepTypeIdentifier.MatchString(stepType.Name): + return fmt.Errorf("workflow step type provider %q: step type %q is not a stable identifier", name, stepType.Name) + case stepType.Factory == nil: + return fmt.Errorf("workflow step type provider %q: step type %q has no factory", name, stepType.Name) + } + if _, declared := pending[stepType.Name]; declared { + return fmt.Errorf("workflow step type provider %q declares step type %q twice", name, stepType.Name) + } + pending[stepType.Name] = stepType.Factory + order = append(order, stepType.Name) + } + + m.mu.Lock() + defer m.mu.Unlock() + for _, stepType := range order { + if owner, claimed := m.owners[stepType]; claimed { + return fmt.Errorf("workflow step type %q is already claimed by provider %q", stepType, owner) + } + } + for _, stepType := range order { + m.registry[stepType] = pending[stepType] + m.owners[stepType] = name + } + m.providers = append(m.providers, name) + return nil +} + +// Registry returns the assembled vocabulary for the parser and compiler entry +// points. It is a copy: the closed set is a property of the manager, not +// something a consumer can widen. +func (m *Manager) Registry() StepRegistry { + m.mu.Lock() + defer m.mu.Unlock() + registry := make(StepRegistry, len(m.registry)) + maps.Copy(registry, m.registry) + return registry +} + +// StepTypes returns every registered step type name, sorted. +func (m *Manager) StepTypes() []string { + registry := m.Registry() + names := make([]string, 0, len(registry)) + for name := range registry { + names = append(names, name) + } + slices.Sort(names) + return names +} + +// Providers returns the registered provider names, sorted. +func (m *Manager) Providers() []string { + m.mu.Lock() + defer m.mu.Unlock() + return slices.Sorted(slices.Values(m.providers)) +} + +// isNilProvider catches a nil interface and a typed nil pointer alike: a +// provider cannot answer Name() in either case, so it is refused rather than +// dereferenced. Mirrors internal/domain/memory's engine check. +func isNilProvider(provider StepTypeProvider) bool { + value := reflect.ValueOf(provider) + switch value.Kind() { + case reflect.Invalid: + return true + case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice: + return value.IsNil() + } + return false +} diff --git a/internal/domain/workflow/vocabulary_test.go b/internal/domain/workflow/vocabulary_test.go new file mode 100644 index 000000000..6efbc7187 --- /dev/null +++ b/internal/domain/workflow/vocabulary_test.go @@ -0,0 +1,217 @@ +package workflow + +import ( + "slices" + "strings" + "testing" + + "gopkg.in/yaml.v3" +) + +// namedFactory builds a stage that names itself, so a test can tell which step +// type a definition compiled from. +func namedFactory(name string) StepFactory { + return func(yaml.Node) (Stage, error) { return Stage{Name: name}, nil } +} + +// testProvider is a provider set of one, for driving the manager directly. +type testProvider struct { + name string + types []StepType +} + +func (p testProvider) Name() string { return p.name } + +func (p testProvider) StepTypes() []StepType { return p.types } + +func provider(name string, names ...string) testProvider { + types := make([]StepType, 0, len(names)) + for _, stepType := range names { + types = append(types, StepType{Name: stepType, Factory: namedFactory(stepType)}) + } + return testProvider{name: name, types: types} +} + +// shippedProvider is the provider that contributes the stages of the shipped +// workflows, which is where a bundled step type arrives from in production. +func shippedProvider() testProvider { + registry := BuiltinStepRegistry() + names := make([]string, 0, len(registry)) + for name := range registry { + names = append(names, name) + } + return provider("shipped", names...) +} + +// TestManagerRefusesInvalidContributions is the family's validation contract: +// every way a contribution can be wrong is refused at registration, and a +// refused contribution applies nothing. +func TestManagerRefusesInvalidContributions(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + before []StepTypeProvider + provider StepTypeProvider + want string + }{ + { + name: "nil provider", + want: "is nil", + }, + { + name: "unnamed provider", + provider: provider(""), + want: "not a stable identifier", + }, + { + name: "malformed provider name", + provider: provider("Probe Plugin", "probe.one"), + want: "not a stable identifier", + }, + { + name: "malformed step type name", + provider: provider("probe", "Probe One"), + want: "not a stable identifier", + }, + { + name: "step type with no factory", + provider: testProvider{name: "probe", types: []StepType{{Name: "probe.one"}}}, + want: "has no factory", + }, + { + name: "provider declaring one type twice", + provider: testProvider{name: "probe", types: []StepType{ + {Name: "probe.one", Factory: namedFactory("probe.one")}, + {Name: "probe.one", Factory: namedFactory("probe.one")}, + }}, + want: "twice", + }, + { + name: "duplicate claim", + before: []StepTypeProvider{provider("alpha", "alpha.one")}, + provider: provider("beta", "alpha.one"), + want: `already claimed by provider "alpha"`, + }, + { + name: "shadows a shipped stage", + before: []StepTypeProvider{shippedProvider()}, + provider: provider("probe", "bootstrap.apply"), + want: `already claimed by provider "shipped"`, + }, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + t.Parallel() + + manager := NewManager() + for _, before := range test.before { + if err := manager.Register(before); err != nil { + t.Fatalf("setup registration: %v", err) + } + } + before := manager.StepTypes() + + err := manager.Register(test.provider) + if err == nil || !strings.Contains(err.Error(), test.want) { + t.Fatalf("Register() error = %v, want containing %q", err, test.want) + } + if after := manager.StepTypes(); !slices.Equal(after, before) { + t.Errorf("a refused contribution changed the vocabulary: %v -> %v", before, after) + } + }) + } +} + +// TestManagerRefusalAppliesNoneOfAMultiStepContribution pins atomicity: a +// contribution whose first step type is valid and whose second is not leaves +// the vocabulary untouched. +func TestManagerRefusalAppliesNoneOfAMultiStepContribution(t *testing.T) { + t.Parallel() + + manager := NewManager() + err := manager.Register(testProvider{name: "probe", types: []StepType{ + {Name: "probe.one", Factory: namedFactory("probe.one")}, + {Name: "probe.two"}, + }}) + if err == nil || !strings.Contains(err.Error(), "has no factory") { + t.Fatalf("Register() error = %v, want containing %q", err, "has no factory") + } + if got := manager.StepTypes(); len(got) != 0 { + t.Errorf("vocabulary = %v, want empty: a refused contribution applies nothing", got) + } + if _, resolved := manager.Registry()["probe.one"]; resolved { + t.Error("the valid half of a refused contribution was applied") + } +} + +// TestManagerAssemblesTheRegisteredVocabulary is the family's resolution +// contract: what was registered is exactly what workflows can name. +func TestManagerAssemblesTheRegisteredVocabulary(t *testing.T) { + t.Parallel() + + manager := NewManager() + for _, contributor := range []StepTypeProvider{ + provider("beta", "beta.one", "beta.two"), + shippedProvider(), + provider("alpha", "alpha.one"), + } { + if err := manager.Register(contributor); err != nil { + t.Fatalf("Register(%s): %v", contributor.Name(), err) + } + } + + got := manager.StepTypes() + want := make([]string, 0, len(BuiltinStepRegistry())+3) + for name := range BuiltinStepRegistry() { + want = append(want, name) + } + want = append(want, "alpha.one", "beta.one", "beta.two") + slices.Sort(want) + if !slices.Equal(got, want) { + t.Errorf("StepTypes() = %v, want %v", got, want) + } + + if providers := manager.Providers(); !slices.Equal(providers, []string{"alpha", "beta", "shipped"}) { + t.Errorf("Providers() = %v, want [alpha beta shipped]", providers) + } + + compiled, err := ParseAndCompile("id: probe\nsteps:\n - type: alpha.one\n - type: beta.two\n", manager.Registry()) + if err != nil { + t.Fatalf("compile a definition naming contributed step types: %v", err) + } + if compiled.Name != "probe" || len(compiled.Stages) != 2 { + t.Fatalf("compiled = %+v, want the two-stage probe workflow", compiled) + } + if compiled.Stages[0].Name != "alpha.one" || compiled.Stages[1].Name != "beta.two" { + t.Errorf("compiled stages = %q, %q, want the contributing factories' stages", + compiled.Stages[0].Name, compiled.Stages[1].Name) + } + + if _, err := ParseAndCompile("id: probe\nsteps:\n - type: unregistered\n", manager.Registry()); err == nil { + t.Error("a step type no provider contributed compiled") + } +} + +// TestManagerRegistryIsAClosedSet pins that the assembled vocabulary is a +// property of the manager, not a map a consumer can widen. +func TestManagerRegistryIsAClosedSet(t *testing.T) { + t.Parallel() + + manager := NewManager() + if err := manager.Register(provider("alpha", "alpha.one")); err != nil { + t.Fatalf("Register: %v", err) + } + + registry := manager.Registry() + registry["smuggled"] = namedFactory("smuggled") + delete(registry, "alpha.one") + + if _, ok := manager.Registry()["smuggled"]; ok { + t.Error("a consumer's write reached the manager's vocabulary") + } + if _, ok := manager.Registry()["alpha.one"]; !ok { + t.Error("a consumer's delete removed a registered step type") + } +} diff --git a/internal/infrastructure/workflowsteps/workflowsteps.go b/internal/infrastructure/workflowsteps/workflowsteps.go new file mode 100644 index 000000000..cebc55256 --- /dev/null +++ b/internal/infrastructure/workflowsteps/workflowsteps.go @@ -0,0 +1,61 @@ +// 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. +package workflowsteps + +import ( + "fmt" + "maps" + "slices" + + "github.com/samcharles93/archie-core/internal/domain/workflow" +) + +// shippedStages is the provider that contributes every stage of the shipped +// workflows (bootstrap, implement, tdd, feasibility, triage, remediate) as a +// workflow step type. It is what makes the shipped vocabulary arrive by +// registration rather than by the manager implying it, so the vocabulary a +// process resolves is always the vocabulary a provider set claimed. +type shippedStages struct{} + +func (shippedStages) Name() string { return "shipped" } + +func (shippedStages) StepTypes() []workflow.StepType { + registry := workflow.BuiltinStepRegistry() + stepTypes := make([]workflow.StepType, 0, len(registry)) + for _, name := range slices.Sorted(maps.Keys(registry)) { + stepTypes = append(stepTypes, workflow.StepType{Name: name, Factory: registry[name]}) + } + 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 +// 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. +func Providers() []workflow.StepTypeProvider { + return []workflow.StepTypeProvider{shippedStages{}} +} + +// NewManager builds this process's workflow step-type manager by registering +// the provider set. Every call constructs an independent manager: there is no +// package-level registry and nothing registers at init(), so building the +// vocabulary twice in one process — as `-count=2` does — cannot collide with +// the first build. +func NewManager() (*workflow.Manager, error) { + manager := workflow.NewManager() + for _, provider := range Providers() { + if err := manager.Register(provider); err != nil { + return nil, fmt.Errorf("register workflow step type provider %q: %w", provider.Name(), err) + } + } + return manager, nil +} diff --git a/internal/infrastructure/workflowsteps/workflowsteps_test.go b/internal/infrastructure/workflowsteps/workflowsteps_test.go new file mode 100644 index 000000000..f80da9889 --- /dev/null +++ b/internal/infrastructure/workflowsteps/workflowsteps_test.go @@ -0,0 +1,60 @@ +package workflowsteps + +import ( + "slices" + "testing" + + "github.com/samcharles93/archie-core/internal/domain/workflow" +) + +// TestShippedVocabularyCoversEveryShippedStage is the guard that the bundled +// provider set really carries the shipped stages: a process that registers it +// can compile every shipped workflow, and one that does not has no vocabulary +// at all. +func TestShippedVocabularyCoversEveryShippedStage(t *testing.T) { + t.Parallel() + + manager, err := NewManager() + if err != nil { + t.Fatalf("NewManager: %v", err) + } + + want := make([]string, 0, len(workflow.BuiltinStepRegistry())) + for name := range workflow.BuiltinStepRegistry() { + want = append(want, name) + } + slices.Sort(want) + if got := manager.StepTypes(); !slices.Equal(got, want) { + t.Fatalf("registered vocabulary = %v, want the shipped stages %v", got, want) + } + + // The vocabulary arrives by registration, not by implication: a manager + // that was handed no provider set resolves nothing, which is what makes + // every resolution site's use of the injected manager observable. + if got := workflow.NewManager().StepTypes(); len(got) != 0 { + t.Fatalf("an unregistered manager resolves %v, want nothing", got) + } +} + +// TestNewManagerIsRepeatableWithinOneProcess is the regression guard for +// registering the provider set into shared state: every construction is +// independent, so building the vocabulary twice in one process — as `-count=2` +// does — must succeed and produce the same vocabulary. +func TestNewManagerIsRepeatableWithinOneProcess(t *testing.T) { + t.Parallel() + + first, err := NewManager() + if err != nil { + t.Fatalf("first NewManager: %v", err) + } + second, err := NewManager() + if err != nil { + t.Fatalf("second NewManager: %v", err) + } + if !slices.Equal(first.StepTypes(), second.StepTypes()) { + t.Fatalf("two managers resolved different vocabularies: %v and %v", first.StepTypes(), second.StepTypes()) + } + if !slices.Equal(first.Providers(), second.Providers()) { + t.Fatalf("two managers registered different providers: %v and %v", first.Providers(), second.Providers()) + } +}