Files
archie/internal/domain/workflow/vocabulary.go
T
sam 9fb65d0519 fix(workflow): pin the roots, drop the dead vocabulary, guard the nil manager
Third review pass on the step-vocabulary shape, one fix per finding.

P1, roots unpinned. The agreement test built its own manager and injected it, so
it pinned the resolution sites and not the roots that decide the provider set; a
root regressed to workflow.NewManager() (no shipped stages) left go test green.
archied now resolves through one unit, stepVocabulary (step_vocabulary.go), and
agentworker's productionWorkerDependencies is exercised directly:
internal/app/agentworker/step_vocabulary_test.go and
internal/app/archied/step_vocabulary_test.go assert each root's manager resolves
the shared provider set's shipped stages and accepts a provider registered
through it. RunStateStore and openStateStoreAdapter own a SQLite file and a gRPC
dial, so their calls are pinned by source position, the way
composition_order_test.go pins the memory-engine ordering.

P2-B, dead vocabulary. archie-messaging registered a step vocabulary it never
resolved (its only control-plane call is RuntimeChatConfig) and could fail
startup on it before the State Store target guard. The workflow-definitions
surface is now its own type, controlplane.WorkflowDefinitionsClient, so the
vocabulary is a constructor dependency of the one surface that resolves step
types and of nothing else. The messaging root no longer imports workflowsteps.

P2-C, nil manager. A nil *workflow.Manager dereferenced on every resolution path.
stepRegistry and CompilePinnedWorkflow now refuse with an error naming the wiring
mistake; TestNilStepVocabularyFailsClosedAtEveryResolutionSite pins the refusal.

Claim-vs-code corrections: agreement is stated as within one build (vocabulary.go,
stepRegistry, openStateStoreControlPlane, openStateStoreAdapter); the Yaegi claim
now says no bridge to StepFactory has been built and cites
internal/secret/secretextract; the provider set names its three roots;
Manager.Register's ordering is documented as a constraint with its consequence,
and the shape rule no longer claims to reserve shipped stage names; the
shipped-stage test compares against the builtin factory's own stage.
2026-09-21 20:00:37 +10:00

169 lines
6.5 KiB
Go

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 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
// 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: 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 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
// 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
}