diff --git a/internal/app/archieui/auth.go b/internal/app/archieui/auth.go index a09f9f53a..930cb0402 100644 --- a/internal/app/archieui/auth.go +++ b/internal/app/archieui/auth.go @@ -10,18 +10,8 @@ import ( "github.com/samcharles93/archie-core/internal/infrastructure/oidc" ) -// dashboardAuthenticator builds the dashboard's credential check from the -// endpoint references the process was given, or returns nil when none were. -// -// It is built here rather than in the command because cmd/ parses flags and -// nothing else, and it takes two URLs rather than a configuration struct because -// this process is deliberately kept unaware of the config file's shape -- see the -// note above Options. Issuer and audience are exactly the endpoint references -// Options already carries for the Gateway and the State Store. -// -// A nil result means no provider is configured, and the shared token stays the -// gate: an instance that never configured one keeps working, and its requests are -// recorded unattributed rather than credited to a human. +// dashboardAuthenticator builds the OIDC credential check, or nil when no +// provider is configured. func dashboardAuthenticator(ctx context.Context, opts Options, subjects identity.SubjectResolver, log *slog.Logger) (func(context.Context, string) (identity.Identity, error), error) { if strings.TrimSpace(opts.OidcIssuer) == "" { return nil, nil @@ -41,13 +31,8 @@ func dashboardAuthenticator(ctx context.Context, opts Options, subjects identity }, nil } -// dashboardLoginFlow builds the browser sign-in flow from endpoint references and -// the operator's registration, or returns nil when none is configured. -// -// The secret is read from the environment variable the operator named and never -// logged, printed or stored. A client id is optional: an instance that only -// accepts agent tokens configures none, and then there is simply no sign-in -// route -- token verification is unaffected. +// dashboardLoginFlow builds the browser sign-in flow, or nil when not +// configured. The client secret is read from the named env var. func dashboardLoginFlow(ctx context.Context, opts Options) (identity.LoginFlow, error) { if strings.TrimSpace(opts.OidcIssuer) == "" || strings.TrimSpace(opts.OidcClientID) == "" { return nil, nil diff --git a/internal/app/archieui/compose.go b/internal/app/archieui/compose.go index 6ce9c696c..dc1f81a62 100644 --- a/internal/app/archieui/compose.go +++ b/internal/app/archieui/compose.go @@ -42,11 +42,8 @@ type deps struct { Denials access.DenialStore } -// compose builds the dashboard server for the UI process from contract-backed -// dependencies only. Fields left at zero are daemon-local handles; their -// handlers answer 501/503 or empty. Config writes stay with the daemon. Task -// logs are read through the State Store, and this process is the only listener -// for POST /webhooks/capture/{source}. +// compose builds the dashboard server from contract-backed dependencies. +// Unset fields answer 501/503 or empty. func compose(d deps) *webui.Server { srv := &webui.Server{ Store: d.Store, @@ -84,12 +81,8 @@ func compose(d deps) *webui.Server { if bindings, ok := d.Store.(storecontract.BindingStore); ok { srv.Bindings = bindings } - // Harness OAuth token sets are a ratified State Store contract, and the - // same client already carries them. Withholding it would leave the - // harness page answering 503 on a deployment that has the store. - // The setup terminal itself is not wired here: its - // implementation owns a container, which this process must not link, so - // the route stays a documented 503 until a daemon-side contract exists. + // Harness token status comes from the State Store; the setup terminal is not + // available here. if secrets, ok := d.Store.(storecontract.HarnessSecretStore); ok { srv.HarnessSecrets = secrets } @@ -99,12 +92,7 @@ func compose(d deps) *webui.Server { if d.Chat != nil { srv.Chat = &webui.ChatService{Contract: d.Chat} } - // The task-log read crosses the State Store contract: the files live in - // the state directory that process owns, so this one asks for the log - // rather than opening a path. Withholding - // it would degrade a page that has an owner, and would leave the dashboard - // claiming task logging was not enabled -- see wireTaskLogs. - // The policy chain: wired together or not at all + // The policy chain: wired together or not at all. srv.Access = d.Access srv.Principals = d.Principals srv.Denials = d.Denials @@ -128,12 +116,8 @@ func wireTaskLogs(d deps, srv *webui.Server) { srv.TaskLogs = logs } -// wireCaptureSurfaces attaches the capture read, the source editor and the -// intake receiver. All resolve from d.Store's contracts: CaptureStore backs -// the inspector's list and the mapping preview's scan window, SourceStore -// resolves the source whose signing setting verifies an event. A store that -// does not implement one degrades that half with a warning rather than -// aborting the process, mirroring the daemon's own adapter selection. +// wireCaptureSurfaces attaches capture listing, source editing and intake. A +// store missing a contract degrades that part with a warning. func wireCaptureSurfaces(d deps, srv *webui.Server) { captures, hasCaptures := d.Store.(storecontract.CaptureStore) sources, hasSources := d.Store.(storecontract.SourceStore) @@ -164,12 +148,8 @@ func wireCaptureSurfaces(d deps, srv *webui.Server) { } } -// captureArrivalPublisher persists a capture's arrival event through the -// State Store, where the daemon's bus drain persists every other activity -// event; the event pump then delivers it to every connected browser. A nil -// store records captures without announcing them (compose's test-only -// shape); an insert failure is logged, not surfaced -- the capture row is -// already durable, and the inspector refetches on its next view. +// captureArrivalPublisher persists a capture's arrival event. Failures are +// logged. func captureArrivalPublisher(d deps) func(context.Context, events.Event) { if d.Store == nil { return nil diff --git a/internal/app/archieui/config.go b/internal/app/archieui/config.go index a8dde99d9..0792fbf3b 100644 --- a/internal/app/archieui/config.go +++ b/internal/app/archieui/config.go @@ -12,18 +12,8 @@ import ( "github.com/samcharles93/archie-core/internal/webui" ) -// Resolve produces the effective Options: flag values win, and a field the -// operator left empty falls back to the configuration file's projection, then -// to a process default. It ends with validate, so a caller that gets no error -// holds a startable configuration. -// -// The projection is an allowlist of the values this process needs -- -// [services.gateway].{target,target_token}, [services.state].{target, -// target_token}, [web].{listen,trust_forwarded_headers} and [capture]. The UI -// reads the same file the daemon does because operators already keep the -// service endpoints there, but Options has no field for anything else in it: -// the daemon's forge credentials, model catalog, workflow routing, NATS -// settings, filesystem jail and agent/container settings have nowhere to land +// Resolve returns the effective Options: flags first, then the config file's +// projection, then defaults, and validates the result. func Resolve(o Options, log *slog.Logger) (Options, error) { if o.Config != "" { cfg, found, err := readProjection(o.Config, o.Overlay, log) @@ -87,24 +77,7 @@ func project(cfg config.Config) projection { } } -// withEnvTokens fills a service token the operator gave neither on the command -// line nor in [services.*].target_token. The config loader does not expand -// environment variables, and config.example.toml documents the environment as -// how a remote consumer presents these tokens, so without this a deployment -// that supplies them by env dials with an empty bearer and staterpc.Dial -// refuses a non-loopback start. -// -// It runs here rather than inside project() because the process is fully -// drivable by flags: readProjection returns early when there is no config -// file, so a fallback living in the file's projection would miss exactly the -// flags-only deployment that needs it. -// -// This reads the process environment only. The daemon resolves the same names -// through a secret.Registry, which also consults bws and any Yaegi-loaded -// engine; the UI process deliberately does not compose that runtime, because -// ui-service-boundary.md's deletion gate forbids a secret runtime package -// here. A token held in a secret manager must therefore be exported into -// archie-ui's environment by whatever starts it. +// withEnvTokens fills service tokens left unset from the environment. func withEnvTokens(o Options) Options { if o.Gateway.Token == "" { o.Gateway.Token = os.Getenv("GATEWAY_TOKEN") @@ -155,14 +128,7 @@ func merge(o Options, p projection) Options { } func withDefaults(o Options) Options { - // This is the one config key the UI and the daemon read with opposite - // meanings: in the daemon, Web.Listen = "off" disables the dashboard - // (config.Config "off" is a sentinel, not an address). In a dedicated UI - // process there is no sense disabling the only thing it does, so "off" - // falls through to the default listener. None of the other projected - // values is overloaded this way; if "off" ever means something else here - // it must be pinned with a test, because it is exactly where an operator - // preparing the split would set it. + // "off" disables the daemon's dashboard but means the default listener here. if o.Listen == "" || o.Listen == "off" { o.Listen = defaultListen } diff --git a/internal/app/archieui/options.go b/internal/app/archieui/options.go index c811326fa..43761f3ed 100644 --- a/internal/app/archieui/options.go +++ b/internal/app/archieui/options.go @@ -1,14 +1,5 @@ -// Package archieui composes the standalone UI Service: the operator-facing -// HTTP surface and the compiled SPA, served against a Gateway and a State -// Store running in other processes. -// -// The two rules that shape this package are that the UI owns only process-local -// settings ("HTTP listen address and read/header/shutdown timeouts; UI asset -// source or build mode; UI authentication mode and token reference; Gateway -// endpoint and credential reference; State Store endpoint and credential -// reference; readiness endpoint and dependency timeout policy"), and that it -// "must never implement [configuration] policy by holding or mutating a shared -// config.Holder". +// Package archieui composes the standalone dashboard service, talking to the +// Gateway and State Store over their contracts. package archieui import ( @@ -55,18 +46,12 @@ type Options struct { // use. It is the explicit opt-in to a non-loopback listener: without it // a reachable bind must be given a token. TokenFile string - // OidcIssuer and OidcAudience are endpoint references for the identity - // provider, not configuration. The issuer is read for its discovery document - // and signing keys, and the audience is the resource identifier this process - // accepts credentials for. Both empty leaves the shared-token gate in place; - // an issuer with no audience is refused rather than accepted without the check. + // OidcIssuer and OidcAudience configure the identity provider. Both empty + // keeps the shared token; an issuer without an audience is refused. OidcIssuer string OidcAudience string - // OidcClientID and OidcClientSecretEnv are the provider registration for the - // browser sign-in. The secret itself is never a flag: the flag names the - // environment variable holding it, so it cannot reach a process listing or a - // log line. No client id means no sign-in flow, which is what an instance - // that only accepts agent tokens wants. + // OidcClientID and OidcClientSecretEnv register the browser sign-in; the + // secret is read from the named env var. No client ID disables sign-in. OidcClientID string OidcClientSecretEnv string // OidcRedirectURL is the callback the provider returns the browser to. Its @@ -77,15 +62,8 @@ type Options struct { // operator did not say, and the file (else false) decides. TrustForwardedHeaders *bool - // Capture configures the unbound webhook capture receiver this process - // mounts on its bypass mux. At the - // cutover this process is the only listener - // serving POST /webhooks/capture/{source}: the receiver persists what - // arrives through the State Store contract, and the daemon's - // binding-dispatch loop consumes captures from the same store, so the - // HTTP front door moves without moving the owner of work intake. Zero - // fields fall back to configuration.DefaultCapture, the same defaults a - // decoded config would carry. + // Capture configures the webhook capture receiver. Zero fields use + // configuration.DefaultCapture. Capture CaptureOptions // Gateway and State are the two remote contracts the dashboard consumes. diff --git a/internal/app/archieui/readiness.go b/internal/app/archieui/readiness.go index fc82b3f78..e2355e9eb 100644 --- a/internal/app/archieui/readiness.go +++ b/internal/app/archieui/readiness.go @@ -10,13 +10,8 @@ import ( "github.com/samcharles93/archie-core/internal/infrastructure/readiness" ) -// newReadinessRegistry builds the registry behind GET /health/detailed. The -// UI is ready when both of its mandatory remote contracts answer within the -// dependency timeout; each probe consumes the dependency's own result over -// the wire and never inspects its manager, registry or database -// -// The component names match the daemon dashboard's, so the readiness view -// reads the same whichever process serves it. +// newReadinessRegistry builds the readiness probes for the Gateway and State +// Store. func newReadinessRegistry(o Options, tasks storecontract.TaskStore, chat messaging.ChatContract, problems []infraaccess.Problem) *health.Registry { return health.NewRegistry( readiness.NewProblemProbe("access_policies", problems), diff --git a/internal/app/archieui/run.go b/internal/app/archieui/run.go index 9f4fa6785..32ac6ec97 100644 --- a/internal/app/archieui/run.go +++ b/internal/app/archieui/run.go @@ -20,13 +20,8 @@ import ( "github.com/samcharles93/archie-core/internal/webui" ) -// buildAccessChain loads the stored policies over the wire and builds the -// engine. The wire client satisfies the two access contracts the dashboard -// needs alongside the engine. -// buildAccessChain loads the stored policies over the wire and builds the -// engine. A State Store serving no policies has no chain to evaluate: the -// dashboard degrades to the credential check rather than refusing to serve, -// so an unavailable policy store is a warning, not a boot failure. +// buildAccessChain loads stored policies and builds the access engine. With +// no policies it returns nil and logs a warning. func buildAccessChain(ctx context.Context, store *staterpc.Client, log *slog.Logger) (access.Authorizer, []infraaccess.Problem, error) { stored, err := store.ListPolicies(ctx) if err != nil { @@ -138,11 +133,8 @@ func Run(ctx context.Context, options Options) error { return serve(ctx, listener, srv.Handler(), opts) } -// serve runs handler on listener until ctx ends, then shuts the HTTP server -// down within ShutdownTimeout so in-flight dashboard requests finish before -// the contract clients close. A graceful shutdown that overruns its deadline -// is a normal shutdown under load, not a process failure: the remaining -// connections are force-closed and serve reports clean. +// serve runs handler until ctx ends, then shuts down within +// ShutdownTimeout. func serve(ctx context.Context, listener net.Listener, handler http.Handler, opts Options) error { server := &http.Server{Handler: handler, ReadHeaderTimeout: opts.ReadHeaderTimeout} serveErr := make(chan error, 1) diff --git a/internal/domain/eda/playbook/coordinator.go b/internal/domain/eda/playbook/coordinator.go index c09692df1..0e7ac04a1 100644 --- a/internal/domain/eda/playbook/coordinator.go +++ b/internal/domain/eda/playbook/coordinator.go @@ -10,17 +10,9 @@ import ( "github.com/samcharles93/archie-core/internal/domain/storecontract" ) -// InvokeOnce runs one playbook action at most once per -// (playbook, version, event, action) tuple, record-before-invoke: the ledger -// row is committed before fn runs, so a redelivered action (the same -// structural key) skips without repeating a non-revocable side effect. -// The structural key is computed -// from Decision.PlaybookID, Decision.Version, input.TaskID (the event_id) and -// Decision.ActionID; when the action declares no id the 1-based -// Decision.ActionPosition is used instead -- it is never a CEL expression. A -// key with an empty component (or no fallback position) is rejected before -// the ledger write rather than recorded as a degenerate row that collapses -// distinct events onto one key. +// InvokeOnce runs fn at most once per (playbook, version, event, action), +// recording the ledger row first. The action's id, or its position, keys the +// action; a key with an empty part is refused. func InvokeOnce(ctx context.Context, ledger storecontract.PlaybookDispatcher, log *slog.Logger, decision Decision, input DispatchInput, fn func(context.Context) error) error { if decision.ActionID == "" && decision.ActionPosition < 1 { return fmt.Errorf("playbook action has no id and no 1-based position (playbook_id=%q)", decision.PlaybookID) diff --git a/internal/domain/eda/playbook/playbook.go b/internal/domain/eda/playbook/playbook.go index 0bd718fcc..b6642523f 100644 --- a/internal/domain/eda/playbook/playbook.go +++ b/internal/domain/eda/playbook/playbook.go @@ -1,18 +1,5 @@ -// Package playbook is the EDA playbook document type and its event coordinator: -// the rich trigger+actions YAML shape with CEL `when` conditions and `args` -// values (open question 1, resolved to CEL). A playbook is one of two shapes -// (multi-action-playbooks.md, D2): -// -// - a workflow playbook is exactly one `workflow` action, unchanged from -// the original boundary, and is routed by the daemon's definition pin; -// - an action playbook is one or more `module` actions in order, each with -// a registered `kind`, `args`, and an optional `when`/`id`. Store.Run -// executes it. -// -// The two shapes never mix in one playbook. This is an ADDITIONAL routing -// source alongside the flat kind/label binding files: the daemon consults a -// matching workflow playbook before those bindings when it pins a task's -// workflow definition. The binding loaders themselves are untouched. +// Package playbook loads EDA playbooks: a trigger plus either one workflow +// action or ordered module actions, with CEL `when` and `args`. package playbook import ( @@ -59,12 +46,7 @@ type Store struct { // Playbook is one trigger+actions document. type Playbook struct { - // ID is the playbook's stable identity for execution-time idempotency: - // its file path relative to the configured directory root. It is unique - // within a single Load because the EDA loader walks one directory's - // entries and filenames there are inherently unique -- the doc's claim - // about "the directory-loader's collision rule" belongs to the ROUTING - // loader (workflow.LoadPlaybookDirs), a different loader. + // ID is the playbook's path relative to the directory root. ID string // Version is a content hash of the loaded file, recomputed on every // load. It pins dispatched-run provenance to the exact definition active @@ -93,11 +75,7 @@ type Trigger struct { // routed yet. type Action struct { Position string - // ID is an optional stable identifier for this action. When present it - // is the key later actions read this action's result under - // (actions.). Workflow actions use the shared stable-identifier - // grammar; module actions must use a CEL identifier so the id can be - // read through `actions.` field selection. + // ID optionally names this action so later actions can read actions.. ID string // Kind is the module kind name (position: module only); empty for a // workflow action. @@ -111,12 +89,8 @@ type Action struct { // Nil or empty means the action takes no args. Args map[string]*expr.Program - // env is the per-action CEL environment this action's expressions were - // compiled against: the prior actions' declared ids and their kinds' - // Result types. It is compile-only: expr.Env.Eval reads only the - // compiled Program (the cost limit is baked in at Compile) and never - // reads the Env receiver. It is unset only for a hand-built Action - // (tests, pre-load composition); loaded actions always carry it. + // env is the CEL environment this action's expressions were compiled + // against. env *expr.Env } @@ -178,12 +152,7 @@ func at(path string, line int) string { return fmt.Sprintf("%s:%d", path, line) } -// Module action ids are stricter than workflow ids because they must also be -// readable as `actions.` in CEL field selection. The authoritative check -// is expr.IsCELFieldName (which compiles the probe), plus a lowercase policy: -// the id must be a lowercase CEL field name, so `Build` -- a valid CEL -// identifier -- is rejected for its case, while a CEL keyword such as `in` is -// rejected because `actions.in` has no field-selection spelling. +// Module action ids must be lowercase CEL field names. // validateActionIDs enforces the WORKFLOW id shape and uniqueness. An absent // id is fine (ids are optional); a declared id must match the @@ -229,14 +198,8 @@ func validateModuleActionIDs(path string, actions []rawAction) error { return nil } -// Load reads every *.yaml/*.yml playbook in dir, validates each against the -// two-shape boundary (exactly one workflow action, or one or more module -// actions; never mixed), and compiles each when expression and args value -// against the action's per-playbook environment. ANY failure -- malformed -// YAML, a mixed/unsupported/empty action shape, an unknown kind, a when -// compile error, an args key error -- fails the whole load: the reject-at-load -// philosophy of the parent design doc. A missing directory is an empty store -// (matching the flat binding loaders' convention). +// Load reads and compiles every playbook in dir. Any invalid playbook fails +// the load. A missing directory is an empty store. func Load(dir string, modules Modules) (*Store, error) { entries, err := os.ReadDir(dir) if os.IsNotExist(err) { @@ -360,11 +323,8 @@ func compileActions(path string, raw []rawAction, schemas KindSchemas) ([]Action } } -// validateActionShapeField rejects a field from the other shape being present -// on an action: a workflow action must not declare kind (module-only), and a -// module action must not declare workflow (workflow-only). yaml.Unmarshal -// accepts both keys, so this is where a silently-ignored foreign key becomes -// a reported load failure naming the playbook and the action index. +// validateActionShapeField rejects a field belonging to the other action +// shape. func validateActionShapeField(path string, i int, pos string, a *rawAction) error { switch pos { case "workflow": @@ -505,14 +465,8 @@ func checkArgType(path, label, kind string, argsSchema reflect.Type, key string, return nil } -// compileArgs compiles every args value as a CEL expression at load, keyed by -// arg name. J2 has no literal/expression split: the YAML scalar text IS the -// CEL source, so a string literal is quoted inside YAML and a number or -// context read is written as CEL. When argsSchema is non-nil (a module kind's -// Args struct) every key must name one of its fields; workflow actions pass -// nil and keep free-form args. Each program goes through the same -// compile/reference validation as `when`, with label naming the offending -// action and the args key naming the offending field. +// compileArgs compiles each args value as CEL. With argsSchema, every key +// must name one of its fields. func compileArgs(path string, lines map[string]int, label, kind string, raw map[string]string, env *expr.Env, argsSchema reflect.Type) (map[string]*expr.Program, error) { if len(raw) == 0 { return nil, nil @@ -543,12 +497,7 @@ func compileArgs(path string, lines map[string]int, label, kind string, raw map[ return args, nil } -// validateArgsKeys rejects an args key the kind's Args struct does not define -// (multi-action-playbooks.md, D4), so an arg typo is a load failure rather -// than a dispatch-time shape mismatch. Go field names are lower-cased to the -// YAML spelling (Message -> message), and the YAML key is compared verbatim: -// the decoder also matches literal lower-case keys, so `Message` is rejected -// here rather than loading and then failing at dispatch. +// validateArgsKeys rejects args keys the kind's Args struct does not define. func validateArgsKeys(path string, lines map[string]int, label, kind string, argsSchema reflect.Type, raw map[string]string) error { t := argsSchema if t.Kind() == reflect.Pointer { @@ -575,14 +524,7 @@ func validateArgsKeys(path string, lines map[string]int, label, kind string, arg return nil } -// compileExpr compiles one playbook expression and applies the remaining -// load-time reference check: every `actions` read must be statically -// resolvable to a prior action id. The per-playbook object type rejects an -// undeclared or forward id and a dynamic `actions` read at compile time; the -// one spelling it does not reject is a bare `actions` value read, which this -// check still refuses. field is the human-readable expression location used in -// errors (`when condition` or `args["name"]`), so a failure names the -// playbook path and the offending expression. +// compileExpr compiles one expression and rejects a bare `actions` read. func compileExpr(path, field, src string, env *expr.Env) (*expr.Program, error) { prg, err := env.Compile(strings.TrimSpace(src)) if err != nil { @@ -605,13 +547,7 @@ type DispatchInput struct { Labels []string // Kind is the routing kind the labels produced (workintake.KindForLabels). Kind string - // TaskID is the originating task's identity, used to derive the event_id - // half of the playbook_dispatches idempotency ledger key. It carries the - // TaskEnvelope.IdempotencyKey() value ("archie:owner/repo/number"), the - // stable identity available at the discovery/dispatch point (pollNATS and - // the webhook receiver both compute kind/labels from a TaskEnvelope before - // any workflow.Task row exists). It is NOT a workflow.Task.ID int64, which - // does not exist until the task is persisted. + // TaskID is the originating task's idempotency key, used as the event id. TaskID string // Event is the event payload exposed as `event` in CEL expressions. For // a workflow-kind dispatch this carries the label/kind fields cheaply @@ -619,11 +555,8 @@ type DispatchInput struct { Event map[string]any } -// IsActionPlaybook reports whether pb is an action playbook (one or more -// module actions), as opposed to a workflow playbook (exactly one workflow -// action). It is the single two-shape predicate shared by Dispatch (which -// routes only workflow playbooks) and Run (which executes only action -// playbooks), so the two can never disagree. +// IsActionPlaybook reports whether pb has module actions rather than a +// workflow action. func (pb *Playbook) IsActionPlaybook() bool { return len(pb.Actions) != 1 || pb.Actions[0].Position != "workflow" } @@ -654,11 +587,8 @@ func (pb *Playbook) Match(input DispatchInput) bool { return true } -// Decision is what the coordinator selected for one event: the workflow a -// matching playbook's action names, plus the provenance of the definition -// that chose it. Version pins the decision to the exact file content active -// when it fired, and both fields are the first two components of the -// per-action idempotency key the resolved gap-2 scheme derives +// Decision is the workflow a matching playbook selected, with its playbook +// id and version. type Decision struct { PlaybookID string Version string @@ -673,21 +603,8 @@ type Decision struct { ActionPosition int } -// Dispatch returns the workflow name the first matching workflow playbook -// selects for the input, and whether any playbook matched. Action playbooks -// choose no workflow, so they are skipped here and executed by Run. No match -// means trigger -// mismatch or a when condition evaluating false, and the caller keeps its own -// routing. -// -// The name is returned rather than a compiled workflow because the production -// caller (the daemon's definition pin) decides against the active definition -// collection, not against a compiled registry; whether the named workflow -// exists is that caller's check, in the same place it makes it for every -// other routing source. -// -// A when evaluation error follows the resolved doc's J3: the condition -// evaluates to false and dispatch is skipped (the caller logs). +// Dispatch returns the workflow the first matching workflow playbook names, +// and whether one matched. A `when` error counts as false. func (s *Store) Dispatch(input DispatchInput) (Decision, bool) { // Nil-receiver-safe: a composition root that builds its daemon before the // playbook load hands over a nil store, and "no playbooks" is the honest @@ -723,15 +640,7 @@ func evalContext(input DispatchInput) expr.Context { } } -// EvalArgs evaluates a compiled action's args against the dispatch context, -// returning the resulting name->value map. Run evaluates args the same way -// against a context that also carries earlier actions' results. An action declaring no args evaluates to an empty map, nil-program entries -// are skipped, and the first evaluation error is returned. Nil-receiver-safe -// for the pre-load composition phase. -// -// Asymmetry with `when`: `when` is a predicate, so an evaluation error is -// false (J3: skip + log); `args` is data, so an evaluation error has no -// meaningful substitute and is returned to the caller to abort the playbook run +// EvalArgs evaluates an action's args and returns the first error. func (s *Store) EvalArgs(a Action, input DispatchInput) (map[string]any, error) { if s == nil { return map[string]any{}, nil diff --git a/internal/domain/eda/playbook/run.go b/internal/domain/eda/playbook/run.go index 0c90ed03f..42d34f4a9 100644 --- a/internal/domain/eda/playbook/run.go +++ b/internal/domain/eda/playbook/run.go @@ -11,11 +11,9 @@ import ( "github.com/samcharles93/archie-core/internal/domain/storecontract" ) -// Run executes every action playbook whose trigger matches input, in load -// order. Each action goes through -// InvokeOnce, so it fires at most once per (playbook, version, event, -// action). A failure stops only its own playbook; the rest still run, and -// the failures are returned joined, each naming its playbook and action. +// Run executes every matching action playbook in load order, each action at +// most once. A failure stops only its playbook; failures are returned +// joined. func (s *Store) Run(ctx context.Context, ledger storecontract.PlaybookDispatcher, log *slog.Logger, input DispatchInput) error { if s == nil { return nil diff --git a/internal/domain/workflow/prreview/blast.go b/internal/domain/workflow/prreview/blast.go index bd6be92ec..43bbe94ce 100644 --- a/internal/domain/workflow/prreview/blast.go +++ b/internal/domain/workflow/prreview/blast.go @@ -13,17 +13,8 @@ import ( "strings" ) -// BlastRadius returns the files inside fsys that a change reaches without -// touching: the files that import a changed file, and the files a changed file -// imports. It is the review's other half -- a line that breaks its callers -// still compiles, so the callers have to be read even though the diff never -// mentions them. -// -// Paths are relative to fsys's root and are matched as the diff wrote them. An -// import that cannot be resolved to a file inside fsys -- a standard library -// package, a node module, a file this snapshot does not carry -- contributes -// nothing: a guessed path would put a file nobody can open into the review's -// scope. +// BlastRadius returns the files that import a changed file or that a changed +// file imports. Unresolvable imports are ignored. func BlastRadius(fsys fs.FS, changed []string) ([]string, error) { graph, err := buildImportGraph(fsys) if err != nil { @@ -51,11 +42,8 @@ func BlastRadius(fsys fs.FS, changed []string) ([]string, error) { return radius, nil } -// ExposureCounts returns, for every file the change reaches without touching, -// how many changed files reach it: a fan-in count computed from the same -// import graph BlastRadius walks. It is BlastRadius's detail, not its -// replacement -- the coverage gate needs to tell a file three unrelated -// changed files each reach apart from one only one of them happens to import. +// ExposureCounts returns, for each file BlastRadius reaches, how many changed +// files reach it. func ExposureCounts(fsys fs.FS, changed []string) (map[string]int, error) { graph, err := buildImportGraph(fsys) if err != nil { @@ -174,14 +162,8 @@ func modulePath(fsys fs.FS) (string, error) { return "", nil } -// goPackageFiles maps every Go import path this snapshot owns to the files -// that package contains. The module path is what turns a directory into an -// import path, so an import resolves only when a directory of the snapshot -// really is the package that path names. -// -// A _test.go file is left out: it is never part of what an importer compiles, -// so no import path resolves to one. A test file's own imports are still edges -// of its own -- a test that exercises the change is read with it. +// goPackageFiles maps each Go import path in the snapshot to its non-test +// files. func goPackageFiles(paths []string, module string) map[string][]string { if module == "" { return nil diff --git a/internal/domain/workflow/prreview/budget.go b/internal/domain/workflow/prreview/budget.go index e49e5d649..9761dec88 100644 --- a/internal/domain/workflow/prreview/budget.go +++ b/internal/domain/workflow/prreview/budget.go @@ -10,16 +10,8 @@ type Budget struct { WallClock time.Duration } -// PhaseExhausted reports whether phase (1-based, counting the phase about to -// start) has already spent its share, given how much of the run's total -// budget every phase up to and including it is allotted out of phases total. -// -// The check is against the cumulative allotment through phase, not phase's -// own isolated slice: an earlier phase's underspend is not wasted, but its -// overspend still eats into a later phase's share. That is what "a phase -// whose share is spent is skipped" means for a phase that has not started -// yet and so has spent nothing of its own -- the run's spend so far is -// compared against how much the whole run should have spent by this point. +// PhaseExhausted reports whether the run's spend exceeds the cumulative share +// allotted through phase (1-based) of phases. func (b Budget) PhaseExhausted(phase, phases, tokensSpent int, elapsed time.Duration) bool { if phase <= 0 || phases <= 0 { return false diff --git a/internal/domain/workflow/prreview/diff.go b/internal/domain/workflow/prreview/diff.go index da6303e17..6bdf06af7 100644 --- a/internal/domain/workflow/prreview/diff.go +++ b/internal/domain/workflow/prreview/diff.go @@ -1,12 +1,5 @@ -// Package prreview is the deterministic core of the PR review pipeline: diff -// parsing, change clustering, blast radius, evidence extraction, scoring, -// deduplication, line mapping and the review event. Everything the pipeline -// can compute is computed here, so identical findings always produce identical -// scores, order and verdicts, and the agents around them only reason. -// -// It imports the standard library only, and the workflow package imports it -// rather than the reverse: code that cannot reach the store, the forge or the -// worktree is code whose data boundary stays visible. +// Package prreview is the deterministic part of the PR review pipeline: diff +// parsing, clustering, blast radius, evidence, scoring and the review event. package prreview import ( @@ -123,21 +116,13 @@ const rootClusterName = "root" const ( gitFilePrefix = "diff --git " devNull = "/dev/null" - // oldSidePrefix and newSidePrefix are the a/ and b/ git puts in front of - // the two sides of its own diff. They are not part of the path: a finding - // anchored to "b/x" names a file the snapshot does not have. A plain - // unified diff written by another tool carries no prefix, and a path whose - // first directory really is "a" or "b" keeps it, because only its own - // side's prefix is stripped. + // Git's a/ and b/ path prefixes, stripped from their own side only. oldSidePrefix = "a/" newSidePrefix = "b/" ) -// gitHeaderPaths reads both paths out of a "diff --git" line, each without its -// side prefix. git writes the paths plainly, or C-quoted when one of them holds -// something it has to escape -- and a quoted line names both sides in quotes, -// because a path that needs escaping is exactly a path this line could not be -// split on a space. +// gitHeaderPaths returns both paths from a "diff --git" line, unquoted and +// without prefixes. func gitHeaderPaths(line string) (oldPath, newPath string) { rest := strings.TrimPrefix(line, gitFilePrefix) if oldField, remaining, quoted := quotedField(rest); quoted { @@ -152,11 +137,7 @@ func gitHeaderPaths(line string) (oldPath, newPath string) { return strings.TrimPrefix(rest[:split], oldSidePrefix), strings.TrimRight(rest[split+len(" b/"):], " \r") } -// headerPath reads the path out of a "--- " or "+++ " header: git's "b/main.go", -// a plain unified diff's path with a timestamp after a tab, a /dev/null side, or -// the C-quoted form git writes for a path it has to escape. side is the prefix -// that side of a git diff carries; it is stripped here and only here, so the -// other side's prefix survives in a path that happens to start with it. +// headerPath returns the path from a "--- " or "+++ " header, stripping side. func headerPath(field, side string) string { if quoted, _, ok := quotedField(field); ok { return strings.TrimPrefix(unquotePath(quoted), side) @@ -265,11 +246,7 @@ func parseFileType(field string) int { // "@@" may contain anything, so nothing after it is matched. var hunkHeaderRE = regexp.MustCompile(`^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@`) -// fileInProgress is the parser's state for the file section it is inside. The -// section's headers are read into it as facts -- which paths, what kind of -// change, which object type -- and close() turns those facts into one status, -// so the status is a statement about the section and not about the line of it -// that happened to come last. +// fileInProgress is the parser state for the current file section. type fileInProgress struct { change FileChange oldPath string @@ -314,11 +291,7 @@ func newSectionInProgress(line string) *fileInProgress { return file } -// note reads one of the file's own header lines: the old and new paths, the -// /dev/null side that makes a file an addition or a deletion, the rename pair, -// and the mode lines -- which say the same thing for a file whose patch has no -// hunks at all. Anything else the section says -- index, similarity -- says -// nothing about where the change is, which is all findings are positioned by. +// note records one header line of the file section. func (f *fileInProgress) note(line string) { switch { case strings.HasPrefix(line, "--- "): @@ -352,12 +325,7 @@ func (f *fileInProgress) note(line string) { } } -// status is what the section's own headers said the change did to the file, -// read off every fact the section stated at once. A rename wins over a mode -// change, because git reports a file that was renamed and had its mode changed -// as a rename; an addition or a deletion wins over a type change, because a -// file that was not there has no old type; and a mode change between two -// permission sets of one object type is a modification, not a typechange. +// status derives the file's change status from its headers. func (f *fileInProgress) status() FileStatus { switch { case f.renamed: @@ -415,13 +383,8 @@ func headerPair(lines []string, index int) bool { return index+1 < len(lines) && strings.HasPrefix(lines[index+1], "+++ ") } -// opensNextFile reports whether the header pair at index begins the next file -// rather than being body text of this one. A pair is body text -- a removed -// line whose text begins "-- " followed by an added line whose text begins -// "++ " -- while the open hunk is still waiting for the lines its header -// counted; and a section has read its own "+++ " line before a pair can be -// another file's, because the pair of the section being opened is its own -// header. +// opensNextFile reports whether the header pair at index starts the next +// file rather than being hunk content. func (f *fileInProgress) opensNextFile(lines []string, index int) bool { return f.headerSeen && !f.hunkOpen() && headerPair(lines, index) } @@ -474,11 +437,7 @@ func (f *fileInProgress) close() FileChange { return change } -// ParseDiff parses a unified diff into per-file changes: the file sections -// "diff --git" opens, the sections a "--- "/"+++ " header pair opens in a diff -// that has no such line, their rename, mode and /dev/null headers, and the -// hunks that carry the change. It is the one parser: every position, count and -// path this package reports is read here. +// ParseDiff parses a unified diff into per-file changes. func ParseDiff(diff string) []FileChange { var ( files []FileChange diff --git a/internal/domain/workflow/prreview/dimension.go b/internal/domain/workflow/prreview/dimension.go index 4eee677c9..413b840d2 100644 --- a/internal/domain/workflow/prreview/dimension.go +++ b/internal/domain/workflow/prreview/dimension.go @@ -13,11 +13,9 @@ type Dimension struct { Priority float64 } -// MergeDimensions drops duplicate dimension names across the lenses' outputs -// (keeping the higher-priority copy), sorts by priority, and cuts the tail at -// cap. Order is stable for equal priority: the input order of the first lens -// that produced the name wins, so re-running the same lenses in the same -// order always keeps the same dimensions. +// MergeDimensions deduplicates dimensions by name, keeping the higher +// priority, sorts by priority and keeps the first limit. Ties keep input +// order. func MergeDimensions(lensOutputs [][]Dimension, limit int) []Dimension { byName := make(map[string]Dimension) order := make([]string, 0) diff --git a/internal/domain/workflow/prreview/gate.go b/internal/domain/workflow/prreview/gate.go index dd5e06d1f..1fef189e4 100644 --- a/internal/domain/workflow/prreview/gate.go +++ b/internal/domain/workflow/prreview/gate.go @@ -7,11 +7,7 @@ import ( "github.com/samcharles93/archie-core/internal/domain/workflow/task" ) -// Key is a scored finding's stable identity inside one gate document: file, -// line and title. Findings carry no ID, so this is what an operator's -// selection names and what filtering matches on. The document stores the key -// beside the finding (task.ReviewGateFinding), because the operator surface -// never sees this type. +// Key identifies a scored finding by file, line and title. func (f ScoredFinding) Key() string { return fmt.Sprintf("%s:%d:%s", f.File, f.LineStart, f.Title) } diff --git a/internal/domain/workflow/prreview/scoring.go b/internal/domain/workflow/prreview/scoring.go index 7f9dd8c4a..aa635763d 100644 --- a/internal/domain/workflow/prreview/scoring.go +++ b/internal/domain/workflow/prreview/scoring.go @@ -136,14 +136,8 @@ type ScoreInputs struct { BlastRadiusFiles int } -// Score drops the findings under their severity's confidence floor, scores -// what is left, merges the duplicates among the survivors and ranks the rest by -// score. The same findings always produce the same scores and the same order, -// whatever order they were handed in. -// -// The floor comes before the merge, so a discarded finding cannot shadow a kept -// one, and the merge is a clustering rather than a scan, so a chain of -// overlapping findings collapses the same way however it was listed. +// Score drops findings below their severity's confidence floor, scores and +// merges the rest, and ranks them. The result is deterministic. func Score(findings []Finding, inputs ScoreInputs) []ScoredFinding { scored := make([]ScoredFinding, 0, len(findings)) for _, finding := range findings { @@ -202,17 +196,9 @@ func sameKey(a, b ScoredFinding) bool { return a.File == b.File && a.Category == b.Category } -// mergeRun unions the overlapping ranges of one (file, category) group into -// clusters. The group arrives ordered by line, so a cluster is a run of members -// whose start is inside the range the run has already covered -- which is what -// makes the overlap transitive: 1-2, 2-3 and 3-4 are one cluster even though -// 1-2 and 3-4 do not touch. A run that begins where the previous one ended is -// two clusters: line 13 and the range 10-12 are two places. -// -// The cluster contributes the highest-scoring member, because that is the one -// that says the most, over the union of the cluster's lines, because the -// cluster is the claim and it covers every line of it. It is blocking when any -// member is: a merge may discard wording, never a verdict. +// mergeRun merges overlapping line ranges in one (file, category) group, +// keeping the best-scoring member over the union of lines. Blocking if any +// member is. func mergeRun(group []ScoredFinding) []ScoredFinding { clusters := make([]findingCluster, 0, len(group)) for _, member := range group { @@ -230,11 +216,7 @@ func mergeRun(group []ScoredFinding) []ScoredFinding { return merged } -// findingCluster is the run of overlapping findings one output finding stands -// for: the best member's wording and score, the union of the members' lines, -// and the disjunction of their verdicts. The best member is kept whole, so -// choosing between two members reads the fields they carry and never the -// cluster's widened range. +// findingCluster is a run of overlapping findings. type findingCluster struct { best ScoredFinding first int @@ -384,11 +366,8 @@ var severityAliases = map[Severity]Severity{ Severity("trivial"): SeverityNitpick, } -// normalizeSeverity reads a severity as one of the rubric's four words, however -// it is spelled or capitalised. A word the rubric does not know is read as a -// suggestion: the lowest weight that keeps a plausible finding in the review -// rather than the highest, because an unrecognised word is not evidence of -// severity. +// normalizeSeverity maps a severity to one of the four rubric words; +// unknown words become suggestion. func normalizeSeverity(severity Severity) Severity { lowered := Severity(strings.ToLower(strings.TrimSpace(string(severity)))) switch lowered { @@ -426,11 +405,8 @@ func IsHighPriority(f Finding) bool { } } -// ReviewEventFor decides the event a review is submitted with: a blocking -// finding requests changes, and anything else -- including a review that found -// nothing -- is a comment. A pipeline that found nothing has said nothing about -// the change, and an approval from a reviewer that did not look is worse than -// silence. +// ReviewEventFor returns REQUEST_CHANGES when any finding blocks, else +// COMMENT. It never approves. func ReviewEventFor(findings []ScoredFinding) ReviewEvent { for _, finding := range findings { if finding.Blocking { diff --git a/internal/domain/workflow/task/caller.go b/internal/domain/workflow/task/caller.go index 345c38aff..0c8bf6a79 100644 --- a/internal/domain/workflow/task/caller.go +++ b/internal/domain/workflow/task/caller.go @@ -2,17 +2,10 @@ package task import "context" -// Caller is what a workflow.call step uses to start a callee run and read it -// back while waiting. It is the consumer-owned contract the workflow engine -// holds (the same shape as Store), satisfied by *staterpc.Client for an -// agent-container run: the callee is a first-class task the State Store -// derives from the caller's row. +// Caller starts a workflow.call callee and reads it back. type Caller interface { - // StartCall enqueues the callee task for callerTaskID's workflow.call - // step: org, workspace, identity, owner, repo and issue number are - // derived from the caller's row, the callee carries the call's inputs, - // and the callee's depth is the caller's + 1. The store refuses a - // caller that is not running and a call past the depth limit. + // StartCall enqueues the callee for callerTaskID's call step at depth + 1. + // It fails if the caller is not running or the depth limit is exceeded. StartCall(ctx context.Context, callerTaskID int64, workflow string, inputs map[string]any) (*Task, error) // CallStatus reads one call's callee: its status, latest transition detail // and written outputs. A store only answers for a task whose diff --git a/internal/domain/workflow/task/changes.go b/internal/domain/workflow/task/changes.go index e2c81c50f..5ee4accf1 100644 --- a/internal/domain/workflow/task/changes.go +++ b/internal/domain/workflow/task/changes.go @@ -1,16 +1,6 @@ package task -// ChangeStats is the change one attempt produced, measured at the moment it -// was committed or pushed. -// -// It is a measurement, not a view: the worktree it was read from is deleted on -// merge, close and no-PR terminal states, and a retry resets the branch onto -// its base, so this is the only record of what an attempt actually changed. -// Nothing re-derives it after the fact. -// -// The value types live in this subpackage because package workflow must not -// import internal/worktree. Both the workflow engine and persistence boundary -// can use the measurement without depending on git infrastructure. +// ChangeStats is what one attempt changed, measured at commit or push time. type ChangeStats struct { BaseSHA string `json:"base_sha"` HeadSHA string `json:"head_sha"` @@ -53,9 +43,6 @@ const ( ChangeTypeChanged = "typechange" ) -// MaxCapturedFiles caps how many file entries one capture persists. Unlike -// Event.Detail, an event's data is not length-limited by the store, so this cap -// is what keeps one large refactor from writing an unbounded payload. A capture -// that dropped entries keeps the totals of the full set and reports itself as -// truncated. +// MaxCapturedFiles caps the file entries one capture stores; totals still +// cover all files. const MaxCapturedFiles = 200 diff --git a/internal/domain/workflow/task/definition_source.go b/internal/domain/workflow/task/definition_source.go index f39983f8b..02586c16d 100644 --- a/internal/domain/workflow/task/definition_source.go +++ b/internal/domain/workflow/task/definition_source.go @@ -1,12 +1,7 @@ package task -// WorkflowDefinitionEntry is one workflow's portable YAML as the control plane -// stores and serves it. YAML stays canonical and can be copied between Archie -// installations. -// -// It lives with the task vocabulary rather than with the engine for the same -// reason Definition does: a dashboard reads the stored collection without -// linking the workflow engine, which the UI process must never pull in. +// WorkflowDefinitionEntry is one workflow's YAML as stored in the control +// plane. type WorkflowDefinitionEntry struct { ID string `json:"id"` YAML string `json:"yaml"` diff --git a/internal/domain/workflow/task/interface.go b/internal/domain/workflow/task/interface.go index be75c6a66..9a90d5ac2 100644 --- a/internal/domain/workflow/task/interface.go +++ b/internal/domain/workflow/task/interface.go @@ -62,11 +62,7 @@ type WorkflowInterface struct { DeclaredNeeds WorkflowNeeds `yaml:"needs" json:"needs"` } -// Needs reports the harness requirements the interface carries: the declared -// needs, plus the captures a declared output forces, because an output is -// written through a capture tool. Profile selection reads this rather than -// DeclaredNeeds, so a workflow that declares outputs cannot name a Kit profile -// whose harness serves no capture tools. +// Needs returns the declared needs plus captures when outputs are declared. func (w WorkflowInterface) Needs() WorkflowNeeds { needs := w.DeclaredNeeds if len(w.Outputs) > 0 { @@ -160,12 +156,8 @@ func (w WorkflowInterface) CheckInputs(values map[string]any) error { return nil } -// CheckOutputs rejects declared-output values that do not satisfy the -// declared outputs: the same rules CheckInputs applies to inputs (required, -// undeclared, wrong type), read from the other side of the interface. -// A written null -// counts as not written, as CheckInputs treats a null input; an unwritten -// optional output leaves its key absent rather than null. +// CheckOutputs validates output values against the declared outputs. Null +// counts as not written. func (w WorkflowInterface) CheckOutputs(values map[string]any) error { for name, spec := range w.Outputs { v, ok := values[name] diff --git a/internal/domain/workflow/task/review_gate.go b/internal/domain/workflow/task/review_gate.go index bef62adf9..08711292f 100644 --- a/internal/domain/workflow/task/review_gate.go +++ b/internal/domain/workflow/task/review_gate.go @@ -6,22 +6,8 @@ import ( "github.com/samcharles93/archie-core/internal/taskstate" ) -// ReviewGate is the operator-approval gate's whole conversation with the -// operator, encoded on the task's review_gate column -// -// It lives with the task record it encodes, the way EncodeInputs does, for the -// same reason: the dashboard process renders and answers a gate, and it must -// not link the workflow engine that owns the finding type the pipeline reads. -// The findings therefore cross this document as opaque JSON beside the key an -// operator's selection names (ReviewGateFinding); only the pipeline decodes -// them. -// -// The offer half -- the findings, the head SHA, the pull request's identity -// and the workflow the wait resumes -- is written by the gate stage before it -// ends the run in waiting_human. The answer half -- the outcome, the finding -// keys an approve posts and the instructions a re-review carries -- is -// written back by the response path in the guarded requeue that clears the -// wait. +// ReviewGate is the operator-approval gate document stored on the task: the +// offered findings and context, and the operator's answer. type ReviewGate struct { // Findings is the review the operator is answering. An approve keeps it // (the resumed run posts it, filtered by Selection); a re-review's diff --git a/internal/domain/workflow/task/step.go b/internal/domain/workflow/task/step.go index 79c2dd63a..d69daadfa 100644 --- a/internal/domain/workflow/task/step.go +++ b/internal/domain/workflow/task/step.go @@ -40,11 +40,7 @@ type StepStart struct { ParentID int64 Kind string Name string - // CalledExecutionID names the WorkflowExecution a `call` step started. - // The store refuses a value that is not the caller's own callee (the - // callee's call_parent_task_id must name this execution), so a step's - // tree cannot cross runs: a cancel of that execution would otherwise - // cancel work the caller never started. Non-call kinds leave it 0. + // CalledExecutionID is the execution a call step started; 0 for other kinds. CalledExecutionID int64 } diff --git a/internal/domain/workflow/task/task.go b/internal/domain/workflow/task/task.go index d0905686b..bef79fdd5 100644 --- a/internal/domain/workflow/task/task.go +++ b/internal/domain/workflow/task/task.go @@ -1,10 +1,5 @@ -// Package task is the task-execution vocabulary of the workflow domain: -// the Task record, its lifecycle statuses, and the narrow Store contract -// workflow stages call mid-run. It split out of package workflow -// so the UI process can hold the vocabulary without -// linking the pipeline engine there -- which drags in agentexec, skill and -// tools. package workflow keeps aliases, so daemon-side callers are -// unaffected. +// Package task defines the Task record, its statuses and the Store contract +// workflow stages use. package task import ( @@ -66,13 +61,8 @@ type Task struct { // (parking-to-queued transitions). When it reaches the configured // max_retries the daemon moves the task to StatusDead. RetryCount int `json:"retry_count"` - // RetryMode is the operator's worktree choice for the next dispatch of this - // task (taskstate.RetryMode): refresh onto the base branch, or continue the - // work already pushed on Branch. The retry action writes it -- and the - // reaction consumer writes continue when it queues a remediation -- and the - // daemon's prepareWorkspace reads it to position the worktree. Empty reads - // as the explicit default, RefreshOntoBase; it is never inferred from the - // workflow at dispatch. + // RetryMode is the worktree mode for the next dispatch; empty means + // RefreshOntoBase. RetryMode string `json:"retry_mode"` // WatchCommentID is the poll backstop's high-water mark over forge // review-comment IDs for this task (pr-review-remediation.md decision @@ -84,11 +74,8 @@ type Task struct { // and comment IDs are independent forge sequences, and one combined // cursor would silently skip reviews once a larger comment ID landed. ReviewCursor int64 `json:"review_cursor"` - // Source is "forge" (default; a real forge issue backs this task) or - // "chat" (created via /spawn with no forge issue). Workflow stages - // and daemon reconciliation must skip forge-only operations (issue - // labels, comments, replies) for chat-sourced tasks; IssueNumber on - // a chat task is a synthetic value, not a real forge issue. + // Source is "forge" or "chat". Chat tasks have a synthetic IssueNumber and + // skip forge operations. Source string `json:"source"` // Identity is the archie identity that owns this task (chat-spawned // tasks only; empty for forge-sourced tasks and single-identity @@ -110,47 +97,22 @@ type Task struct { // the workflow's declared inputs at dispatch. They reach the agent as // structured data, never as body text. Inputs map[string]any `json:"inputs,omitempty"` - // Outputs are the structured results this run wrote to the workflow's - // declared outputs. The set is - // attempt-scoped: a claim starts the next attempt with an empty set and - // the finish write replaces the row's set wholesale. Callers read these - // only from a successful terminal state, through WorkflowCallStatus. + // Outputs are this attempt's declared outputs. Outputs map[string]any `json:"outputs,omitempty"` - // ReviewPayload is the JSON-encoded review unit (the forge review's - // actionable comments) the remediate workflow's current run must address. - // The daemon's reaction consumer injects it before queuing a remediation - // run, so the run is recoverable from the task record itself rather than - // only from a prompt. Empty outside a remediation run. RetryCount doubles - // as the remediation round counter for this same task, bounded by the - // repo's existing max_retries (decision 5's round cap). + // ReviewPayload is the JSON review unit the remediate run must address. ReviewPayload string `json:"review_payload"` // ParkClass is the producer-recorded answer to "what kind of // intervention does this park need?" (taskstate.ParkClass). Set at the // park site, never inferred from reason text; needs_human is the // default an unclassified park reads as. ParkClass string `json:"park_class"` - // RemediationRounds counts review-triggered remediation rounds, - // bounded by the repo's max_retries (pr-review-remediation.md - // decision 5). Deliberately separate from RetryCount, the operator - // budget: one shared counter made N operator retries eat the - // review-remediation budget and vice versa. + // RemediationRounds counts review-triggered remediation rounds. RemediationRounds int `json:"remediation_rounds"` - // ReviewGate is the operator-approval gate's whole conversation with the - // operator, persisted as one JSON document (prreview.EncodeReviewGate): the - // offer the gate writes before it waits for an operator -- the scored - // findings, the head SHA, the pull request's identity and the workflow the - // wait resumes -- and the answer the response path fills in -- the outcome, - // the selected findings' keys for an approve and the instructions for a - // re-review. Without it, "post the selected findings" cannot mean the - // findings the operator saw: the resumed run recomputes them with agent - // calls. Empty for a task that never reached the gate. + // ReviewGate is the encoded review gate document; empty if the task never + // reached the gate. ReviewGate string `json:"review_gate"` - // RereviewRounds counts how many operator re-reviews the pr-review gate - // granted, incremented in the same guarded write that requeues the - // re-review and capped at prreview.MaxRereviewRounds. - // Deliberately - // separate from both RetryCount and RemediationRounds -- one shared - // counter made unrelated retries draw another phase's budget down. + // RereviewRounds counts operator re-reviews, capped at + // prreview.MaxRereviewRounds. RereviewRounds int `json:"rereview_rounds"` // CallParentTaskID is the task whose workflow.call step started this // one; 0 on a root run. A caller reads only the tasks it started, @@ -182,14 +144,7 @@ func (t Task) IsForgeBacked() bool { return t.Source != SourceChat } -// EffectivePRNumber resolves the pull request a pr-review task targets: -// PRNumber when a producer already set it directly (archie's own PRs, which -// never goes through binding/chat input assignment), otherwise the pr_number -// input a binding (watched repositories) or a chat task (the operator -// trigger) assigned generically through Inputs. Returns 0 when neither is -// set. DecodeInputs (the store's round-trip) decodes a JSON number as -// json.Number; a caller that built Inputs by hand in Go may use float64 or -// int instead, so all three are accepted. +// EffectivePRNumber returns PRNumber, else the pr_number input, else 0. func (t Task) EffectivePRNumber() int { if t.PRNumber != 0 { return t.PRNumber @@ -218,12 +173,8 @@ type Store interface { Update(ctx context.Context, t *Task) error Transition(ctx context.Context, taskID int64, from, to, detail string) error InsertEvent(ctx context.Context, e events.Event) (int64, error) - // StartStep records a StepExecution entering running: - // the store creates the row, - // enforces the step transition table and the execution's own status, and - // writes the transition's stage_start event in the same transaction. It - // returns the step's id and the persisted event, which the caller publishes - // to its bus after the write commits. + // StartStep records a step entering running and returns its id and the + // persisted event. StartStep(ctx context.Context, s StepStart) (int64, events.Event, error) // FinishStep moves one step to its outcome under the same table, writing // the stage_finish event in the same transaction, and returns that event @@ -231,11 +182,7 @@ type Store interface { FinishStep(ctx context.Context, s StepFinish) (events.Event, error) } -// Definition is the operator-safe snapshot of an executable workflow. It -// contains only identity and stage order, never executable function values. -// It lives with the task vocabulary (not with the engine in package -// workflow) for the same reason this package exists: dashboards render -// Definitions without linking the engine. +// Definition is a workflow's id and stage order. type Definition struct { ID string `json:"id"` Name string `json:"name"` diff --git a/internal/infrastructure/postgres/clip.go b/internal/infrastructure/postgres/clip.go index 2f49bd3b7..721500527 100644 --- a/internal/infrastructure/postgres/clip.go +++ b/internal/infrastructure/postgres/clip.go @@ -7,11 +7,7 @@ import ( "github.com/jackc/pgx/v5/pgconn" ) -// clip limits s to n bytes without splitting a UTF-8 rune. It is the exact -// write-side normalisation the SQLite store applied before inserting event -// detail, transition detail, park reasons and review payloads: a generated -// query that drops it lets an oversized value through where the old store -// truncated it. +// clip limits s to n bytes without splitting a UTF-8 rune. func clip(s string, n int) string { if len(s) <= n { return s diff --git a/internal/infrastructure/postgres/harness_secrets.go b/internal/infrastructure/postgres/harness_secrets.go index 8117fb99b..e6424afce 100644 --- a/internal/infrastructure/postgres/harness_secrets.go +++ b/internal/infrastructure/postgres/harness_secrets.go @@ -73,11 +73,8 @@ func (s *EDA) PutHarnessSecret(ctx context.Context, secret harnesssecret.Secret) return nil } -// sealHarnessSecret JSON-marshals the token set and encrypts it under -// bindingcipher.HarnessSecretDomain -- its own domain separator, distinct -// from BindingDomain's, so a row cannot be relocated between the two tables -// and still authenticate. OAuth tokens require a configured encryption key; -// the binding store's legacy plaintext fallback does not apply here. +// sealHarnessSecret encrypts the token set under HarnessSecretDomain. An +// encryption key is required. func (s *EDA) sealHarnessSecret(payload harnessSecretPayload) (string, error) { if s.cipher == nil { return "", errors.New("postgres: harness secrets require an encryption key") diff --git a/internal/infrastructure/postgres/identities.go b/internal/infrastructure/postgres/identities.go index 1830eb09f..745f9236a 100644 --- a/internal/infrastructure/postgres/identities.go +++ b/internal/infrastructure/postgres/identities.go @@ -230,12 +230,9 @@ func (s *Store) BindSubject(ctx context.Context, id identity.IdentityID, subject return tx.Commit(ctx) } -// BootstrapIdentities seeds the system identity and the configured legacy -// names idempotently, migrating any forge tasks that still carry a legacy -// name to the stable id. Each legacy name is derived through -// identity.FromLegacyName, so a name this store cannot turn into an identity is -// reported rather than silently skipped -- the file loader refuses the same -// names (configuration.validateIdentities). +// BootstrapIdentities seeds the system identity and the legacy names, and +// moves tasks carrying a legacy name to its stable id. Invalid names are +// errors. func (s *Store) BootstrapIdentities(ctx context.Context, legacyNames []string) error { values := make([]identity.Identity, 0, len(legacyNames)+1) values = append(values, identity.System()) diff --git a/internal/infrastructure/postgres/maintenance.go b/internal/infrastructure/postgres/maintenance.go index 746f9b9ad..bf211ce44 100644 --- a/internal/infrastructure/postgres/maintenance.go +++ b/internal/infrastructure/postgres/maintenance.go @@ -89,11 +89,8 @@ func AcquireAll(ctx context.Context, pool *pgxpool.Pool, names []string) (releas return release, nil } -// Backup writes a whole-database pg_dump archive to out. It takes no claim: -// pg_dump reads one consistent snapshot, so it is safe against serving -// processes, which is what the update installer needs. The archive goes to a -// scratch file and replaces out only once pg_restore can read it back, so a -// failed run never costs the previous good snapshot. +// Backup writes a pg_dump archive to out, replacing it only once pg_restore +// can read the new archive. func Backup(ctx context.Context, databaseURL, out string) error { tmp, err := os.CreateTemp(filepath.Dir(out), filepath.Base(out)+".tmp*") if err != nil { @@ -134,14 +131,9 @@ func ValidateSnapshot(ctx context.Context, path string) ([]string, error) { return tables, nil } -// Restore replaces the whole database with the snapshot at from. It is -// destructive: every write after the snapshot is lost. It refuses unless it -// can claim every service role, so no serving process is running and none can -// start until it finishes; a claim that cannot be checked is a refusal too. -// -// pg_restore --clean drops only what the archive holds, so tables a later -// migration created are dropped first; otherwise they would survive into the -// restored schema and break the next upgrade's migration. +// Restore replaces the whole database with the snapshot at from. It refuses +// unless it can claim every service role. Tables the archive lacks are +// dropped first. func Restore(ctx context.Context, databaseURL, from string) error { tables, err := ValidateSnapshot(ctx, from) if err != nil { diff --git a/internal/infrastructure/postgres/orgs.go b/internal/infrastructure/postgres/orgs.go index af9be40ec..cfdffef4f 100644 --- a/internal/infrastructure/postgres/orgs.go +++ b/internal/infrastructure/postgres/orgs.go @@ -1,11 +1,3 @@ -// Orgs, workspaces, memberships and agent assignments: the Postgres -// implementation of internal/domain/org's contracts, plus the resumable -// default org/workspace upgrade the State Store runs at boot -// -// The upgrade refuses nothing itself; the refusal to serve scoped calls -// until it has finished is enforced by the boot order -- the State Store -// runs this upgrade before its gRPC listener starts, and a failed upgrade -// fails the boot (fail closed) rather than serving records with no org. package postgres import ( @@ -244,10 +236,7 @@ func (s *Store) UpgradeDefaultOrg(ctx context.Context) error { } // runUpgradePhase stamps one phase's tables and records its ledger row in one -// transaction, after making sure the default org and workspace exist and -// every agent identity belongs to the default org. An interrupted phase -// leaves no ledger row, so the next start re-runs it from the beginning -- -// every stamp is idempotent on rows the upgrade has not covered yet. +// transaction. An interrupted phase reruns from the start. func (s *Store) runUpgradePhase(ctx context.Context, name string, stamps []func(context.Context, *postgresdb.Queries) (int64, error)) error { tx, err := s.pool.Begin(ctx) if err != nil { diff --git a/internal/infrastructure/postgres/resources.go b/internal/infrastructure/postgres/resources.go index 2f6f4ad3f..e47f349e1 100644 --- a/internal/infrastructure/postgres/resources.go +++ b/internal/infrastructure/postgres/resources.go @@ -96,17 +96,8 @@ func (s *Resources) Audit(ctx context.Context, table string, keys []string, limi return entries, nil } -// PutResource applies one control-plane resource write. -// -// It is idempotent per request ID: a write whose (org_id, kind, request_id) is already -// in resource_history returns that revision instead of writing a second one, so a -// retry that reached the store twice is still one revision. The ledger is what -// carries the key -- resource_history outlives the row it describes -- so a -// replay of a revision whose resource an operator removed re-creates that row -// rather than answering with a revision the store no longer holds. The -// alternative is a write that reports a version for a kind that is absent: the -// caller cannot tell the difference, and a kind can stay gone while every -// process believes it holds a value. +// PutResource applies one control-plane resource write, idempotent per +// request ID. func (s *Resources) PutResource(ctx context.Context, write storecontract.ResourceWrite) (_ storecontract.Resource, retErr error) { if err := checkResourceKey(write.OrgID, write.Kind); err != nil { return storecontract.Resource{}, err @@ -197,13 +188,8 @@ func appendResourceRevision(ctx context.Context, queries *postgresdb.Queries, wr return history, nil } -// replayedResource answers a write whose request ID resource_history already -// holds. The ledger's revision is the answer and a replay writes nothing, with -// one repair: when the resource that revision describes is no longer the current -// row, the row is re-created from it. That is the state an operator removing a -// resource leaves behind, and without the repair the store answers with a -// revision it does not hold, so the caller reads a version for a kind that is -// absent and the kind stays absent. +// replayedResource answers a repeated request ID with its recorded revision, +// re-creating the row if it was removed since. func (s *Resources) replayedResource(ctx context.Context, queries *postgresdb.Queries, tx pgx.Tx, existing postgresdb.ResourceByRequestRow) (storecontract.Resource, error) { if _, err := queries.ResourceByKind(ctx, postgresdb.ResourceByKindParams{OrgID: existing.OrgID, Kind: existing.Kind}); errors.Is(err, pgx.ErrNoRows) { if _, err := queries.ReinsertResource(ctx, postgresdb.ReinsertResourceParams{ diff --git a/internal/infrastructure/postgres/steps.go b/internal/infrastructure/postgres/steps.go index bf58241a9..a93b85010 100644 --- a/internal/infrastructure/postgres/steps.go +++ b/internal/infrastructure/postgres/steps.go @@ -20,12 +20,8 @@ import ( // bus after the write commits, and the daemon's event sink skips // already-persisted rows by their assigned ID -- the EmitDurable convention. -// StartStep records a StepExecution entering running: the row is created -// pending, guarded into running under the shared step transition table, and -// the stage_start event is appended in the same transaction. The execution's -// row is locked for the whole write, so its status check cannot race the -// guarded updates, and org and workspace are stamped from it -- the request's -// ownership fields are ignored, like every owned record. +// StartStep creates a step and moves it to running, appending stage_start in +// the same transaction. Org and workspace come from the execution row. func (s *Store) StartStep(ctx context.Context, start task.StepStart) (int64, events.Event, error) { if !task.ValidStepKind(start.Kind) { return 0, events.Event{}, fmt.Errorf("%w: unknown step kind %q", storecontract.ErrInvalidStep, start.Kind) @@ -98,11 +94,8 @@ func (s *Store) StartStep(ctx context.Context, start task.StepStart) (int64, eve return stepID, event, nil } -// verifyCallStep refuses a call step whose callee is not this run's own: -// the callee's call_parent_task_id must name the recording execution, or the -// call step cannot record (a missing callee is the caller's stale view). -// Without this check a cancel of the recording run would sweep work it never -// started. +// verifyCallStep refuses a call step whose callee is not this execution's +// own. func (s *Store) verifyCallStep(ctx context.Context, q *postgresdb.Queries, start task.StepStart) error { if start.CalledExecutionID == 0 { return nil @@ -151,11 +144,9 @@ type stepParentState struct { underTerminal bool } -// FinishStep moves one step to its outcome under the shared step transition -// table, writing the stage_finish event in the same transaction and returning -// it for the caller's post-commit publish. A step that is missing, that is -// not the named execution's, or whose status does not match from is stale; an -// off-table from->to pair is refused as an illegal transition. +// FinishStep moves a step to its outcome and returns the stage_finish event. +// A missing, foreign or mismatched step is stale; a disallowed pair is +// illegal. func (s *Store) FinishStep(ctx context.Context, finish task.StepFinish) (events.Event, error) { tx, err := s.pool.Begin(ctx) if err != nil { @@ -245,12 +236,8 @@ func stepEventData(to taskstate.StepStatus, durationMS int64, detail string) map return data } -// ListSteps reads one execution's recorded steps, every attempt oldest first -// when attempt is 0, or just the one it names. It is the dashboard run -// detail's authoritative source, -// replacing the fold over stage_start/stage_finish events tasks.stage used to -// back -- unlike StartStep/FinishStep, this is a plain read with no -// transition to guard, so it takes no transaction. +// ListSteps returns an execution's steps, for every attempt when attempt is +// 0. func (s *Store) ListSteps(ctx context.Context, executionID int64, attempt int) ([]task.StepExecution, error) { rows, err := s.queries().ListStepExecutions(ctx, postgresdb.ListStepExecutionsParams{ ExecutionID: executionID, Attempt: int64(attempt), @@ -287,14 +274,8 @@ func stepParentID(parentID int64) pgtype.Int8 { return pgtype.Int8{Int64: parentID, Valid: parentID != 0} } -// CancelExecution is the one cancel path: one transaction moves every -// non-terminal StepExecution of the execution's current attempt to cancelled -- -// one event row each -- and the execution itself to the status the operator -// action names, under the shared execution transition table. Staleness is -// decided before legality, as guardTransition decides it, and the audit row -// lands in the same write. The caller cancels the in-memory context after this -// commits; the worker's next step write then fails ErrStaleTransition and -// stops. +// CancelExecution cancels the current attempt's open steps and moves the +// execution to `to`, in one transaction with events and an audit row. func (s *Store) CancelExecution(ctx context.Context, taskID int64, reason, to string) ([]int64, error) { tx, err := s.pool.Begin(ctx) if err != nil { @@ -367,12 +348,8 @@ func (s *Store) CancelExecution(ctx context.Context, taskID int64, reason, to st return ids, nil } -// cancelWaitedCallees cancels each callee the caller was still waiting on -// through its own CancelExecution, under its own lifecycle, in the caller's -// write's aftermath -- the callee's own steps and its own move to the same -// destination. A chain of calls is bounded by the call depth the enqueue -// enforces, so the recursion is finite; a callee that cannot be cancelled is -// reported, and the caller's own record stands either way. +// cancelWaitedCallees cancels each callee the caller was waiting on. +// Failures are reported; the caller's cancel stands. func (s *Store) cancelWaitedCallees(ctx context.Context, waiting []postgresdb.WaitingCallStepsRow, reason, to string) error { var failures []error for _, call := range waiting { diff --git a/internal/infrastructure/postgres/store.go b/internal/infrastructure/postgres/store.go index dedba3adf..6db381c04 100644 --- a/internal/infrastructure/postgres/store.go +++ b/internal/infrastructure/postgres/store.go @@ -18,11 +18,8 @@ import ( "github.com/samcharles93/archie-core/internal/taskstate" ) -// Store is the PostgreSQL implementation of the State Store. It carries the -// full task/event/identity/status surface behind the storecontract interfaces, -// with the control-plane resource surface embedded from Resources. The pool is -// process-scoped and owned by the composition (internal/app/archied), not by -// the Store, so Close is a no-op. +// Store is the PostgreSQL State Store. The pool belongs to the caller, so +// Close is a no-op. type Store struct { pool *pgxpool.Pool *Resources @@ -37,16 +34,9 @@ func (s *Store) queries() *postgresdb.Queries { return postgresdb.New(s.pool) } -// guardTransition locks the task's row and checks the status write the caller -// is about to perform: a row whose status is not the expected from is stale -// (ErrStaleTransition), a from->to pair outside the shared transition table is -// refused with ErrIllegalTransition. -// Staleness is decided first, so -// a caller that is wrong about the row's state gets the stale sentinel even -// when its pair is also unroutable. The row stays locked for the caller's -// transaction, so the checks cannot race the guarded write that follows. -// A missing row is stale, matching what the guarded update alone used to -// return. +// guardTransition locks the task row and checks the transition: a status +// other than from is ErrStaleTransition, a disallowed pair is +// ErrIllegalTransition. A missing row is stale. func guardTransition(ctx context.Context, q *postgresdb.Queries, taskID int64, from, to string) error { status, err := q.LockTaskStatus(ctx, taskID) if errors.Is(err, pgx.ErrNoRows) { @@ -74,11 +64,8 @@ func (s *Store) Close() error { return nil } // JSON-safe floor that keeps synthetic issue numbers clear of real ones. const syntheticIssueNumberBase = 1_000_000_000_000_000 -// structuredPayloadBytes is the write-side bound the store applies to a -// structured payload (review_payload today, task outputs now). A value that -// would exceed it is refused for outputs -- clipped JSON does not parse, and a -// caller must receive an object or nothing -- where the legacy review payload -// is still clipped. +// structuredPayloadBytes bounds structured payloads. Oversized outputs are +// refused; review payloads are clipped. const structuredPayloadBytes = 4000 // taskFromRow maps the generated task row to the workflow.Task the daemon and @@ -159,11 +146,8 @@ func (s *Store) EnqueueIssue(ctx context.Context, owner, repo string, number int return n > 0, nil } -// EnqueueChatTask inserts a queued chat-sourced task and returns the full row. -// The store allocates the synthetic issue number durably so processes sharing -// the database cannot generate the same value. inputs are the task's workflow -// inputs (the operator trigger's pr_number, for instance); a chat task carries -// no binding provenance, so the insert is the only writer of that column. +// EnqueueChatTask inserts a queued chat task with a store-allocated synthetic +// issue number. func (s *Store) EnqueueChatTask(ctx context.Context, owner, repo, title, body, wf, identity string, inputs map[string]any) (*workflow.Task, error) { encoded, err := task.EncodeInputs(inputs) if err != nil { @@ -226,11 +210,8 @@ func (s *Store) ClaimByIssue(ctx context.Context, owner, repo string, number int return taskFromRow(t), nil } -// Transition moves a task to a new status and records the audit detail. The -// from status guards the update; a mismatch returns ErrStaleTransition without -// writing an audit row, and a from->to pair outside the shared transition -// table returns ErrIllegalTransition. Transitioning to parked also stores -// detail as ParkReason in the same transaction. +// Transition moves a task from `from` to `to` with an audit row. Parking +// also stores detail as ParkReason. func (s *Store) Transition(ctx context.Context, taskID int64, from, to, detail string) error { tx, err := s.pool.Begin(ctx) if err != nil { @@ -295,11 +276,7 @@ func (s *Store) ParkTask(ctx context.Context, taskID int64, from, detail, class // Update persists mutable task fields written by workflows. func (s *Store) Update(ctx context.Context, t *workflow.Task) error { - // The row write is where a run's outputs land. - // An encoded set past the bound the store applies to a structured payload - // is refused rather than clipped: clipped JSON does not parse, and a caller - // would receive a broken object as a value. The engine turns the refusal - // into a park, so nothing silently loses its structured result. + // Oversized outputs are refused, not clipped. outputs, err := task.EncodeOutputs(t.Outputs) if err != nil { return fmt.Errorf("store: encode task %d outputs: %w", t.ID, err) @@ -414,12 +391,8 @@ func (s *Store) RetryTask(ctx context.Context, taskID int64, fromStatus, wf, ret }) } -// RespondReviewGate is the review gate response write: -// one guarded -// requeue that records the operator's answer, increments rereview_rounds for -// a re-review only, and writes one audit row -- all in one transaction. The -// cap is checked under the row lock the transition guard takes, so two -// simultaneous re-reviews cannot both spend the last round. +// RespondReviewGate records the operator's gate answer and requeues, counting +// re-reviews against the cap under the row lock. func (s *Store) RespondReviewGate(ctx context.Context, taskID int64, fromStatus, gate string, rereview bool, maxRounds int) error { tx, err := s.pool.Begin(ctx) if err != nil { @@ -520,11 +493,8 @@ func (s *Store) ArchiveTask(ctx context.Context, taskID int64, fromStatus string return eventID, nil } -// RecoverStale re-queues tasks left running by a crashed or replaced daemon -// and, in the same transaction, moves the steps those executions left running -// to the step transition table's interrupted outcome: one event row per step -// transition and the execution's audit row land in the same write. The next -// attempt starts with fresh steps; earlier attempts are never rewritten. +// RecoverStale requeues tasks left running and marks their running steps +// interrupted, in one transaction. func (s *Store) RecoverStale(ctx context.Context) (int64, error) { tx, err := s.pool.Begin(ctx) if err != nil { @@ -671,12 +641,9 @@ func (s *Store) TaskByID(ctx context.Context, taskID int64) (*workflow.Task, err return taskFromRow(t), nil } -// StartCall enqueues the callee of callerTaskID's workflow.call step. -// The store owns the table, so it re-checks -// both runtime invariants the engine checks: the caller must be running and -// the call must not pass workflow.MaxCallDepth. The callee inherits the -// caller's org, workspace, identity, owner and repo, and takes a fresh -// synthetic issue number, the same allocator chat tasks use. +// StartCall enqueues a workflow.call callee inheriting the caller's org, +// workspace, identity and repo. The caller must be running and within +// workflow.MaxCallDepth. func (s *Store) StartCall(ctx context.Context, callerTaskID int64, wf string, inputs map[string]any) (*workflow.Task, error) { encoded, err := task.EncodeInputs(inputs) if err != nil { @@ -703,11 +670,7 @@ func (s *Store) StartCall(ctx context.Context, callerTaskID int64, wf string, in return taskFromRow(callee), nil } -// callRefusal names why EnqueueCallTask inserted nothing. The three refusals -// are distinct failures an operator reads differently: a missing caller is a -// problem, a caller that is not running is a stale retry, and a depth -// refusal is the limit doing its job. The two behavioural ones carry the -// caller's detail in the log and the sentinel across the wire. +// callRefusal explains why EnqueueCallTask inserted nothing. func (s *Store) callRefusal(ctx context.Context, callerTaskID int64) error { caller, err := s.queries().TaskByID(ctx, callerTaskID) if errors.Is(err, pgx.ErrNoRows) { diff --git a/internal/tools/mcp/client.go b/internal/tools/mcp/client.go index 1e6488136..f486d1d5d 100644 --- a/internal/tools/mcp/client.go +++ b/internal/tools/mcp/client.go @@ -13,11 +13,7 @@ import ( // protocolVersion is the MCP protocol version this client speaks. const protocolVersion = "2024-11-05" -// Transport is the narrow interface Client depends on -- satisfied by -// [*StdioTransport]. Tests substitute a fake to avoid spawning a real -// subprocess. Notify is separate from Send because a notification (no -// "id") never gets a JSON-RPC response -- a transport whose Send always -// waits for a correlated reply would hang forever if asked to send one. +// Transport sends requests and notifications to an MCP server. type Transport interface { Send(ctx context.Context, body []byte) ([]byte, error) Notify(ctx context.Context, body []byte) error @@ -31,11 +27,7 @@ type Client struct { transport Transport serverName string nextID atomic.Int64 - // callMu serializes tools/call requests to this server. Most MCP - // servers are single-threaded processes and don't expect or handle - // concurrent requests safely, so serializing is the default. A server - // whose config declares it handles concurrent requests gets no callMu: - // nil means this server's calls are never held apart. + // callMu serializes tools/call to this server. Nil allows concurrent calls. callMu *sync.Mutex // samplingHandler answers server-initiated sampling/createMessage // requests. Set once at construction, so reading it from a transport @@ -54,15 +46,9 @@ func WithSamplingHandler(handler SamplingHandler) ClientOption { return func(c *Client) { c.samplingHandler = handler } } -// NewClient builds a Client over transport. serverName identifies this -// MCP server in log/error messages; it need not match the server's own -// self-reported name. parallelToolCalls drops the per-server serialization -// of tools/call: false (the default) keeps one call in flight at a time, -// true lets the caller's own concurrency through. -// -// A transport that can receive server-initiated requests gets this client -// registered as their handler; one that cannot (the stateless HTTP -// transport) has no server→client channel for them to arrive on. +// NewClient builds a Client over transport. parallelToolCalls allows +// concurrent tools/call. The client handles server-initiated requests when +// the transport supports them. func NewClient(transport Transport, serverName string, parallelToolCalls bool, opts ...ClientOption) *Client { c := &Client{transport: transport, serverName: serverName} if !parallelToolCalls { @@ -77,11 +63,8 @@ func NewClient(transport Transport, serverName string, parallelToolCalls bool, o return c } -// handleServerRequest dispatches one server-initiated request. The MCP spec -// defines sampling/createMessage as the request a server sends to a client; -// everything else is method-not-found. A request this client cannot answer -// always gets an explicit JSON-RPC error response -- dropping it would leave -// the server blocked on a reply that never comes. +// handleServerRequest answers sampling/createMessage and returns +// method-not-found for anything else. func (c *Client) handleServerRequest(ctx context.Context, method string, params json.RawMessage) (json.RawMessage, *ErrorData) { if method != "sampling/createMessage" { return nil, &ErrorData{Code: ErrCodeMethodNotFound, Message: "method not found: " + method} @@ -156,11 +139,8 @@ type ResourceContent struct { Blob string `json:"blob,omitempty"` } -// CallToolResult is the result of tools/call. IsError reports a -// tool-level failure (the call reached the tool, which then failed) as -// distinct from a transport or JSON-RPC protocol error -- the MCP spec -// requires tool failures to be reported this way so the calling LLM sees -// the failure content instead of a bare error. +// CallToolResult is a tools/call result. IsError reports a tool-level +// failure. type CallToolResult struct { Content []ContentBlock `json:"content"` IsError bool `json:"isError,omitempty"` @@ -212,11 +192,8 @@ func (c *Client) ListTools(ctx context.Context) ([]ToolSchema, error) { } } -// CallTool invokes a tool by name with the given arguments. A non-nil -// error means the call could not be completed at all (transport failure, -// malformed response, unknown method). A tool that ran and failed is -// reported via CallToolResult.IsError, not a Go error -- see -// [CallToolResult]. +// CallTool calls a tool. A Go error means the call failed; a tool failure is +// CallToolResult.IsError. func (c *Client) CallTool(ctx context.Context, name string, arguments map[string]any) (CallToolResult, error) { if c.callMu != nil { c.callMu.Lock() diff --git a/internal/tools/mcp/framing.go b/internal/tools/mcp/framing.go index 8c4854134..bb45880cb 100644 --- a/internal/tools/mcp/framing.go +++ b/internal/tools/mcp/framing.go @@ -21,13 +21,8 @@ func writeMessage(w io.Writer, data []byte) error { return err } -// readMessage reads one newline-delimited JSON-RPC message from r and returns -// the raw JSON bytes without its line ending. -// -// r must be a *bufio.Reader. Callers that hold a plain io.Reader should -// wrap it once with bufio.NewReader and reuse that wrapper across -// multiple readMessage calls -- creating a new bufio.Reader per call -// silently drops buffered data and breaks multi-message streams. +// readMessage reads one newline-delimited JSON-RPC message from r, which must +// be a reused *bufio.Reader. func readMessage(r io.Reader) ([]byte, error) { br, ok := r.(*bufio.Reader) if !ok { diff --git a/internal/tools/mcp/npm_cache.go b/internal/tools/mcp/npm_cache.go index 8efa49b73..c06af0d96 100644 --- a/internal/tools/mcp/npm_cache.go +++ b/internal/tools/mcp/npm_cache.go @@ -2,22 +2,8 @@ package mcp import "path/filepath" -// NpmCacheEnv returns environment variables that make an npx-launched MCP -// server reuse a persistent package cache at cacheDir, instead of npm -// re-resolving and re-downloading the package from the registry on every -// launch. Empty for any command other than npx, or an empty cacheDir -- -// npx has a registry dependency other commands don't, and an empty cacheDir -// means the caller has no persistent location to point npm at. -// -// This covers the npm package itself, not a package's own separate -// download path -- e.g. Playwright/Puppeteer-based servers fetch browser -// binaries from a CDN via a postinstall script, gated by their own env -// vars, which this does not touch. -// -// Matched by base name, not exact string: a command may be pinned via an -// absolute path (an operator's daemon config, or a container image's PATH), -// and an exact "npx" match would skip the fix silently, with no error -// logged, leaving the underlying registry re-fetch in place unnoticed. +// NpmCacheEnv returns env vars pointing npx's package cache at cacheDir. Empty +// unless command's base name is npx and cacheDir is set. func NpmCacheEnv(command, cacheDir string) []string { if filepath.Base(command) != "npx" || cacheDir == "" { return nil diff --git a/internal/tools/mcp/sampling.go b/internal/tools/mcp/sampling.go index c11320d14..8a8b791ea 100644 --- a/internal/tools/mcp/sampling.go +++ b/internal/tools/mcp/sampling.go @@ -54,11 +54,8 @@ type SamplingResult struct { StopReason string `json:"stopReason,omitempty"` } -// SamplingHandler answers one server-initiated sampling request from a -// configured model. It returns a Go error for a refused or failed -// completion; the client maps that to a JSON-RPC internal error so the -// server sees the failure for its own request only, never a dropped -// session. +// SamplingHandler answers a server's sampling request. Errors become JSON-RPC +// internal errors. type SamplingHandler func(ctx context.Context, req SamplingRequest) (SamplingResult, error) // ServerRequestHandler answers one request the MCP server sent to this diff --git a/internal/tools/mcp/transport.go b/internal/tools/mcp/transport.go index 563f5ff36..e8b53d3e6 100644 --- a/internal/tools/mcp/transport.go +++ b/internal/tools/mcp/transport.go @@ -80,14 +80,8 @@ func (c StdioTransportConfig) effectiveShutdownGrace() time.Duration { // ── Transport ─────────────────────────────────────────────────────────── -// StdioTransport manages an MCP server subprocess, sending JSON-RPC 2.0 -// messages to its stdin and receiving responses from its stdout. Messages -// use MCP's newline-delimited JSON framing. -// -// The transport supports automatic restart with exponential backoff when -// the subprocess dies unexpectedly. Use [StdioTransport.Start] to begin, -// [StdioTransport.Send] to exchange messages, and [StdioTransport.Stop] -// to shut down cleanly. +// StdioTransport runs an MCP server subprocess, exchanging newline-delimited +// JSON-RPC over stdin/stdout, and restarts it with backoff when it dies. type StdioTransport struct { config StdioTransportConfig @@ -289,12 +283,7 @@ func (t *StdioTransport) Stop(_ context.Context) error { return nil } -// Send writes a JSON-RPC 2.0 request to the subprocess stdin and waits for -// the matching response on stdout. It uses the "id" field from the JSON -// body to correlate the response. -// -// Send returns an error if the transport is not running, if the write fails, -// if the context is cancelled, or if the transport is stopped while waiting. +// Send writes a request and waits for the response with the same id. func (t *StdioTransport) Send(ctx context.Context, body []byte) ([]byte, error) { // Extract the message ID from the body for response correlation. msgID, err := extractMessageID(body) @@ -356,11 +345,7 @@ func (t *StdioTransport) Send(ctx context.Context, body []byte) ([]byte, error) } } -// Notify writes a JSON-RPC 2.0 notification (a message with no "id") to -// the subprocess stdin without waiting for a response -- notifications -// have none by definition. Using [StdioTransport.Send] for a -// notification would hang until ctx is cancelled, since Send always -// waits for a reply keyed by the (absent) id. +// Notify writes a notification without waiting for a response. func (t *StdioTransport) Notify(ctx context.Context, body []byte) error { if err := ctx.Err(); err != nil { return err @@ -397,20 +382,9 @@ func (t *StdioTransport) startSubprocess(ctx context.Context) error { return t.commitSpawnedProcess(ctx, cmd, stdin, stdout, false) } -// commitSpawnedProcess installs a freshly spawned subprocess as the -// transport's active one and starts its reader goroutine. spawnProcess runs -// without t.mu held (it performs a real fork/exec), so a concurrent Stop() -// can close t.stopCh and commit StateStopped while a spawn is still in -// flight. commitSpawnedProcess re-checks stopCh under the lock immediately -// before committing: if Stop() already won, the just-spawned subprocess is -// discarded (killed and reaped) instead of clobbering the Stopped state -// Stop() already reported to its own caller. Both startSubprocess (a fresh -// Start()) and attemptRestart's success path (a crash-triggered restart) -// funnel through this single guarded commit point. -// -// resetStartupFailures resets the spawn-failure counter on success; it is -// true only for attemptRestart, since Start() already resets both crash and -// startup-failure counters itself before the first spawn attempt. +// commitSpawnedProcess installs a spawned subprocess and starts its reader, +// unless Stop has already run, in which case the process is killed. +// resetStartupFailures resets the spawn-failure counter. func (t *StdioTransport) commitSpawnedProcess(ctx context.Context, cmd *exec.Cmd, stdin io.WriteCloser, stdout *bufio.Reader, resetStartupFailures bool) error { t.mu.Lock() if t.isStopped() { @@ -615,14 +589,8 @@ func (t *StdioTransport) failAllPendingLocked() { } } -// attemptRestart runs the auto-restart loop with exponential backoff. -// It is called after a subprocess crash and runs until either the -// transport is stopped, max retries (for spawn failures) are exceeded, -// or the subprocess successfully starts. -// -// Crash loops where the process starts but immediately dies are bounded -// by exponential backoff growing up to MaxBackoff. Spawn failures -// (binary not found, permissions, etc.) count against MaxRetries. +// attemptRestart restarts a crashed subprocess with exponential backoff until +// it starts, the transport stops, or spawn failures reach MaxRetries. func (t *StdioTransport) attemptRestart(ctx context.Context) { for { // Check preconditions under lock. @@ -698,16 +666,8 @@ func (t *StdioTransport) computeBackoffLocked() time.Duration { return d } -// writeMessageWithTimeout writes a framed message to w, bounding the write -// itself (not any subsequent response wait) by timeout. A non-positive -// timeout writes with no bound, matching writeMessage directly. -// -// The write runs in a goroutine so a wedged writer (e.g. a full stdin pipe -// because the subprocess has stopped reading) cannot block the caller past -// timeout. Since io.Writer gives no way to cancel an in-flight Write, the -// goroutine is left to finish on its own if the timeout fires; the errCh -// buffer of 1 lets it deliver into a channel nobody is receiving on anymore -// without leaking. +// writeMessageWithTimeout writes a framed message, giving up after timeout. A +// non-positive timeout waits indefinitely. func writeMessageWithTimeout(w io.Writer, data []byte, timeout time.Duration) error { if timeout <= 0 { return writeMessage(w, data) diff --git a/internal/tools/mcp/transport_http.go b/internal/tools/mcp/transport_http.go index 880ffa432..5991bcb4a 100644 --- a/internal/tools/mcp/transport_http.go +++ b/internal/tools/mcp/transport_http.go @@ -28,17 +28,8 @@ func (c HTTPTransportConfig) effectiveTimeout() time.Duration { return c.Timeout } -// HTTPTransport implements [Transport] over HTTP/StreamableHTTP. Each -// [Send] makes an HTTP POST with the JSON-RPC request body and returns the -// JSON-RPC response. [Notify] fires an HTTP POST and discards the response -// body — notifications don't expect a JSON-RPC reply. -// -// This transport is stateless (no persistent connection), so Start/Stop -// are not needed. It satisfies the [Transport] interface directly. Being -// stateless, it has no server→client channel and therefore does not -// implement serverRequestRouter: a server-initiated request (MCP sampling) -// cannot arrive over it at all, rather than arriving and being dropped. -// A deployment that needs sampling must use stdio or SSE. +// HTTPTransport is a stateless HTTP Transport: each Send is a POST. It cannot +// receive server-initiated requests. type HTTPTransport struct { config HTTPTransportConfig client *http.Client diff --git a/internal/tools/mcp/transport_sse.go b/internal/tools/mcp/transport_sse.go index 968768475..f4e857468 100644 --- a/internal/tools/mcp/transport_sse.go +++ b/internal/tools/mcp/transport_sse.go @@ -18,11 +18,8 @@ type SSETransportConfig struct { // SSEEndpoint is the GET URL for the server→client event stream (e.g. // "https://mcp.example.com/sse"). Required. SSEEndpoint string - // MessageEndpoint is the POST URL for client→server messages. When - // empty (the common case), the client discovers it from the - // "endpoint" SSE event sent by the server after connecting — this - // is the MCP SSE spec behaviour; the server's endpoint event carries - // the full POST URL including a session-id query parameter. + // MessageEndpoint is the POST URL for client messages. Empty discovers it + // from the server's "endpoint" event. MessageEndpoint string // Headers are additional HTTP headers sent with every request. Headers map[string]string @@ -522,15 +519,8 @@ func readEndpointEvent(r *bufio.Reader) (string, error) { return strings.TrimSpace(data), nil } -// readSSEEvent reads one complete SSE event from the stream. It returns the -// event type and data payload. SSE fields are: -// -// event: \n -// data: \n -// \n (blank line terminates the event) -// -// Lines beginning with ':' are comments and are skipped. Multiple "data:" -// lines are concatenated with newlines (per the SSE spec). +// readSSEEvent reads one SSE event and returns its type and data. Comment +// lines are skipped; multiple data lines are joined with newlines. func readSSEEvent(r *bufio.Reader) (event, data string, err error) { var dataLines []string for { diff --git a/internal/tools/mcp/types.go b/internal/tools/mcp/types.go index 530231de4..0b50f8748 100644 --- a/internal/tools/mcp/types.go +++ b/internal/tools/mcp/types.go @@ -1,9 +1,4 @@ -// Package mcp implements the Model Context Protocol (MCP) transport layer. -// -// The stdio transport manages an MCP server subprocess over stdin/stdout -// using JSON-RPC 2.0 message framing with Content-Length headers (the same -// framing used by LSP). This is the foundational transport that most local -// MCP servers use. +// Package mcp implements an MCP client over stdio, HTTP and SSE transports. package mcp import "encoding/json"