Files
archie/internal/store/interface.go
T
sam 3ade200ca7 feat(webui): payload field mapping -- bind JSON paths to named fields, preview before saving
Adds t2db.3: schema-by-example field mapping for the no-code playbook epic.
An operator picks a captured event, clicks through its payload to bind named
fields to JSON paths, and previews the resolution against a real event
before saving -- a missing, null, or type-changed path fails loudly (named
by field and event) rather than handing an agent a blank value.

- internal/domain/mapping: Mapping/Field types, path parsing/walking,
  Resolve (per-field failure reporting), Validate (incl. duplicate names)
- internal/store/mappings.go: SQLite persistence, mirrors captures.go
- internal/webui/api_mapping.go: CRUD + preview HTTP API
- ui/src/mappings/: dashboard editor (clickable payload tree, live preview)

Design decisions recorded in docs/prds/payload-field-mapping.md. t2db.4
(binding a mapping + matcher to a workflow) is out of scope here.
2026-08-22 19:18:15 +10:00

113 lines
4.7 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/mapping"
"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.
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, workflow, identity string) (*Task, error)
ClaimNext(ctx context.Context) (*Task, error)
ClaimByIssue(ctx context.Context, owner, repo string, number int) (*Task, error)
Transition(ctx context.Context, taskID int64, from, to, detail string) error
Update(ctx context.Context, t *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) (*Task, error)
TaskByID(ctx context.Context, taskID int64) (*Task, error)
OpenPRs(ctx context.Context) ([]Task, error)
ClearTerminalTasks(ctx context.Context) (int64, error)
Tasks(ctx context.Context, limit int) ([]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
}
// WorkflowStore is the narrow subset of TaskStore that workflow stages call
// mid-run. *Store and storerpc.Client satisfy it.
// This is the interface archie-agent uses via storerpc NATS proxy.
type WorkflowStore interface {
Update(ctx context.Context, t *Task) error
Transition(ctx context.Context, taskID int64, from, to, detail string) 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)
}
// 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
}
// Compile-time check: *Store satisfies TaskStore.
var _ TaskStore = (*Store)(nil)
// Compile-time check: *Store satisfies WorkflowStore.
var _ WorkflowStore = (*Store)(nil)
// Compile-time check: *Store satisfies CaptureStore.
var _ CaptureStore = (*Store)(nil)
// Compile-time check: *Store satisfies MappingStore.
var _ MappingStore = (*Store)(nil)