Files
archie/internal/store/interface.go
T
sam 242e51b3e1 feat(staterpc): carry the dashboard's configuration snapshot
archie-core-ymut decided the configuration page reads a projection the daemon
publishes rather than reaching into a shared config.Holder. This is the
carrier: a single-row store surface plus PutConfigSnapshot/GetConfigSnapshot,
taking the contract to 42 RPCs.

The document is opaque here. Its shape belongs to the daemon that builds it
and the page that renders it, so the store neither parses nor validates it,
and schema names the projection so a reader can refuse one it does not
understand. It is secret-free where it is built: the projection carries an API
key's environment variable name and whether it resolved, never a value.

Both RPCs are administrative. authorizesTaskScopedCall is deny-by-default, so
a container's task-scoped grant can neither rewrite what an operator reads nor
read a projection of the deployment it runs inside; a test pins both.

Nothing publishes or reads it yet -- the daemon's publisher and the UI's
read path land with the rest of the cutover.
2026-09-09 23:35:41 +10:00

171 lines
7.6 KiB
Go

// Package store defines the storage abstractions for archied's task and
// event data. TaskStore is the full surface the daemon needs and *Store is its
// SQLite implementation.
package store
import (
"context"
"time"
"github.com/samcharles93/archie-core/internal/domain/binding"
"github.com/samcharles93/archie-core/internal/domain/mapping"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/events"
)
// TaskStore is the full store surface the daemon needs.
// Consumers depend on TaskStore, never on a concrete type.
type TaskStore interface {
TaskLifecycle
TaskEvents
TaskQueries
TaskArchiver
TaskRetryer
}
// TaskLifecycle manages the core task state machine and enqueuing.
// Binding-triggered task creation lives on BindingTaskCreator, not here,
// so the lifecycle surface stays narrow and non-binding consumers (forge
// poll, chat spawn, drain loop) do not acquire a binding-specific shape.
type TaskLifecycle interface {
EnqueueIssue(ctx context.Context, owner, repo string, number int, title, body, labels, identity string) (bool, error)
EnqueueChatTask(ctx context.Context, owner, repo, title, body, wf, identity string) (*workflow.Task, error)
ClaimNext(ctx context.Context) (*workflow.Task, error)
ClaimByIssue(ctx context.Context, owner, repo string, number int) (*workflow.Task, error)
Transition(ctx context.Context, taskID int64, from, to, detail string) error
Update(ctx context.Context, t *workflow.Task) error
Requeue(ctx context.Context, taskID int64, fromStatus, workflow string) error
RecoverStale(ctx context.Context) (int64, error)
}
// TaskArchiver removes one terminal task's local record with an optimistic
// status guard. It is separate from the already broad lifecycle contract so
// consumers that only run tasks do not acquire an operator-only capability.
type TaskArchiver interface {
ArchiveTask(ctx context.Context, taskID int64, fromStatus string, audit events.Event) (eventID int64, err error)
}
// TaskRetryer atomically requeues recoverable work and accounts for the new
// attempt so a partial write cannot evade the retry cap.
type TaskRetryer interface {
RetryTask(ctx context.Context, taskID int64, fromStatus, workflow string) error
}
// TaskQueries groups read-only task accessors.
type TaskQueries interface {
TaskByIssue(ctx context.Context, owner, repo string, number int) (*workflow.Task, error)
TaskByID(ctx context.Context, taskID int64) (*workflow.Task, error)
OpenPRs(ctx context.Context) ([]workflow.Task, error)
ClearTerminalTasks(ctx context.Context) (int64, error)
Tasks(ctx context.Context, limit int) ([]workflow.Task, error)
StatusCounts(ctx context.Context) (map[string]int, error)
IncrementRetryCount(ctx context.Context, taskID int64) error
}
// TaskEvents groups observability and lifecycle methods.
type TaskEvents interface {
InsertEvent(ctx context.Context, e events.Event) (int64, error)
EventsSince(ctx context.Context, sinceID int64, limit int) ([]events.Event, error)
TaskEvents(ctx context.Context, taskID int64) ([]events.Event, error)
WorkflowStats(ctx context.Context) ([]WorkflowStat, error)
StageStats(ctx context.Context) ([]StageStat, error)
TokensByDay(ctx context.Context, days int) ([]DayTokens, error)
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. See docs/prds/event-capture-storage.md.
type CaptureStore interface {
InsertCapture(ctx context.Context, c CapturedEvent, retention time.Duration, maxEvents int) (int64, 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.
// See docs/architecture/migration-decisions.md, "Dashboard configuration page".
type ConfigSnapshotStore interface {
PutConfigSnapshot(ctx context.Context, snapshot ConfigSnapshot) error
ConfigSnapshot(ctx context.Context) (ConfigSnapshot, bool, error)
}
// MappingStore persists payload field mappings (t2db.3). Deliberately
// separate from TaskStore and CaptureStore for the same reason those are
// split: the dashboard's mapping editor should only acquire the mapping
// surface, not the full task or capture APIs. See
// docs/prds/payload-field-mapping.md.
type MappingStore interface {
InsertMapping(ctx context.Context, m mapping.Mapping) (int64, error)
GetMapping(ctx context.Context, id int64) (*mapping.Mapping, error)
ListMappings(ctx context.Context) ([]mapping.Mapping, error)
UpdateMapping(ctx context.Context, m mapping.Mapping) error
DeleteMapping(ctx context.Context, id int64) error
}
// BindingStore persists playbook bindings (t2db.4 Phase B): 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
// docs/prds/playbook-binding.md.
type BindingStore interface {
InsertBinding(ctx context.Context, b binding.Binding) (int64, error)
GetBinding(ctx context.Context, id int64) (*binding.Binding, error)
ListBindings(ctx context.Context) ([]binding.Binding, error)
UpdateBinding(ctx context.Context, b binding.Binding) error
DeleteBinding(ctx context.Context, id int64) error
ApproveBinding(ctx context.Context, id int64) 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.
type BindingDispatcher interface {
ArmedBindingsForSource(ctx context.Context, source string) ([]binding.Binding, error)
RecordDispatch(
ctx context.Context,
bindingID int64,
bindingVersion int64,
captureID int64,
taskID int64,
) error
ListUndispatchedCaptures(ctx context.Context, sources []string, limit int) ([]CapturedEvent, error)
}
// BindingTaskCreator is the single-method consumer-facing surface for
// enqueueing a task triggered by a binding. Splitting it off TaskLifecycle
// keeps the lifecycle surface narrow (8 methods, the interfacebloat limit)
// and keeps the binding-specific shape on the binding interfaces.
type BindingTaskCreator interface {
EnqueueBindingTask(ctx context.Context, owner, repo, title, body, wf, identity string, bindingID int64, bindingVersion int) (*workflow.Task, error)
}
// Compile-time check: *Store satisfies TaskStore.
var _ TaskStore = (*Store)(nil)
// Compile-time check: *Store satisfies workflow.Store.
var _ workflow.Store = (*Store)(nil)
// Compile-time check: *Store satisfies CaptureStore.
var _ CaptureStore = (*Store)(nil)
// Compile-time check: *Store satisfies MappingStore.
var _ MappingStore = (*Store)(nil)
// Compile-time check: *Store satisfies BindingStore.
var _ BindingStore = (*Store)(nil)
// Compile-time check: *Store satisfies BindingDispatcher.
var _ BindingDispatcher = (*Store)(nil)
// Compile-time check: *Store satisfies BindingTaskCreator.
var _ BindingTaskCreator = (*Store)(nil)