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)),