From a8b3dc55d0d3dfd1e56c0376d2dbbdc40587a39e Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 3 Oct 2026 22:00:43 +1000 Subject: [PATCH] refactor(staterpc,releaseupdate,agentexec,storecontract,worktree): cut comments down to what the code does --- internal/agentexec/loop_runner.go | 30 +-- internal/agentexec/protocol.go | 9 +- internal/agentexec/sampling.go | 17 +- internal/agentexec/subjects.go | 18 +- internal/agentexec/systemlog.go | 42 +--- internal/agentexec/taskevents.go | 20 +- internal/agentexec/toolset.go | 58 +----- internal/domain/storecontract/cursor.go | 10 +- .../domain/storecontract/storecontract.go | 188 ++++------------- internal/infrastructure/staterpc/auth.go | 14 +- internal/infrastructure/staterpc/client.go | 7 +- internal/infrastructure/staterpc/dial.go | 96 +-------- internal/infrastructure/staterpc/server.go | 29 +-- .../infrastructure/staterpc/task_grants.go | 12 +- internal/infrastructure/staterpc/values.go | 53 +---- internal/releaseupdate/command.go | 14 +- internal/releaseupdate/pending_report.go | 9 +- internal/releaseupdate/report_event.go | 16 +- internal/releaseupdate/result.go | 14 +- internal/releaseupdate/service.go | 64 +----- internal/releaseupdate/verify.go | 88 ++------ internal/worktree/worktree.go | 189 +++--------------- 22 files changed, 175 insertions(+), 822 deletions(-) diff --git a/internal/agentexec/loop_runner.go b/internal/agentexec/loop_runner.go index c1863e306..e1cee345f 100644 --- a/internal/agentexec/loop_runner.go +++ b/internal/agentexec/loop_runner.go @@ -40,13 +40,9 @@ type LoopRunner struct { // Limits bounds the size of tool results fed back into the stage. The // zero value applies no limits. Limits ToolLimits - // AllowTools is the agent profile's allowlist over the tools archie adds - // (central/MCP, repository scripts and skill plugins). Empty allows them - // all. A stage's capture tools are how it returns structured results, so - // they are never filtered. The agent loop's built-in file tools are not - // covered either: ai-sdk agentloop registers them itself with no filter - // hook, so they are always present (read-only when the stage asks), and - // restricting them needs an ai-sdk change. + // AllowTools is the profile's allowlist over archie-added tools. Empty allows + // all. Capture tools and agentloop's built-in file tools are never + // filtered. AllowTools []string } @@ -62,16 +58,8 @@ func NewLoopRunner( return runner } -// workspaceToolset names the central-registry toolset a task agent must not -// inherit. Those tools are rooted at the chat workspace, not the task's -// worktree, and they reach the filesystem through their own handlers -- so -// agentloop's ReadOnly and ProtectPaths, which gate only the tools agentloop -// registers itself, do not apply to them. A feasibility stage running -// ReadOnly could otherwise write, and a TDD fix stage could edit the very -// tests it is being graded against. -// -// This is an invariant of task execution rather than a deployment choice, so -// it is not configurable. +// workspaceToolset is the central toolset a task agent never gets: its tools +// work on the chat workspace and bypass ReadOnly and ProtectPaths. const workspaceToolset = "workspace" func (r *LoopRunner) Run(ctx context.Context, workspace string, req Request, report ToolCallReporter) (Result, error) { @@ -357,12 +345,8 @@ func isNonEmptyString(object map[string]json.RawMessage, field string) bool { return ok && json.Unmarshal(raw, &text) == nil && strings.TrimSpace(text) != "" } -// scriptToolSet exposes run_go_script: interpreting a Yaegi Go script -// bundled with a skill or living -// anywhere else in the workspace, and returning what it printed. This is -// how an agent following a skill's instructions ("run scripts/gitleaks.go -// to scan for secrets") actually executes a .go helper without a Go -// toolchain in the sandbox. +// scriptToolSet exposes run_go_script, which runs a Yaegi Go script from the +// workspace and returns its output. func scriptToolSet(workspace string) core.ToolSet { return core.ToolSet{ "run_go_script": core.NewTypedTool( diff --git a/internal/agentexec/protocol.go b/internal/agentexec/protocol.go index f619e74e2..d16b4468e 100644 --- a/internal/agentexec/protocol.go +++ b/internal/agentexec/protocol.go @@ -52,13 +52,8 @@ type CaptureTool struct { RequiredFields []string `json:"required_fields,omitempty"` NonEmptyStrings []string `json:"non_empty_strings,omitempty"` BooleanFields []string `json:"boolean_fields,omitempty"` - // RequiredWhenTrue makes fields required only when a boolean field in - // the same call is true, keyed by that boolean's name. It exists because - // a flat RequiredFields entry cannot express "name a workflow, but only - // when you have said one is needed": the alternatives were forcing a - // meaningless answer on the other branch, or accepting the omission and - // defaulting it, which lets the model skip the decision entirely. - // A named field must also be a non-empty string when the trigger is true. + // RequiredWhenTrue lists fields that must be non-empty strings when the named + // boolean field is true. RequiredWhenTrue map[string][]string `json:"required_when_true,omitempty"` MaxCalls int `json:"max_calls,omitempty"` } diff --git a/internal/agentexec/sampling.go b/internal/agentexec/sampling.go index 55dcabdfd..698cb79d5 100644 --- a/internal/agentexec/sampling.go +++ b/internal/agentexec/sampling.go @@ -15,12 +15,8 @@ import ( // turn-sized output allowance on a single request. const DefaultSamplingMaxTokens = 4096 -// SamplingMessages maps a server's sampling messages onto chat messages. Both -// MCP sampling host paths use it -- the daemon's chat handler and the agent -// worker's task handler -- so the same server is answered the same way -// wherever the client runs. A non-text content block or an unknown role is -// rejected rather than silently dropped: answering from a partial prompt would -// be a wrong answer, not a degraded one. +// SamplingMessages converts sampling messages to chat messages. Non-text +// content and unknown roles are errors. func SamplingMessages(req protocol.SamplingRequest) ([]chat.Message, error) { if len(req.Messages) == 0 { return nil, errors.New("mcp sampling: the request has no messages") @@ -44,13 +40,8 @@ func SamplingMessages(req protocol.SamplingRequest) ([]chat.Message, error) { return messages, nil } -// SamplingMaxTokens bounds a delegated completion to the request's own -// maxTokens, falling back to DefaultSamplingMaxTokens, and never past the -// model's own output ceiling (zero when the ceiling is unknown). A -// reasoning-class model gets no bound at all: its provider rejects the -// `max_tokens` parameter the chat-completions provider emits for a non-zero -// bound. Both the daemon's chat path and the agent worker answer sampling -// with this, so the same server gets the same bound on either path. +// SamplingMaxTokens returns the request's maxTokens or the default, capped at +// the model's ceiling. Reasoning models get no bound. func SamplingMaxTokens(requested, modelCeiling int, reasoning bool) int { maxTokens := requested if maxTokens <= 0 { diff --git a/internal/agentexec/subjects.go b/internal/agentexec/subjects.go index 3e17b62b4..b76880f56 100644 --- a/internal/agentexec/subjects.go +++ b/internal/agentexec/subjects.go @@ -6,10 +6,6 @@ import ( ) // Agent observability subjects. -// -// These belong to this package because it defines what an agent request and -// response mean. They previously sat in the NATS package, which made the -// transport the owner of Archie's agent protocol. const ( // SubjectSystemWildcard matches every task's system subject, for a // daemon subscribing to all of them at once with a single core NATS @@ -46,11 +42,8 @@ func subjectForTask(taskID int64, kind string) string { return subjectAgentPrefix + strconv.FormatInt(taskID, 10) + "." + kind } -// TaskIDFromSystemSubject extracts the task ID from a subject produced by -// SubjectForSystem, for a daemon demuxing a SubjectSystemWildcard -// subscription. Rejects (0, false) for anything that isn't exactly that -// shape, rather than parsing a partial or wrong-kind subject into a -// misleading task ID. +// TaskIDFromSystemSubject extracts the task ID from a SubjectForSystem +// subject. func TaskIDFromSystemSubject(subject string) (int64, bool) { if !strings.HasPrefix(subject, subjectAgentPrefix) || !strings.HasSuffix(subject, subjectSystemSuffix) { return 0, false @@ -63,11 +56,8 @@ func TaskIDFromSystemSubject(subject string) (int64, bool) { return id, true } -// TaskIDFromEventsSubject extracts the task ID from a subject produced by -// SubjectForEvents, for a daemon demuxing a SubjectEventsWildcard -// subscription. Rejects (0, false) for anything that isn't exactly that -// shape, rather than parsing a partial or wrong-kind subject into a -// misleading task ID. +// TaskIDFromEventsSubject extracts the task ID from a SubjectForEvents +// subject. func TaskIDFromEventsSubject(subject string) (int64, bool) { if !strings.HasPrefix(subject, subjectAgentPrefix) || !strings.HasSuffix(subject, subjectEventsSuffix) { return 0, false diff --git a/internal/agentexec/systemlog.go b/internal/agentexec/systemlog.go index 818bc0ed1..0772e96e5 100644 --- a/internal/agentexec/systemlog.go +++ b/internal/agentexec/systemlog.go @@ -10,41 +10,14 @@ import ( "github.com/samcharles93/archie-core/internal/logging" ) -// LogPublisher is the minimal capability SystemLogHandler needs: fire a -// message at a subject without waiting for a reply. Declared here rather -// than taking *nats.go's Conn or eventbus.Bus so the handler can be tested -// with a fake and never gains capabilities (subscribe, request/reply) it has -// no use for. *nats.Conn already satisfies this with no adapter needed. +// LogPublisher publishes a message to a subject without waiting. type LogPublisher interface { Publish(subject string, data []byte) error } -// SystemLogHandler tees slog records to a wrapped handler -- normally the -// agent's own stderr, kept for an operator attached to a live container -- -// and additionally publishes each one, JSON-encoded as a logging.Entry, to -// SubjectForSystem(taskID): the return channel documented in subjects.go for -// "log dumps, health... observability" that previously had no publisher. -// -// The wire payload is a marshaled logging.Entry -- {"time","level","msg", -// "fields":{...}} -- meant to be round-tripped with json.Unmarshal straight -// back into a logging.Entry. This is deliberately NOT the same shape -// logging.decode() parses: decode() reads raw slog JSON *log lines* off -// disk, where every non-{time,level,msg} key sits at the top level and -// decode() moves it into Fields itself. Handing decode() this payload -// instead of json.Unmarshal would nest everything one level too deep, under -// a literal "fields" key, and silently lose every real field name. A future -// consumer of this subject must unmarshal directly -// into logging.Entry, not call decode() on these bytes. -// -// Publishing is fire-and-forget. A core NATS Publish call is already -// non-blocking -- it queues to the connection's outbound buffer and returns, -// and the client itself drops writes rather than blocking once its -// reconnect buffer is full -- so this handler does not duplicate that -// behaviour with a second, home-grown bounded queue. A publish or marshal -// failure is reported once via the wrapped handler and then swallowed: log -// shipping must never block or fail the run it is reporting on, and a dead -// NATS connection is already visible through every stage subsequently -// failing to report its own result. +// SystemLogHandler writes slog records to a wrapped handler and publishes +// each as a JSON logging.Entry to SubjectForSystem(taskID). Publish failures +// are reported once and never block. type SystemLogHandler struct { next slog.Handler pub LogPublisher @@ -86,12 +59,7 @@ func (h *SystemLogHandler) Handle(ctx context.Context, record slog.Record) error return h.next.Handle(ctx, record) } -// warnAtMostOnce reports the first system-log delivery failure (marshal or -// publish, either way this record's own history is now missing on the -// daemon side) via the wrapped handler, then goes quiet -- a dead -// connection would otherwise turn every subsequent line into a second -// failure notice on stderr, drowning out the output an operator is trying -// to read. +// warnAtMostOnce reports the first publish failure only. func (h *SystemLogHandler) warnAtMostOnce(ctx context.Context, at time.Time, cause error) { h.warnOnce.Do(func() { warning := slog.NewRecord(at, slog.LevelWarn, diff --git a/internal/agentexec/taskevents.go b/internal/agentexec/taskevents.go index 593d45f32..54ecc5cd8 100644 --- a/internal/agentexec/taskevents.go +++ b/internal/agentexec/taskevents.go @@ -7,27 +7,13 @@ import ( "github.com/samcharles93/archie-core/internal/events" ) -// EventPublisher is the minimal capability needed to ship a task's -// observability events to the daemon over NATS: fire a message at a subject -// without waiting for a reply. Declared here rather than taking *nats.go's -// Conn so ForwardTaskEvents can be tested with a fake. *nats.Conn already -// satisfies this with no adapter needed. +// EventPublisher publishes a message to a subject without waiting. type EventPublisher interface { Publish(subject string, data []byte) error } -// ForwardTaskEvents relays every event published on sub to pub, JSON-encoded, -// on SubjectForEvents(taskID), until sub is closed. -// -// A workflow.TaskContext built inside an archie-agent worker publishes to an -// in-process *events.Bus the daemon cannot see -- the worker and the daemon -// are separate processes connected only by NATS. This is the bridge that -// makes those Emit calls (stage progress, outcome, parking) reach the -// daemon's events table and dashboard timeline. -// -// A marshal or publish failure is logged and the loop continues: one missing -// event must never abort the ones after it, and event shipping must never -// block or fail the workflow run it is reporting on. +// ForwardTaskEvents publishes every event from sub to SubjectForEvents(taskID) +// until sub closes. Failures are logged. func ForwardTaskEvents(sub *events.Sub, pub EventPublisher, taskID int64, log *slog.Logger) { subject := SubjectForEvents(taskID) for e := range sub.C { diff --git a/internal/agentexec/toolset.go b/internal/agentexec/toolset.go index f4bee842e..076ff54ba 100644 --- a/internal/agentexec/toolset.go +++ b/internal/agentexec/toolset.go @@ -13,23 +13,14 @@ import ( "github.com/samcharles93/archie-core/internal/tools" ) -// ToolLimits are the configured result limits for one chat turn or agent -// stage. It holds only settings, never accumulated state, so it is safe to -// store on a long-lived runner and share across tasks. -// -// A negative limit means no limit; see config.ToolPolicy for why zero cannot -// carry that meaning. +// ToolLimits are the tool result limits for one turn or stage. A negative +// limit means none. type ToolLimits struct { MaxResultChars int SpillDir string } -// EnsureSpillDir creates the spill directory if one is configured. -// -// Call it once at startup. Without it the directory never exists, and a -// failed spill write falls back to inline truncation -- spilling looks -// configured and does nothing. An empty SpillDir is not an error: it -// selects inline truncation deliberately. +// EnsureSpillDir creates the spill directory if one is set. func (l ToolLimits) EnsureSpillDir() error { if l.SpillDir == "" { return nil @@ -137,21 +128,9 @@ func (o ToolSetOptions) excludes(entry tools.ToolEntry) bool { return slices.Contains(o.ExcludeToolsets, entry.Toolset) } -// BuildToolSet converts every currently-available entry in reg into an -// ai-sdk core.ToolSet, ready to pass as core.GenerateOptions.Tools for a -// multi-step chat turn. A nil registry (memory/tools disabled) returns -// an empty set. Invalid availability callbacks and dynamic schemas return -// errors instead of panicking or silently hiding an advertised tool. -// -// core.Tool.Execute exchanges JSON-encoded strings with the model; -// tools.Handler exchanges a decoded map. The returned Execute functions -// do the JSON <-> map translation and surface decode failures as errors -// rather than silently dropping malformed model input. -// -// This is the only path from a registered tools.ToolEntry to a model, so it is -// also where result limits are enforced. The model runtime owns the tool loop -// and decides what to invoke, so archie cannot gate a batch -- but it builds -// every Execute closure here, which makes per-call accounting reachable. +// BuildToolSet converts reg's available entries into an ai-sdk ToolSet, +// translating JSON input and enforcing result limits. A nil registry returns +// an empty set. func BuildToolSet(reg *tools.Registry, opts ToolSetOptions) (aicore.ToolSet, error) { if reg == nil { return aicore.ToolSet{}, nil @@ -159,13 +138,7 @@ func BuildToolSet(reg *tools.Registry, opts ToolSetOptions) (aicore.ToolSet, err return BuildToolSetFrom(reg.All(), opts) } -// BuildToolSetFrom converts a loose slice of entries under the same rules as -// [BuildToolSet]. -// -// It exists for tools that are bound per turn rather than registered globally -// -- the task tools carry the calling gateway's identity, so there is one set -// of them per gateway and they cannot live in the process-wide registry. Pass -// the same ToolSetOptions to both calls so a single turn shares one budget. +// BuildToolSetFrom is BuildToolSet over a slice of entries. func BuildToolSetFrom(entries []tools.ToolEntry, opts ToolSetOptions) (aicore.ToolSet, error) { set := aicore.ToolSet{} for _, entry := range entries { @@ -223,14 +196,8 @@ func safeResolvedSchema(entry tools.ToolEntry) (schema tools.JSONSchema, err err return entry.ResolvedSchema(), nil } -// toolExecute adapts a tools.ToolEntry's Handler to core.Tool's -// Execute(ctx, jsonInput string) (jsonOutput string, err error) shape, and -// applies the turn's result accounting. -// -// The cap is applied to the marshalled payload rather than to the handler's -// return value, because the marshalled form is what actually reaches the -// model: JSON escaping can change the length materially, so capping the Go -// value would bound the wrong string. +// toolExecute adapts a ToolEntry's handler to an ai-sdk Execute and caps the +// marshalled result. func toolExecute(entry tools.ToolEntry, opts ToolSetOptions) func(context.Context, string) (string, error) { limit := opts.resultLimit(entry) return func(ctx context.Context, input string) (result string, err error) { @@ -275,11 +242,8 @@ func requireApproval(ctx context.Context, entry tools.ToolEntry, opts ToolSetOpt } decision, err := opts.Approval.RequestApproval(approveCtx, entry.Name, desc) if err != nil { - // Distinguish a tool-level timeout (our own deadline) from a - // turn-level cancellation (/stop). A turn cancellation must - // propagate as a context error; a tool timeout must surface as - // a plain error so the model can report it instead of the turn - // aborting. + // A tool timeout is a plain error; a turn cancellation stays a context + // error. if (errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled)) && ctx.Err() == nil { return fmt.Errorf("tool %s: approval timed out after %v", entry.Name, tools.ToolApprovalTimeout) } diff --git a/internal/domain/storecontract/cursor.go b/internal/domain/storecontract/cursor.go index 62e300baa..25b241f4c 100644 --- a/internal/domain/storecontract/cursor.go +++ b/internal/domain/storecontract/cursor.go @@ -7,14 +7,8 @@ import ( "time" ) -// EventCursorLayout is the fixed-width UTC layout every persisted event's at -// column and every EventsSince cursor is built with. Fixed width is the whole -// point: time.RFC3339Nano trims trailing zeros, so a whole-second row -// ("...05Z") and a full-precision row ("...05.123456789Z") would compare out -// of chronological order as strings. With nine fractional digits always -// present, lexicographic order is chronological order. It mirrors edastore's -// capturedAtLayout, which exists for the same reason; the two stores now share -// this rule. +// EventCursorLayout is the fixed-width UTC layout for event times and cursors, +// so string order is time order. const EventCursorLayout = "2006-01-02T15:04:05.000000000Z" // cursorSeparator joins the sort key and the row id inside a cursor. The sort diff --git a/internal/domain/storecontract/storecontract.go b/internal/domain/storecontract/storecontract.go index 777a6d73e..ef606efa2 100644 --- a/internal/domain/storecontract/storecontract.go +++ b/internal/domain/storecontract/storecontract.go @@ -1,16 +1,5 @@ -// Package storecontract is the ratified State Store contract as its -// consumers reference it: the producer-owned daemon/webui/intake store -// surfaces. It carries no -// persistence -- internal/infrastructure/postgres and *staterpc.Client (the -// remote adapter) both satisfy these interfaces -- -// so a process that only holds the contracts, such as the archie-ui -// dashboard process, can reference them without linking the SQL -// implementation. -// -// It is hand-written and lives in the domain layer (which owns required -// contracts), NOT under internal/contracts: that tree is the buf generate -// output and is wiped and regenerated by tools/proto.sh, which would -// delete a hand-written file there. +// Package storecontract defines the State Store interfaces its consumers use, +// without an implementation. package storecontract import ( @@ -57,56 +46,31 @@ type TaskLifecycle interface { RecoverStale(ctx context.Context) (int64, error) } -// TaskParker is the classified park write, kept off TaskLifecycle so that -// interface stays under the repo's 8-method cap. It mirrors Transition with -// a park class attached (taskstate.ParkClass); the class is normalized -// store-side, so an empty or unknown value becomes needs_human rather than -// an error -- a park that predates classification must not fail because its -// caller did not know the vocabulary. +// TaskParker parks a task with a park class. Unknown classes become +// needs_human. type TaskParker interface { ParkTask(ctx context.Context, taskID int64, from, detail, class string) error } -// StepRecorder records the StepExecutions of one running WorkflowExecution. -// It is deliberately separate -// from TaskLifecycle, which is exactly at the interfacebloat cap: the same -// two methods also sit on the workflow engine's mid-run facade (task.Store), -// which is what a container's run credential calls. +// StepRecorder records a running execution's steps. type StepRecorder interface { StartStep(ctx context.Context, s task.StepStart) (int64, events.Event, error) FinishStep(ctx context.Context, s task.StepFinish) (events.Event, error) } -// ExecutionCanceller is the one cancel path: -// one -// transaction moves every non-terminal StepExecution of the execution's -// current attempt to cancelled and the execution itself to the status the -// operator action names (parked or closed_wont_do, as the transition table -// routes). The daemon then cancels the in-memory context that was delivering -// the run: the store is the record of cancellation, the context cancel is -// only the delivery mechanism, so a lost cancel still leaves the store -// correct and the worker's next step write fails ErrStaleTransition. It is a -// dashboard, API and dispatch action, so a task-scoped grant never reaches -// it; the Authorizer decides. +// ExecutionCanceller cancels an execution and its current attempt's open +// steps in one transaction. type ExecutionCanceller interface { CancelExecution(ctx context.Context, taskID int64, reason, to string) ([]int64, error) } -// StepReader lists one execution's recorded steps -- the dashboard run -// detail's read. Separate from -// StepRecorder: this is a dashboard/API/dispatch action (Authorizer: read on -// the run), never task-scoped-grant callable the way StartStep/FinishStep -// are. +// StepReader lists one execution's recorded steps. type StepReader interface { ListSteps(ctx context.Context, executionID int64, attempt int) ([]task.StepExecution, error) } -// HarnessSecretStore persists one org's OAuth token set per credential binding -// service. The setup terminal writes the first capture (an `update` action on -// the secret, Authorizer-gated); the egress proxy's token-endpoint interception -// overwrites it on every refresh with no Authorizer check of its own -- it acts -// as the run, not as an operator. Encrypted at rest under its own domain -// separator. +// HarnessSecretStore stores one org's OAuth token set per credential binding +// service, encrypted at rest. type HarnessSecretStore interface { GetHarnessSecret(ctx context.Context, org, service string) (harnesssecret.Secret, error) PutHarnessSecret(ctx context.Context, s harnesssecret.Secret) error @@ -127,17 +91,9 @@ type TaskRetryer interface { RetryTask(ctx context.Context, taskID int64, fromStatus, workflow, retryMode string) error } -// ReviewGateResponder is the operator's answer to the review gate: -// one guarded write -// beside RetryTask/BeginRemediation that fills in the review gate document -// the caller computed (the outcome, the selection or the instructions), and -// -- for a re-review only -- increments rereview_rounds and requeues, under -// one transition-table guard and one from-status check. A re-review that has -// spent its rounds is refused with ErrRereviewCapReached and writes nothing, -// so the cap cannot be raced past; an approve requeues with no counter. -// -// The caller computes the gate document from the task row it read; the write -// is the only place rereview_rounds ever increments. +// ReviewGateResponder records the operator's review-gate answer. A re-review +// increments rereview_rounds and requeues; one past the cap returns +// ErrRereviewCapReached and writes nothing. type ReviewGateResponder interface { RespondReviewGate(ctx context.Context, taskID int64, fromStatus, gate string, rereview bool, maxRounds int) error } @@ -178,34 +134,20 @@ type TaskEvents interface { Close() error } -// CaptureStore persists unbound inbound webhook captures -- events with no -// workflow binding and no task association. Deliberately separate from -// TaskStore: a consumer that only needs capture (the intake HTTP handler) -// should not acquire the full task-lifecycle surface, mirroring why -// TaskArchiver is split out above. +// CaptureStore persists inbound webhook captures. type CaptureStore interface { InsertCapture(ctx context.Context, c CapturedEvent, retention time.Duration, maxEvents int) (string, error) ListCaptures(ctx context.Context, limit int) ([]CapturedEvent, error) } -// ConfigSnapshotStore holds the running configuration as the dashboard renders -// it: the owner of configuration publishes, the process that displays it reads. -// Separate from every other store surface because it is the only one whose -// writer is the daemon and whose reader is the UI, and because a task-scoped -// credential must never reach the writer. +// ConfigSnapshotStore holds the published configuration view. type ConfigSnapshotStore interface { PutConfigSnapshot(ctx context.Context, snapshot ConfigSnapshot) error ConfigSnapshot(ctx context.Context) (ConfigSnapshot, bool, error) } -// ChannelStatusStore holds channel runtime state as the process HOSTING the -// channels observes it. Same split as ConfigSnapshotStore and for the same -// reason: the writer is the Messaging Service, the reader is the UI process, and -// a task-scoped credential must reach neither. -// -// It is runtime state rather than a settings document -- a channel that is -// failed is not a document anybody edits -- which is why it is not a -// ControlPlaneService resource kind. +// ChannelStatusStore holds channel runtime state published by the process +// hosting the channels. type ChannelStatusStore interface { // PutChannelStatus records the reporting process's whole set: a channel it no // longer reports is removed rather than left behind, because a stale "running" @@ -253,11 +195,8 @@ type EventTypeStore interface { ListEventTypes(ctx context.Context) ([]eventtype.EventType, error) } -// BindingStore persists playbook bindings: CRUD and the draft -> -// pending_approval -> armed state machine. Split off from TaskStore and -// MappingStore so the webui binding editor does not acquire the full task or -// mapping surfaces. Dispatch-time helpers live in BindingDispatcher; the daemon -// depends on both. See +// BindingStore persists bindings and their draft -> pending_approval -> +// armed states. type BindingStore interface { InsertBinding(ctx context.Context, b binding.Binding) (string, error) GetBinding(ctx context.Context, id string) (*binding.Binding, error) @@ -267,11 +206,8 @@ type BindingStore interface { ApproveBinding(ctx context.Context, id string) error } -// SourceStore persists capture sources and their signing setting. -// The path is the key and never -// changes. Secrets cross this surface in plaintext; the store encrypts them -// at rest. Signing transitions are decided by the source domain and written -// with an expected-from guard, so two operators cannot race an approval. +// SourceStore persists capture sources keyed by path. Secrets are encrypted +// at rest; signing transitions use an expected-from guard. type SourceStore interface { InsertSource(ctx context.Context, s source.Source) error // GetSource returns (nil, nil) for an unknown path. @@ -281,12 +217,8 @@ type SourceStore interface { SetSourceSecret(ctx context.Context, path, secret string) error } -// BindingDispatcher is the dispatch-loop surface over the bindings store: -// look up armed bindings for HMAC verification, list captures that still -// need dispatching, and record the at-most-once ledger row. The -// dispatcher's task-creation call (EnqueueBindingTask) lives on a separate -// BindingTaskCreator interface so the dispatcher does not depend on the -// full TaskStore just to spawn one task. +// BindingDispatcher looks up armed bindings, lists undispatched captures and +// records dispatches. type BindingDispatcher interface { ArmedBindingsForSource(ctx context.Context, source string) ([]binding.Binding, error) RecordDispatch( @@ -310,43 +242,19 @@ type BindingTaskCreator interface { EnqueueBindingTask(ctx context.Context, owner, repo, title, body, wf, identity, bindingID string, bindingVersion int, inputs map[string]any) (*task.Task, error) } -// WorkflowCaller is the consumer surface a workflow.call step crosses to -// start its callee and read it back while waiting. -// It is the workflow engine's own task.Caller contract, satisfied by the -// PostgreSQL store and *staterpc.Client alike -- the same shape as -// workflow.Store. The caller task ID is explicit so both the wire grant and -// the store's own row check answer the same question: is this call this -// task's call? +// WorkflowCaller starts a workflow.call callee and reads it back. type WorkflowCaller = task.Caller -// PlaybookDispatcher is the idempotency-ledger surface for side-effecting -// playbook actions. -// RecordPlaybookDispatch writes the (playbook, version, event, action) row -// BEFORE the action's side effect fires -- the deliberate reverse of -// BindingDispatcher.RecordDispatch -- so a duplicate returns -// ErrAlreadyDispatched and the caller skips the invoke rather than repeating -// a non-revocable side effect. DeletePlaybookDispatches deletes one -// playbook's ledger rows on explicit request only: a playbook file missing at -// boot may be an unmounted directory, and reclaiming on that would let -// redelivered events fire again. There is deliberately no *sql.Tx: any -// transaction stays server-side inside the store. +// PlaybookDispatcher records a playbook action dispatch before its side +// effect runs, returning ErrAlreadyDispatched for a duplicate. +// DeletePlaybookDispatches deletes one playbook's records. type PlaybookDispatcher interface { RecordPlaybookDispatch(ctx context.Context, playbookID, playbookVersion, eventID, actionID string) error DeletePlaybookDispatches(ctx context.Context, playbookID string) error } -// TaskLogStore reads one task attempt's persisted log. Deliberately separate -// from TaskQueries: the log is not a row, it is a file the logging package -// owns the format of, and a process that can read the task board should not -// have to acquire a log reader to do it. The dashboard's UI process is the -// consumer this exists for -- it holds no daemon-local file handle, so the -// read crosses the State Store contract. -// -// Found=false with a nil error is the not-found convention every read here -// uses, and it is load-bearing: "this attempt has no log" is not "this -// process cannot read logs". The second one is an error -// (logging.ErrTaskLogsUnavailable), because a caller that conflates them -// reports a configuration change where none is needed. +// TaskLogStore reads one task attempt's log. Found=false means no log; +// ErrTaskLogsUnavailable means this process cannot read logs. type TaskLogStore interface { // TaskLog returns a page of one attempt's decoded log. attempt 0 selects // the task's current attempt. @@ -382,14 +290,8 @@ type CapturedEvent struct { // a valid signature, or a source approved to take unsigned events. func (c CapturedEvent) Dispatchable() bool { return c.Authenticated || c.Unsigned } -// ConfigSnapshot is the running configuration as the dashboard renders it, -// published by whoever owns configuration for whoever displays it. -// -// Document is opaque here on purpose: its shape belongs to the producer and -// the page that reads it, not to storage, and Schema names that shape so a -// reader can refuse a document it does not understand. It is secret-free by -// construction at the producer (the projection carries an API key's -// environment variable name and whether it resolved, never a value). +// ConfigSnapshot is the published, secret-free configuration view. Schema +// names Document's shape. type ConfigSnapshot struct { Schema string Document []byte @@ -410,15 +312,9 @@ type ChannelStatus struct { ObservedAt time.Time } -// ApplyStatus is one process's report about one control-plane resource kind. -// -// AppliedVersion is the version that process is running. Error is set when the -// process could not apply what the store returned, and leaves AppliedVersion -// at the last version it did apply, so a rejected edit never erases the fact -// that an older one is live. ReportedAt is re-stamped on an interval: a record -// older than the staleness window belongs to a process that has stopped -// running, which is the only way this surface can tell a live process from a -// dead one. +// ApplyStatus is one process's report on one resource kind. On error, +// AppliedVersion stays at the last applied version. ReportedAt is +// re-stamped periodically. type ApplyStatus struct { Process string `json:"process"` Kind string `json:"kind"` @@ -463,12 +359,8 @@ var ( // ErrStaleTransition is returned when a task transition's expected // from status does not match the task's current status. ErrStaleTransition = errors.New("store: stale transition: task status does not match expected from status") - // ErrIllegalTransition is returned when a task's current status and the - // requested status form a pair the shared taskstate transition table - // does not route: the move - // would have executed against a truthful from, but the table forbids - // it. Distinct from ErrStaleTransition, which covers a from that does - // not match the row's actual status. + // ErrIllegalTransition is returned when the transition table does not allow + // the status pair. ErrIllegalTransition = errors.New("store: illegal transition: status pair is not in the transition table") // ErrInvalidStep is returned when a step-execution request names a kind the // store does not record or a step whose identifying fields do not resolve. @@ -482,12 +374,8 @@ var ( // ErrBindingTransition is returned when a binding state transition is // rejected by the draft -> pending_approval -> armed machine. ErrBindingTransition = errors.New("store: binding state transition rejected") - // ErrAlreadyDispatched is returned when a dedup ledger already holds the - // dispatch key: binding_dispatches for the (binding_id, capture_id) pair, - // or playbook_dispatches for the (playbook_id, playbook_version, - // event_id, action_id) tuple. Both ledgers are at-most-once guarantees; - // the sentinel is shared so a caller treats "already recorded" the same - // way across the two surfaces. + // ErrAlreadyDispatched is returned when a dispatch ledger already holds the + // key. ErrAlreadyDispatched = errors.New("store: binding already dispatched for capture") // ErrCallNotYours is returned when a workflow.call status read names a // task that is not a callee of the calling task, or the caller itself diff --git a/internal/infrastructure/staterpc/auth.go b/internal/infrastructure/staterpc/auth.go index 31b654993..5a9bdc411 100644 --- a/internal/infrastructure/staterpc/auth.go +++ b/internal/infrastructure/staterpc/auth.go @@ -11,24 +11,14 @@ import ( // Metadata, never a URL. const tokenMetadataKey = "state-store-token" -// UnaryClientTokenInterceptor attaches token to every outgoing call's -// metadata under tokenMetadataKey. One token covers a task's container -// lifetime so it does not need to be -// refreshed mid-connection. Used by the agent's long-lived client -// connection to the State Store's bridge-address listener. +// UnaryClientTokenInterceptor attaches token to every outgoing call. func UnaryClientTokenInterceptor(token string) grpc.UnaryClientInterceptor { return func(ctx context.Context, method string, req, reply any, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error { return invoker(metadata.AppendToOutgoingContext(ctx, tokenMetadataKey, token), method, req, reply, cc, opts...) } } -// StreamClientTokenInterceptor attaches token to the outgoing stream's -// context, covering the server-streaming read RPCs (StreamCaptures, -// StreamUndispatchedCaptures) the unary interceptor cannot see. Without it -// those calls reach a token-protected listener with no credential and the -// server's stream interceptor refuses them, leaving the capture batch reads -// -- the ones moved onto streams precisely so a large batch crosses -- with -// no working path. +// StreamClientTokenInterceptor attaches token to every outgoing stream. func StreamClientTokenInterceptor(token string) grpc.StreamClientInterceptor { return func(ctx context.Context, desc *grpc.StreamDesc, cc *grpc.ClientConn, method string, streamer grpc.Streamer, opts ...grpc.CallOption) (grpc.ClientStream, error) { return streamer(metadata.AppendToOutgoingContext(ctx, tokenMetadataKey, token), desc, cc, method, opts...) diff --git a/internal/infrastructure/staterpc/client.go b/internal/infrastructure/staterpc/client.go index 4a6ddb3b9..eb0436fc2 100644 --- a/internal/infrastructure/staterpc/client.go +++ b/internal/infrastructure/staterpc/client.go @@ -114,11 +114,8 @@ func (c *Client) Transition(ctx context.Context, taskID int64, from, to, detail return unmapError(err) } -// StartStep and FinishStep record the run's step executions -// under the run credential, which -// the State Store's grant interceptor scopes to the execution the requests -// name. Each returns the transition's persisted event for the caller's -// post-commit publish. +// StartStep and FinishStep record step executions and return the persisted +// event. func (c *Client) StartStep(ctx context.Context, s task.StepStart) (int64, events.Event, error) { r, err := c.client.StartStep(ctx, &pb.StartStepRequest{ ExecutionId: s.ExecutionID, Attempt: int64(s.Attempt), diff --git a/internal/infrastructure/staterpc/dial.go b/internal/infrastructure/staterpc/dial.go index d5eac0c34..5da0ff34b 100644 --- a/internal/infrastructure/staterpc/dial.go +++ b/internal/infrastructure/staterpc/dial.go @@ -11,16 +11,9 @@ import ( "google.golang.org/grpc/keepalive" ) -// Dial returns a State Store contract client for target, applying the -// transport security boundary: a -// loopback target dials insecure with no credential, while a non-loopback -// target requires a bearer token and fails closed without one. The returned -// cleanup closes the connection; Client.Close is a no-op because the store -// service owns its own DB lifecycle. -// -// The rule lives here rather than in a composition root so the server side -// (which decides whether to install the token interceptors) and every client -// that dials it share one implementation. +// Dial returns a State Store client for target. A loopback target dials +// insecure; any other target requires a token. The cleanup closes the +// connection. func Dial(target, token string, options ...grpc.DialOption) (*Client, func(), error) { target = strings.TrimSpace(target) if target == "" { @@ -38,24 +31,7 @@ func Dial(target, token string, options ...grpc.DialOption) (*Client, func(), er } opts := []grpc.DialOption{ grpc.WithTransportCredentials(insecure.NewCredentials()), - // Client keepalive. grpc-go's default client keepalive time is - // infinity (internal/transport.defaultClientKeepaliveTime), so a - // connection that half-opens under an idle client -- peer gone, socket - // still ESTABLISHED -- produces no error here. That is load-bearing for - // this dial because the control-plane Watch stream is silent by design - // while the watched resource's version is unchanged - // (internal/app/controlplane's Watch): with neither peer writing, - // neither notices, and the caller's watch stays frozen for the life of - // the process with no error and no log. - // - // Time 10s is the soonest a dead peer can be detected: gRPC clamps a - // client ping interval up to internal.KeepaliveMinPingTime (10s), and - // 10s of connection-level silence costs one HTTP/2 PING, which is far - // below the traffic this link already carries (the store service polls - // its store every 250ms per watch). Timeout 5s bounds detection at - // ~15s: a PING the peer does not ACK within 5s tears the transport - // down, turning a half-open connection into a stream error the caller - // can act on. + // Keepalive detects a dead peer on an otherwise silent watch stream. grpc.WithKeepaliveParams(ClientKeepaliveParams()), } if token != "" { @@ -75,18 +51,8 @@ func Dial(target, token string, options ...grpc.DialOption) (*Client, func(), er return NewClient(conn), func() { _ = conn.Close() }, nil } -// ClientKeepaliveParams are the client keepalive settings Dial installs; see -// Dial's option comment for why each value is what it is. PermitWithoutStream -// is deliberately left false (the library default): the pings this dial needs -// are covered by an active stream, and pinging a connection with no streams is -// what a peer's keepalive enforcement policy records as a ping strike -- -// against the State Store's default policy a streamless ping draws GOAWAY -// too_many_pings and would churn connections that are healthy today. -// -// It is the dialer's half of the keepalive agreement with -// ServerKeepalivePolicy, so it is exported: the side that installs a server -// option reads the interval this dialer actually pings at from here rather -// than restating it. +// ClientKeepaliveParams are Dial's keepalive settings: ping after 10s idle, +// 5s timeout, no pings without streams. func ClientKeepaliveParams() keepalive.ClientParameters { return keepalive.ClientParameters{ Time: 10 * time.Second, @@ -100,50 +66,13 @@ func ClientKeepaliveParams() keepalive.ClientParameters { // ServerKeepaliveOption carries the arithmetic. const serverKeepaliveMinTime = 5 * time.Second -// ServerKeepaliveOption returns the server half of the keepalive agreement -// Dial's clients enter, for the composition that serves the State Store -// contract to install on its grpc.Server (internal/app/archied's -// stateStoreServerOpts installs it on every listener). -// -// The two sides have to agree on one number. A ping arriving less than -// EnforcementPolicy.MinTime after the previous ping is a strike, and the server -// answers the third strike with GOAWAY too_many_pings (maxPingStrikes is 2; a -// write on that transport is what resets the counter). grpc's default policy -// MinTime is 5 minutes while the client above pings every 10 seconds, so a -// connection that carries no write for ~40s -- which is what a watch is while -// the watched resource's version is unchanged -- is torn down where before the -// client keepalive existed it stayed up. A process that writes on the same -// transport every 30s (the apply-status re-stamp, applystatus.RestampInterval) -// resets the counter often enough to hide this; an idle connection is what it -// kills, and a keepalive that disconnects is worse than no keepalive. -// -// MinTime is 5s, half the client's ping interval. The client's interval is the -// larger of its Time and grpc's KeepaliveMinPingTime clamp -- 10s, so no caller -// can ask for faster pings -- and its keepalive loop arms its timer Time ahead -// and re-arms it only later, on read activity, so consecutive pings are never -// closer than ~10s apart. A 5s floor thus separates every ping from a strike by -// a factor of two, worth more than Go's timer granularity and any scheduling -// delay, which can only push pings further apart. A MinTime of 10s would sit -// exactly on the boundary the clamp already enforces, where a ping a -// microsecond early is a strike; 5 minutes is the defect itself. -// -// The floor is not a blanket exemption: a ping arriving less than 5s after the -// previous one, and any ping on a connection with no stream, still strikes. -// PermitWithoutStream stays false, matching the client, which never pings a -// connection with no streams: every client this server has is a staterpc.Dial -// -- the daemon's control-plane client, the archie-ui dashboard, archie- -// messaging and the archie-agent container -- so permitting streamless pings -// would only relax a setting none of them exercises. +// ServerKeepaliveOption returns the server keepalive enforcement matching +// Dial's clients: pings at least 5s apart are allowed while a stream is open. func ServerKeepaliveOption() grpc.ServerOption { return grpc.KeepaliveEnforcementPolicy(ServerKeepalivePolicy()) } -// ServerKeepalivePolicy returns the policy ServerKeepaliveOption installs as a -// value. A grpc.ServerOption is a closure over unexported grpc state with no -// accessor, so the option cannot be read back once built; this value is -// therefore the handle the agreement is held to -- a caller installing the -// option can assert the policy it is built from, and ClientKeepaliveParams -// gives the interval that policy must stay below. +// ServerKeepalivePolicy returns the policy ServerKeepaliveOption installs. func ServerKeepalivePolicy() keepalive.EnforcementPolicy { return keepalive.EnforcementPolicy{ MinTime: serverKeepaliveMinTime, @@ -151,11 +80,8 @@ func ServerKeepalivePolicy() keepalive.EnforcementPolicy { } } -// TargetIsLoopback reports whether addr's host is a loopback address. Both -// literal loopback IPs (127.0.0.1, ::1) and the "localhost" hostname count; -// everything else (including the wildcard 0.0.0.0 and DNS names) is treated -// as network-reachable and therefore non-loopback. It applies to a listen -// address and a dial target alike -- the same host decides both. +// TargetIsLoopback reports whether addr's host is a loopback IP or +// "localhost". func TargetIsLoopback(addr string) (bool, error) { host, _, err := net.SplitHostPort(addr) if err != nil { diff --git a/internal/infrastructure/staterpc/server.go b/internal/infrastructure/staterpc/server.go index 6548e2881..121bfdb2b 100644 --- a/internal/infrastructure/staterpc/server.go +++ b/internal/infrastructure/staterpc/server.go @@ -43,12 +43,7 @@ var ( errBindingTaskCreatorUnavailable = status.Error(codes.Unavailable, "binding task creator unavailable") errPlaybookDispatcherUnavailable = status.Error(codes.Unavailable, "playbook dispatcher unavailable") errWorkflowCallerUnavailable = status.Error(codes.Unavailable, "workflow caller unavailable") - // errTaskLogsUnavailable is the "this process cannot read task logs at - // all" answer, and it is deliberately distinct from a found=false read - // result: only the first is a deployment matter. A dashboard that receives - // this reports that the log cannot be read here; it must never turn it - // into "task logging was not enabled for this run", which is what the - // absent-handle path used to do. + // errTaskLogsUnavailable reports that this process cannot read task logs. errTaskLogsUnavailable = status.Error(codes.Unavailable, msgTaskLogsUnavailable) ) @@ -129,12 +124,8 @@ type Deps struct { // Denials records and lists denial records. Optional: nil disables the // pair with codes.Unavailable. Denials access.DenialStore - // TaskLogs reads one task attempt's persisted log out of the state - // directory this process owns. Optional, and nil is the honest default for - // a store service that shares no state directory with the daemon: - // ReadTaskLog then answers codes.Unavailable, which the dashboard reports - // as "this process cannot read logs" rather than as "this attempt has no - // log". Conflating those two is the bug this contract exists to fix. + // TaskLogs reads task attempt logs. Nil answers ReadTaskLog with + // Unavailable. TaskLogs storecontract.TaskLogStore Log *slog.Logger } @@ -165,13 +156,7 @@ func (s *server) logErr(rpc string, err error) error { return mapError(err) } -// validationFailure answers a write the owning feature's own Validate refused. -// The domain-managed kinds (identities, captures, mappings, bindings) are -// advertised in the control-plane catalog but are not stored as generic -// documents, so it is these RPC handlers -- not the catalog -- that must apply -// the feature's rule. The rule itself stays in the domain package; this only -// translates its error for the wire, and it is deliberately not codes.Internal -// (an unjudged value is the caller's fault, not this process's). +// validationFailure maps a domain validation error to InvalidArgument. func validationFailure(err error) error { return status.Error(codes.InvalidArgument, err.Error()) } @@ -221,11 +206,7 @@ func (s *server) Transition(ctx context.Context, r *pb.TransitionRequest) (*pb.T return &pb.TransitionResponse{}, nil } -// StartStep and FinishStep are the step-execution writes. -// Each is the store's own -// transaction -- guarded row write plus the event row -- and the store's -// response carries the persisted event back for the caller's post-commit -// publish. +// StartStep and FinishStep write a step transition and return its event. func (s *server) StartStep(ctx context.Context, r *pb.StartStepRequest) (*pb.StartStepResponse, error) { if s.deps.Steps == nil { return nil, status.Error(codes.Unavailable, "step recorder unavailable") diff --git a/internal/infrastructure/staterpc/task_grants.go b/internal/infrastructure/staterpc/task_grants.go index a3d0aceb5..d1a77b634 100644 --- a/internal/infrastructure/staterpc/task_grants.go +++ b/internal/infrastructure/staterpc/task_grants.go @@ -91,20 +91,14 @@ func (g *TaskGrants) taskFor(token string) int64 { } // authorizesTaskScopedCall reports whether a task-scoped token may make this -// call: only when the RPC is in taskScopedTargets and targets taskID. Every -// other RPC, including grant registration, is refused, so a task grant only -// narrows. workflow.call and step-execution writes carry the caller's own task -// ID; the handler checks step membership, so this never reads the database. +// call: only RPCs in taskScopedTargets that target taskID. func authorizesTaskScopedCall(fullMethod string, req any, taskID int64) bool { target := taskScopedTargets[fullMethod] return target != nil && target(req) == taskID } -// taskScopedTargets maps each RPC a task grant may ever authorize to the -// function naming the task ID its request targets (0 for a request it cannot -// read). Held as data so the sanctioned widenings stop growing a switch: a -// new authorized RPC registers one row here, and the deny-by-default rule -// above covers everything else. +// taskScopedTargets maps each RPC a task grant may call to the task ID its +// request targets. var taskScopedTargets = map[string]func(any) int64{ pb.StateStoreService_Update_FullMethodName: func(req any) int64 { r, ok := req.(*pb.UpdateRequest) diff --git a/internal/infrastructure/staterpc/values.go b/internal/infrastructure/staterpc/values.go index 0425d80c8..26ed67f80 100644 --- a/internal/infrastructure/staterpc/values.go +++ b/internal/infrastructure/staterpc/values.go @@ -41,15 +41,7 @@ func timeValue(t *timestamppb.Timestamp) time.Time { return t.AsTime() } -// mapValues maps a slice of proto values to domain values, always returning a -// non-nil result for empty input. -// -// Protobuf decodes an empty `repeated` field to nil, and Go marshals a nil -// slice to JSON null rather than []. Returning nil here made every decoded -// collection field's JSON type depend on whether it happened to have contents, -// and made the wire path disagree with the local path, which normalises its own -// slices. []B{} for empty input keeps the shape stable at every call site -// without making each one remember to guard. +// mapValues maps a slice, returning an empty non-nil slice for empty input. func mapValues[A, B any](in []A, f func(A) B) []B { if len(in) == 0 { return []B{} @@ -417,27 +409,13 @@ const ( // errors.Is on the client without changing behaviour visibly. msgRereviewCapReached = "store: re-review cap reached" msgInternal = "state store: internal error" - // msgTaskLogsUnavailable is the public phrase for "this service has no - // task-log reader". It is a wire contract like the sentinels above: the - // client rehydrates logging.ErrTaskLogsUnavailable from (Unavailable, this - // message), and a caller depends on that to tell "this process cannot read - // logs" from "this attempt has no log". + // msgTaskLogsUnavailable is part of the wire contract for + // ErrTaskLogsUnavailable. msgTaskLogsUnavailable = "task log reader unavailable" ) -// mapError converts a store sentinel error into a structured gRPC status -// carrying a short, public, stable message -- never the raw wrapped chain -// (which may contain SQL, provider detail, or secrets). Infra errors map to -// codes.Internal with a sanitised message; the caller is expected to log the -// full error server-side before calling mapError. -// -// A context cancellation/deadline raised by the store must retain its identity, -// not be folded into codes.Internal: gRPC-Go surfaces -// context.Canceled/DeadlineExceeded to the client only for those exact codes, -// and the agent's workflow consumer depends on errors.Is(err, -// context.DeadlineExceeded) to distinguish an interrupted stage from a failed -// one. So a context error maps to its own gRPC code (and unmapError rehydrates -// it back to the sentinel). +// mapError converts a store sentinel to a gRPC status with a stable public +// message; other errors become Internal. Context errors keep their codes. func mapError(err error) error { if err == nil { return nil @@ -456,25 +434,8 @@ func mapError(err error) error { return status.Error(codes.Internal, msgInternal) } -// unmapError rehydrates a gRPC status error back to the store sentinel it -// came from, so a caller's errors.Is(err, storecontract.ErrX) keeps working across -// the wire. A non-status error (e.g. a transport failure) is returned -// unchanged. -// -// The deadline/cancel identity must survive too: the agent's -// deadlineStore bounds each Store call with context.WithTimeout, and the -// workflow consumer checks errors.Is(err, context.DeadlineExceeded) to -// decide whether a stage was interrupted by shutdown rather than failed -// (workflow.go). gRPC-Go surfaces an expired or cancelled context as a -// *status.Error whose code is DeadlineExceeded or Canceled, so we rehydrate -// those back to the standard context sentinels -- otherwise the consumer -// would (wrongly) park a task that was merely interrupted. -// -// Unavailable carries one message this package owns: the absent task-log -// reader. It is rehydrated for the same reason the error sentinels are -- -// the dashboard's whole bug was rendering "this process cannot read logs" as -// "the attempt has no log", and only the typed error makes that distinction -// available to a caller. +// unmapError turns a gRPC status back into its store sentinel, context error +// or ErrTaskLogsUnavailable. Non-status errors are returned unchanged. func unmapError(err error) error { if err == nil { return nil diff --git a/internal/releaseupdate/command.go b/internal/releaseupdate/command.go index a0ccd603c..b720df6d9 100644 --- a/internal/releaseupdate/command.go +++ b/internal/releaseupdate/command.go @@ -36,21 +36,15 @@ func (c CommandCatalog) Check(ctx context.Context) (Snapshot, error) { return snapshot, nil } -// CommandInstaller runs the deployment's own install command. HealthURL is -// the base URL its restart tooling must poll for /healthz -- only this -// process knows which address it actually serves, so a script left to guess -// one rolls back releases that came up healthy. Empty -// leaves ARCHIE_HEALTH_URL as the environment already has it. +// CommandInstaller runs the deployment's install command. HealthURL is +// passed as ARCHIE_HEALTH_URL when set. type CommandInstaller struct { Command []string HealthURL string } -// Install runs the configured command and streams its stdout to progress -// line by line as the command emits it -- the earlier CombinedOutput-based -// version buffered everything until exit, so callers saw nothing until the -// whole update either finished or failed. One stdout line may be a -// structured Result instead of prose; see updateResultSentinel. +// Install runs the command, streaming stdout lines to progress. One line may +// be a structured Result. func (i CommandInstaller) Install(ctx context.Context, snapshot Snapshot, meta InstallMeta, progress func(string)) (Result, error) { if len(i.Command) == 0 { return Result{}, fmt.Errorf("update install command is empty") diff --git a/internal/releaseupdate/pending_report.go b/internal/releaseupdate/pending_report.go index 0bbabe2fe..36db9c668 100644 --- a/internal/releaseupdate/pending_report.go +++ b/internal/releaseupdate/pending_report.go @@ -7,13 +7,8 @@ import ( "os" ) -// Report is the phase-2 outcome of an update: whether the daemon came back -// up healthy after restarting, written by whichever process determined that -// (the deployment's restart/health-check tooling) and read, relayed to -// Channel/ChatID/ThreadID, and cleared by whichever archied process boots -// next -- which may be the newly installed version (success) or the -// previous one, if a crash-loop forced a rollback before this code could -// ever run on the new version. +// Report is an update's post-restart outcome, written by the restart tooling +// and relayed by the next archied boot. type Report struct { Channel string `json:"channel"` ChatID int64 `json:"chat_id"` diff --git a/internal/releaseupdate/report_event.go b/internal/releaseupdate/report_event.go index aa4d5e33f..25327ef09 100644 --- a/internal/releaseupdate/report_event.go +++ b/internal/releaseupdate/report_event.go @@ -8,12 +8,7 @@ import ( "github.com/samcharles93/archie-core/internal/events" ) -// ReportEvent turns a phase-2 Report, plus its verification against -// the versions actually running, into the activity-stream event the -// dashboard renders. Unlike Telegram's formatPendingReport, this ships the -// structured Verification rather than pre-rendered prose, so the frontend -// controls presentation -- the two channels' operators read the same facts -// through different UIs, not necessarily the same sentence. +// ReportEvent turns a Report and its verification into a dashboard event. func ReportEvent(report Report, running map[string]string) events.Event { verification := report.Verify(running) drift := make([]map[string]any, 0, len(verification.Drift)) @@ -40,13 +35,8 @@ func ReportEvent(report Report, running map[string]string) events.Event { } } -// summarizeReport is the one-line summary shown in the dashboard's -// activity feed, which renders event.Detail generically for every event -// kind (see ui/src/dashboard/dashboard.js activityRow). It condenses the -// same facts internal/channels/telegram/update.go's formatPendingReport -// spells out at length -- not a byte-identical wording, since the two -// surfaces render differently, but the same four outcomes: confirmed, -// drifted, unverified, or rolled back. +// summarizeReport returns a one-line summary: confirmed, drifted, unverified +// or rolled back. func summarizeReport(report Report, verification Verification) string { if report.RolledBack { return "Update failed its health check and was rolled back to the previous version." diff --git a/internal/releaseupdate/result.go b/internal/releaseupdate/result.go index e70307269..af8b1658e 100644 --- a/internal/releaseupdate/result.go +++ b/internal/releaseupdate/result.go @@ -1,11 +1,6 @@ package releaseupdate -// InstallMeta identifies who to notify once an installed update finishes -// restarting. The process that calls Install returns before the daemon -// actually restarts (the reference installer queues the restart through a -// detached unit so restarting archied.service doesn't kill the installer -// mid-run), so this identity has to survive the restart on disk -- see -// Report and WritePendingReport. +// InstallMeta identifies who to notify after the update restarts. type InstallMeta struct { Channel string ChatID int64 @@ -24,11 +19,8 @@ type ComponentResult struct { Status string `json:"status"` // "updated", "unchanged", or "failed" } -// Result is the structured outcome of the synchronous phase of an install: -// fetch/build/install, before any restart happens. Previous and Installed -// map a component ID to its version. Field names are snake_case in JSON to -// match the install script's ARCHIE_UPDATE_RESULT sentinel line -- see -// command.go and scripts/archie-update-install. +// Result is the outcome of an install before restart. Previous and Installed +// map component IDs to versions. type Result struct { Previous map[string]string `json:"previous"` Installed map[string]string `json:"installed"` diff --git a/internal/releaseupdate/service.go b/internal/releaseupdate/service.go index 48b2b453d..ed030044b 100644 --- a/internal/releaseupdate/service.go +++ b/internal/releaseupdate/service.go @@ -23,11 +23,8 @@ type Catalog interface { Check(context.Context) (Snapshot, error) } -// Installer applies an approved update. It reports only work it has actually -// started; callers remain responsible for telling users the final result. -// The returned Result covers only the synchronous phase (fetch/build/ -// install) -- whether a subsequent restart actually came up healthy is -// reported later, out of band, via a Report (see pending_report.go). +// Installer applies an approved update. The restart outcome is reported +// later as a Report. type Installer interface { Install(context.Context, Snapshot, InstallMeta, func(string)) (Result, error) } @@ -38,15 +35,8 @@ type Component struct { Installed string Available string Changelog string - // InstallType and Reference describe how this component is actually - // deployed -- "binary"/"container"/"embedded"/"external", and a - // deployment-specific pointer such as an image digest or a NATS URL. - // The external check command that populates Installed/Available cannot - // know either of these: it reports what version exists, not how this - // particular instance was installed. See Service.Enrich, which fills - // them in from sources that actually know (this process's own build - // stamp, an observed archie-agent version, deployment configuration for - // a third-party dependency this repo doesn't build). + // InstallType and Reference describe how this component is deployed, filled + // by Service.Enrich. InstallType string Reference string } @@ -93,25 +83,11 @@ type Service struct { Installer Installer StatePath string - // InstallType gates Install: it must be a value the release pipeline - // actually stamps (see package installtype), never "" or - // installtype.Unknown, or Install refuses to run the configured - // Installer at all. The composition root wires this from - // installtype.Type() -- Service itself never reads that package - // directly, so a test can exercise every InstallType without touching - // process-wide state. + // InstallType must be a stamped install type, or Install refuses to run. InstallType string - // Enrich supplies InstallType/Reference for a known component ID (see - // ComponentDaemon, ComponentAgent, ComponentNATS), using sources the - // external check command has no way to know -- this process's own - // compiled-in installtype.Type(), an archie-agent version actually - // observed at runtime (daemon.AgentStatus), or deployment configuration - // for a third-party dependency archie doesn't build. Optional: nil (or - // a component ID Enrich doesn't recognise, or an empty installType - // return) leaves whatever the check command itself reported untouched, - // so a check command that DOES report its own value is never silently - // overwritten. + // Enrich returns a component's install type and reference. Nil or an empty + // result leaves the check command's values. Enrich func(componentID string) (installType, reference string) mu sync.Mutex @@ -193,12 +169,7 @@ func (s *Service) Defer(ctx context.Context, recipient int64, expected Snapshot) // instance was actually deployed. var ErrUnknownInstallType = errors.New("refusing to install: install type is unknown") -// ErrInstallInProgress is returned by Install when another install is -// already running. Telegram and the web dashboard each keep their own -// local "already in progress" flag for a quick UI response, but both are -// wired to the same Service in production -- this is the one guard that -// actually sees both, since a caller-local bool would let one adapter start -// a second install while the other's is still copying binaries. +// ErrInstallInProgress is returned when another install is running. var ErrInstallInProgress = errors.New("an update is already in progress") // installTimeout bounds an install after it has been deliberately detached @@ -206,17 +177,8 @@ var ErrInstallInProgress = errors.New("an update is already in progress") // script would hold the in-progress lock forever. const installTimeout = 30 * time.Minute -// Install runs the configured Installer. The context it hands the -// Installer is intentionally NOT ctx: ctx belongs to whatever triggered the -// update (a chat message handler cancelled by /restart, an HTTP request -// cancelled by a client disconnect), and exec.CommandContext SIGKILLs its -// child the instant that context is cancelled. The install script backs up -// and overwrites the live binaries with plain, non-atomic copies -- a kill -// mid-copy can leave the daemon unable to start, with the one thing that -// could roll that back (the watchdog) never launched because the script -// never reached that line. Detaching the install from ctx, bounded by -// installTimeout instead, is what actually makes the caller's own -// lifecycle safe to interrupt without corrupting an in-flight update. +// Install runs the Installer under installTimeout, detached from ctx so a +// cancelled caller cannot kill an install mid-copy. func (s *Service) Install(ctx context.Context, snapshot Snapshot, meta InstallMeta, progress func(string)) (Result, error) { if s == nil || s.Installer == nil { return Result{}, errors.New("update installation is not configured") @@ -269,11 +231,7 @@ func saveDeferrals(path string, state deferrals) error { return writeFileAtomic(path, data) } -// writeFileAtomic writes data to path via a temp file in the same -// directory, synced and renamed into place, so a reader never observes a -// partially written file. Shared by saveDeferrals and WritePendingReport -- -// both are small JSON state files under the same operational directory -// (cfg.WorkDir) with the same durability requirement. +// writeFileAtomic writes data to path through a synced temp file and rename. func writeFileAtomic(path string, data []byte) error { dir := filepath.Dir(path) if err := os.MkdirAll(dir, 0o700); err != nil { diff --git a/internal/releaseupdate/verify.go b/internal/releaseupdate/verify.go index 84b7fb67a..129e0f460 100644 --- a/internal/releaseupdate/verify.go +++ b/internal/releaseupdate/verify.go @@ -5,69 +5,35 @@ import ( "strings" ) -// Component IDs used by the reference install script and watchdog in the -// Result and Report JSON documents (scripts/archie-update-install, -// scripts/archie-update-watchdog). They are named here because the -// composition root has to key its running-version map by exactly these -// strings for verification to match anything -- a typo would otherwise -// silently downgrade every component to "unverifiable" and restore the -// false-success behaviour this file exists to prevent. +// Component IDs used by the install script and watchdog. const ( ComponentDaemon = "daemon" ComponentAgent = "agent" - // ComponentNATS identifies the NATS server in a Snapshot's Components, - // by the same convention -- a third-party dependency archie doesn't - // build and Report never claims to have installed, but Service.Enrich - // can still describe from deployment configuration (embedded vs - // external, and the URL an external server was configured with). + // ComponentNATS identifies the NATS server. ComponentNATS = "nats" ) -// Version placeholders that carry no release information. Both mean "nobody -// recorded a real version here", and neither may be compared as though it -// were one: doing so turns a healthy update whose bookkeeping went missing -// into a reported failure. -// -// - VersionUnknown is what the reference watchdog substitutes when it -// cannot tell what was installed ("${ARCHIE_UPDATE_INSTALLED_GATEWAY:-unknown}"). -// - VersionDev is what an unstamped build reports for itself: it is the -// default of gatewayVersion/runtimeVersion in cmd/archied, of -// GATEWAY_VERSION in Dockerfile.archied, and of the version Taskfile.yml -// falls back to when git describes no tag. A plain `go build` or an -// untagged image is therefore "dev", not a release. +// Placeholder versions that are never compared: VersionUnknown from the +// watchdog, VersionDev from unstamped builds. const ( VersionUnknown = "unknown" VersionDev = "dev" ) -// VersionDrift is one component whose reported install the running system -// contradicts: the installer said it put Claimed into service, but the -// component itself reports it is running Running. Both are the versions as -// recorded rather than normalized, so an operator sees the strings the two -// sides actually wrote; renderers should trim them for display. +// VersionDrift is a component running a different version than the one +// claimed installed. type VersionDrift struct { ID string Claimed string Running string - // RunningIsPrevious reports whether the version actually running is the - // one this update set out to replace. True is the ordinary case -- the - // install silently did nothing and the pre-update process is still there - // answering the health probe. False means what is running is neither the - // installed version nor the replaced one, and a caller must NOT describe - // that as "still on the old release": it does not know what happened, - // and asserting a cause it cannot support is the same defect as the - // false success this type exists to catch. + // RunningIsPrevious reports whether the running version is the one the + // update replaced. RunningIsPrevious bool } -// Verification is the outcome of checking a Report's claims against the -// versions actually running. Every component the Report claims to have -// installed lands in exactly one of the three sets. -// -// Unverified is not a lesser Drift: a caller that cannot tell the two apart -// will either cry wolf over components that simply cannot self-report, or -// keep asserting success it never checked. Both have shipped here. +// Verification sorts each claimed component into confirmed, drifted or +// unverified. type Verification struct { // Confirmed lists component IDs whose claimed version matches what the // component reports for itself, in ID order. @@ -81,23 +47,9 @@ type Verification struct { Unverified []string } -// Verify compares what r claims was installed against the versions actually -// running now. -// -// This exists because a Report is entirely self-reported. The reference -// watchdog decides "passed" from an HTTP health probe, which proves only -// that *a* daemon is answering -- if the new binary never actually made it -// into service, the previous one answers the probe just as happily, and the -// watchdog then copies the version the installer *intended* into Installed. -// The result reads as a successful upgrade to a version that is not running. -// That is not hypothetical: it shipped, and a task run immediately after a -// reported-successful update hit the exact bug the update was supposed to -// fix. -// -// running maps a component ID (see ComponentDaemon and ComponentAgent) to -// the version that component reports for itself -- archied's own compiled-in -// build version, for instance, which no installer can talk it out of. A -// component absent from running is Unverified, not drifting. +// Verify compares the versions r claims were installed with the versions +// components report running. Components absent from running are +// unverified. func (r Report) Verify(running map[string]string) Verification { var result Verification for id, claimed := range r.Installed { @@ -133,18 +85,8 @@ func IsRecordedVersion(version string) bool { return ok } -// comparableVersion reduces a recorded version to the form both sides of a -// comparison can be expected to agree on, and reports whether it carries any -// usable information at all. -// -// Normalization is deliberately minimal: surrounding whitespace, and a -// single leading "v" or "V" so an installer that records the git tag -// "v1.9.11" matches a binary stamped "1.9.11" (the reference installer -// strips that prefix itself, but nothing forces another deployment shape -// to). Everything else is compared exactly -- an installer is expected to -// record the version it stamped, not a differently formatted description of -// it, and guessing at looser equivalences here would start hiding the very -// mismatches this check is for. +// comparableVersion trims whitespace and a leading "v", and reports whether +// the version is real. func comparableVersion(version string) (string, bool) { normalized := strings.TrimSpace(version) if len(normalized) > 0 && (normalized[0] == 'v' || normalized[0] == 'V') { diff --git a/internal/worktree/worktree.go b/internal/worktree/worktree.go index 081109607..9a1340238 100644 --- a/internal/worktree/worktree.go +++ b/internal/worktree/worktree.go @@ -1,20 +1,6 @@ -// Package worktree owns archied's git operations: fresh clone per task, -// branch, commit as the bot identity, push, diff stats, cleanup. The -// daemon performs these deterministically -- the model's shell tool never -// drives git. -// -// Implemented with go-git rather than by shelling out to the git binary. -// Two consequences are worth knowing: -// -// - The forge token never leaves the process. The previous -// implementation wrote a GIT_ASKPASS helper script and exported the -// token into every child environment; authentication is now an -// in-process http.BasicAuth value. -// - There is no per-repo object cache. go-git can clone with shared -// alternates but has no equivalent of `--dissociate`, so a cached -// bare repo would remain a live dependency of every worktree built -// from it and expiring one would corrupt running tasks. Each task -// gets an independent full clone instead. +// Package worktree performs archied's git operations with go-git: clone, +// branch, commit, push, diff and cleanup. Each task gets an independent full +// clone. package worktree import ( @@ -43,16 +29,8 @@ import ( "github.com/samcharles93/archie-core/internal/domain/workflow/task" ) -// preparedSentinel marks a worktree as fully cloned, branched and -// configured. Its presence is what makes Prepare idempotent: the daemon -// may prepare a worktree before the task container is acquired. -// -// It lives inside .git deliberately. The previous implementation kept it -// in the working tree and hid it via .git/info/exclude, which worked -// because `git add -A` honours that file -- go-git's Add does NOT, so the -// sentinel was committed and pushed onto every task branch. Nothing under. -// git can ever be tracked, so placing it here removes the failure mode -// rather than papering over it. +// preparedSentinel marks a worktree as prepared, making Prepare idempotent. +// It lives in .git so it is never committed. const preparedSentinel = ".git/archie-prepared" type Manager struct { @@ -94,12 +72,7 @@ func ValidCoordinates(owner, repo string, issue int) bool { owner != "." && owner != ".." && repo != "." && repo != ".." } -// auth builds the HTTP credential for clone, fetch and push. -// -// Forges accept a personal access token as the password with any -// non-empty username, so the bot's own name is used. A nil return means -// no token was configured and go-git attempts an anonymous request, -// which is correct for a public read. +// auth returns the HTTP credential, or nil for anonymous access. func (m *Manager) auth() []gitclient.Option { if m.Token == "" { return nil @@ -120,32 +93,16 @@ func (m *Manager) signature() *object.Signature { return &object.Signature{Name: m.BotUser, Email: m.BotEmail, When: time.Now()} } -// Target selects the commit a prepared worktree is positioned at. -// -// The zero value is Fresh: a run that starts new work is reset onto -// origin/. A non-empty Target is a resume: the worktree is reset onto -// origin/, continuing the work an earlier attempt already pushed. -// -// The branch travels with the choice rather than being recomputed from the -// title, because a resume must land on the branch the open pull request lives -// on: a retitled issue would otherwise name a branch that does not exist. -// -// It is a string rather than a bool or an enum precisely so the branch to -// resume onto is carried by the choice; a bool would force a second parameter -// and let a caller select a resume without naming what it resumes onto. +// Target is the branch a worktree is positioned on. Empty (Fresh) resets onto +// origin/; a branch name resumes onto origin/. type Target string // Fresh is the fresh-run target: reset onto origin/. const Fresh Target = "" -// Prepare creates (or reuses) the task's clone and positions it on target, -// returning the worktree directory and the branch it is on. -// -// A missing clone is created for either target. That is what lets a resume -// recover a worktree the terminal cleanup, an expired volume or a different -// host removed before a retry. Fresh lands it on origin/; a resume lands -// it on origin/ and fails closed when that branch is not on the remote -// rather than falling back to base. +// Prepare clones the task's worktree if missing and positions it on target, +// returning its directory and branch. A resume fails if the branch is not on +// the remote. func (m *Manager) Prepare( ctx context.Context, owner, repo, base string, @@ -289,12 +246,7 @@ func (m *Manager) refresh(ctx context.Context, dir, base, branch string) error { return resetOnto(r, dir, branch, baseHash, remoteBase(base)) } -// resume re-syncs an already-prepared worktree onto its branch's remote tip -// without resetting to base, so a remediation can continue work on the PR -// branch an earlier attempt already pushed. It is refresh's complement: refresh -// resets to origin/ for a fresh run; resume resets to origin/ so -// the committed PR work survives. It is reached through Prepare's Target, and -// the worktree it opens is one Prepare has already cloned when it was missing. +// resume resets an existing worktree onto origin/. func (m *Manager) resume(ctx context.Context, dir, branch string) error { r, err := git.PlainOpen(dir) if err != nil { @@ -314,21 +266,8 @@ func (m *Manager) resume(ctx context.Context, dir, branch string) error { return resetOnto(r, dir, branch, *tip, remoteBase(branch)) } -// resetOnto discards the worktree's current contents and points branch at -// commit, leaving a clean tree that matches commit. -// -// The ORDER here is the substance of the function, and it is deliberately the -// opposite of the checkout-then-reset-then-clean it replaced. A previous -// attempt -- an interrupted stage, a killed container, or a build run inside -// the root sandbox -- can leave a path whose type contradicts the tree being -// reset onto as well as untracked output beside it. go-git's reset cannot -// write a file where a directory sits, nor create a directory through a file; -// it failed with `openat : is a directory` / `not a directory` before it -// could apply anything, and the Create-fallback that used to follow reported -// that as a branch that already existed. Clearing the worktree against the -// TARGET tree first removes exactly those conflicts -- an on-disk directory the -// tree declares as a file is untracked, and so is a file the tree declares as a -// directory -- so the reset that follows has nothing left to collide with. +// resetOnto removes everything the target tree does not contain, then points +// branch at commit with a clean tree. func resetOnto(r *git.Repository, dir, branch string, commit plumbing.Hash, label string) error { target, err := commitTree(r, commit) if err != nil { @@ -351,21 +290,8 @@ func resetOnto(r *git.Repository, dir, branch string, commit plumbing.Hash, labe return nil } -// checkOutBranch switches the worktree to branch, creating it at commit when it -// does not exist yet. -// -// Whether the branch exists is resolved from the reference store rather than -// inferred from a failed checkout. A checkout fails for reasons that have -// nothing to do with a missing branch -- most often a path in the working tree -// the tree cannot be written over -- and treating any such failure as "the -// branch does not exist yet" produced `a branch named "refs/heads/" -// already exists`: it named a branch that was never the problem and hid the -// real cause from the park reason an operator reads to decide what to do. -// -// Creating from an explicit commit rather than from HEAD matters too: a branch -// removed while HEAD still pointed at it (a renamed branch, a half-finished -// refresh) made go-git's create path read an unresolvable HEAD and fail with -// "reference not found" instead of creating the branch. +// checkOutBranch checks out branch, creating it at commit if it does not +// exist. func checkOutBranch(r *git.Repository, wt *git.Worktree, branch string, commit plumbing.Hash) error { ref := plumbing.NewBranchReferenceName(branch) opts := &git.CheckoutOptions{Branch: ref, Force: true} @@ -397,13 +323,7 @@ func commitTree(r *git.Repository, commit plumbing.Hash) (*object.Tree, error) { return tree, nil } -// cleanUntracked removes every path under dir that tree does not contain: -// untracked files, whole directories of build output, and any path whose type -// on disk contradicts what the tree declares. -// -// It is given the tree the worktree is being reset ONTO, not HEAD: the point is -// to leave nothing behind that the incoming tree cannot be written over, and -// on a retry HEAD is one of the things being replaced. +// cleanUntracked removes every path under dir that tree does not contain. func cleanUntracked(dir string, tree *object.Tree) error { files := make(map[string]struct{}) dirs := make(map[string]struct{}) @@ -424,12 +344,7 @@ func cleanUntracked(dir string, tree *object.Tree) error { } rel = filepath.ToSlash(rel) if rel == ".git" { - // SkipDir on a non-directory skips the rest of the *parent* - // directory -- at the worktree root, the whole walk. .git is a - // file, not a directory, in a linked worktree, so returning - // SkipDir there would abandon cleaning entirely. Either shape - // is left untouched; only the directory shape needs descent - // suppressed. + // Leave a .git file or directory alone. if entry.IsDir() { return filepath.SkipDir } @@ -490,14 +405,7 @@ func (m *Manager) setIdentity(r *git.Repository) error { } cfg.User.Name = m.BotUser cfg.User.Email = m.BotEmail - // Pin signing off for this repository. - // - // go-git honours the host's global git config, and it cannot sign: - // it has no gpg fallback, only an ObjectSigner plugin. A developer - // or CI image with commit.gpgSign=true set globally would therefore - // make every bot commit fail with "cannot auto-sign commit". The - // daemon's behaviour must not depend on the ambient git config of - // whatever machine it happens to run on. + // Disable commit signing; go-git cannot sign. cfg.Raw.Section("commit").SetOption("gpgsign", "false") if err := r.SetConfig(cfg); err != nil { return fmt.Errorf("write repo config: %w", err) @@ -639,12 +547,8 @@ func (m *Manager) patch(ctx context.Context, dir, base string) (*object.Patch, e return p, err } -// patchFromMergeBase is patch plus the commit the diff was actually taken -// against. That commit is the merge base of base and HEAD, which is NOT base's -// tip once anyone has landed on the base branch since this branch diverged. -// A capture records it beside the file list it measured, so the two describe -// one change set: re-resolving origin/ on the side would name the new -// tip instead. +// patchFromMergeBase returns the patch and the merge-base commit it was taken +// against. func (m *Manager) patchFromMergeBase(ctx context.Context, dir, base string) (*object.Patch, plumbing.Hash, error) { r, err := git.PlainOpen(dir) if err != nil { @@ -680,15 +584,8 @@ func (m *Manager) patchFromMergeBase(ctx context.Context, dir, base string) (*ob return p, bases[0].Hash, nil } -// HasUncommittedChanges reports whether the worktree holds work no commit has -// captured yet: staged, unstaged or untracked. Ignored files do not count, the -// same rule CommitAll's own status check applies when it decides whether there -// is anything to commit. -// -// It exists because Diff cannot answer this: Diff reports what the branch has -// committed against the merge base and never reads the worktree, so a stage -// that must inspect the committed change has no way to tell "nothing has -// changed" from "the change is not committed yet" without this. +// HasUncommittedChanges reports whether the worktree has staged, unstaged or +// untracked changes, ignoring ignored files. func (m *Manager) HasUncommittedChanges(ctx context.Context, dir string) (bool, error) { if err := ctx.Err(); err != nil { return false, err @@ -772,14 +669,8 @@ func (m *Manager) ChangedFiles(ctx context.Context, dir, base string) ([]string, // a change across types is a typechange. const fileTypeMask = 0o170000 -// ChangedFileStats reports what HEAD changed against base, as the per-file -// status and line counts one attempt's capture records. It reuses patch's -// three-dot semantics: diffing against the remote tip instead would attribute -// every commit landed on base since the branch started to this task. -// -// ChangedLines, Diff and ChangedFiles stay the shape stages call; this is the -// same measurement with the detail a capture needs, so there is still exactly -// one diff path -- and it reports the base that path diffed against. +// ChangedFileStats reports HEAD's per-file changes against the merge base +// with base. func (m *Manager) ChangedFileStats(ctx context.Context, dir, base string) (task.ChangeStats, error) { // The diffed base is the merge base patchFromMergeBase diffed against, not // base's tip: the recorded pair has to describe the file list beside it. @@ -797,13 +688,7 @@ func (m *Manager) ChangedFileStats(ctx context.Context, dir, base string) (task. } patches := p.FilePatches() - // Paths come from FilePatches and counts from Stats, joined by position, - // because Stats() carries one entry per patch that produced textual chunks - // and SKIPS the rest (binary files, and any change whose content is - // identical). Reading the two lists off the same index would shift every - // later file's counts onto the wrong path as soon as one binary file is in - // the change. Totals come from Stats so they agree with ChangedLines, which - // sums the same list. + // Stats has no entry for binary or content-identical files. stats := p.Stats() next := 0 files := make([]task.FileChange, 0, len(patches)) @@ -864,11 +749,7 @@ func fileChange(fp fdiff.FilePatch) task.FileChange { return change } -// Snapshot exports HEAD's tracked files into a fresh, empty destDir with no. -// git directory: file contents only, no commit history, branch name, or reflog. -// Used to build the reviewer's isolated workspace -- stripping.git is what -// makes the implementer's reasoning (commit messages, branch name, history) -// structurally unreachable rather than merely undisclosed. +// Snapshot exports HEAD's tracked files into destDir, without .git. func (m *Manager) Snapshot(ctx context.Context, dir, destDir string) error { r, err := git.PlainOpen(dir) if err != nil { @@ -954,11 +835,8 @@ func remoteBase(base string) string { return "refs/remotes/" + git.DefaultRemoteName + "/" + base } -// CheckoutPR materialises an existing pull request's head commit in a fresh -// full clone so the caller can Diff it against its base and Snapshot it for -// operator-triggered review. The head must already be pushed to the same -// repository (archie's own PRs always are); a cross-repo or deleted head is -// refused rather than half-reviewed. The returned cleanup removes the clone. +// CheckoutPR clones a pull request's head into a fresh directory. The head +// must be in the same repository. The cleanup removes the clone. func (m *Manager) CheckoutPR(ctx context.Context, owner, repo, headRef, baseRef string) (dir string, cleanup func(), err error) { if m.WorkDir != "" { if err := os.MkdirAll(m.WorkDir, 0o755); err != nil { @@ -1003,13 +881,8 @@ func (m *Manager) CheckoutPR(ctx context.Context, owner, repo, headRef, baseRef return dir, cleanup, nil } -// resolveBase finds the commit the task branch is compared against. -// -// The fully-qualified remote-tracking ref is tried first because that is -// what a clone produces and it cannot be shadowed. The bare "origin/" -// revision is tried second so that resolution stays as permissive as -// `git diff origin/...HEAD` was -- git resolves that short form -// against refs/heads too, and repositories built that way exist. +// resolveBase resolves the base commit from refs/remotes/origin/, then +// origin/. func resolveBase(r *git.Repository, base string) (plumbing.Hash, error) { candidates := []plumbing.Revision{ plumbing.Revision(remoteBase(base)),