Files
archie/modules/memory/memory.go
T
sam 073959b4f9 feat(memory): scope chat notes and preserve deletions on restore (#2069)
Keep personal notes private by default and require review before publishing shared notes. Restore backups and replay forgotten notes in one transaction, and retain the installed release when an unattended rollback could bring back forgotten notes.
2026-11-21 13:20:31 +11:00

232 lines
7.6 KiB
Go

// Package memory records investigated incidents by target, including their
// causes and action outcomes. When a cause reaches the recurrence threshold
// for a target, the module proposes a root-cause fix regardless of action outcomes.
package memory
import (
"context"
"encoding/json/jsontext"
json "encoding/json/v2"
"errors"
"fmt"
"log/slog"
"regexp"
"slices"
"strings"
"sync/atomic"
"time"
"github.com/google/uuid"
"github.com/jmoiron/sqlx"
"github.com/samcharles93/archie-core/modules/memory/internal/store"
)
// maxHistory bounds the incidents read for one target. The recurrence setting
// is capped below it.
const maxHistory = 200
// MaxRecurrence is the largest recurrence threshold the history can confirm.
const MaxRecurrence = 100
// Target identifies the affected resource by kind and ID, such as host web-1.
type Target struct {
Kind string `json:"kind"`
ID string `json:"id"`
}
// Action records an action considered during an incident and its outcome.
type Action struct {
Action string `json:"action"`
Target string `json:"target"`
// State records whether the action ran, was refused or has an approval status.
State string `json:"state"`
Detail string `json:"detail,omitzero"`
}
// Incident is one investigation of a target.
type Incident struct {
At time.Time `json:"at"`
Cause string `json:"cause"`
Summary string `json:"summary"`
Actions []Action `json:"actions"`
}
// Line formats the incident as one entry in the history shown to the agent.
func (i Incident) Line() string {
line := fmt.Sprintf("- %s, cause %q: %s", i.At.Format("2006-01-02"), i.Cause, i.Summary)
if len(i.Actions) == 0 {
return line + " Actions: none."
}
parts := make([]string, 0, len(i.Actions))
for _, a := range i.Actions {
part := a.Action + " on " + a.Target + ": " + a.State
if a.Detail != "" {
part += " (" + a.Detail + ")"
}
parts = append(parts, part)
}
return line + " Actions: " + strings.Join(parts, "; ") + "."
}
// Review reports how often the cause occurred and any proposal for a fix.
type Review struct {
// Repeats counts matching incidents in the target's recent history,
// including the current incident if it is in that history.
Repeats int
// Proposal is the text of the request for a root-cause fix. It is empty
// below the recurrence threshold.
Proposal string
}
type ledger interface {
Upsert(ctx context.Context, orgID string, in store.Incident) error
SetActions(ctx context.Context, orgID string, runID uuid.UUID, actions []byte) error
Incident(ctx context.Context, orgID string, runID uuid.UUID) (store.Incident, bool, error)
ByTarget(ctx context.Context, orgID, kind, id string, limit int) ([]store.Incident, error)
Propose(ctx context.Context, orgID string, p store.Proposal) (store.Proposal, error)
}
// Module manages incident history and proposals for one organisation, and the
// notes the platform remembers.
type Module struct {
orgID string
log *slog.Logger
ledger ledger
notes noteStore
shared sharedStore
deleted DeletionLog
// failures counts committed deletions whose record could not be written, and
// cleared counts the failures a reconcile has resolved. The instance is
// unhealthy while failures is ahead, which keeps a reconcile that started
// before a newer failure from reporting the record complete.
failures atomic.Uint64
cleared atomic.Uint64
}
// NewModule returns the memory module for orgID. Deletions of notes are
// recorded in deleted, outside the database, so a restore cannot bring them
// back.
func NewModule(db *sqlx.DB, orgID string, log *slog.Logger, deleted DeletionLog) *Module {
s := store.New(db)
return &Module{orgID: orgID, log: log, ledger: s, notes: s, shared: s, deleted: deleted}
}
var unsafeCause = regexp.MustCompile(`[^a-z0-9]+`)
// Cause normalises labels for comparison: "Disk pressure" and "disk-pressure"
// both produce "disk-pressure".
func Cause(s string) string {
return strings.Trim(unsafeCause.ReplaceAllString(strings.ToLower(s), "-"), "-")
}
// Record saves the incident for a run. Recording it again updates the target,
// cause and summary without replacing the original event.
func (m *Module) Record(ctx context.Context, runID uuid.UUID, event jsontext.Value, t Target, cause, summary string) error {
t = Target{Kind: strings.TrimSpace(t.Kind), ID: strings.TrimSpace(t.ID)}
cause = Cause(cause)
summary = strings.TrimSpace(summary)
if t.Kind == "" || t.ID == "" || cause == "" || summary == "" {
return errors.New("a target kind, a target id, a cause and a summary are all required")
}
if !event.IsValid() {
event = jsontext.Value(`null`)
}
return m.ledger.Upsert(ctx, m.orgID, store.Incident{
ID: uuid.New(), RunID: runID, TargetKind: t.Kind, TargetID: t.ID, Cause: cause, Summary: summary, Event: event,
})
}
// Past returns recent incidents for t, newest first, excluding the current run.
func (m *Module) Past(ctx context.Context, runID uuid.UUID, t Target) ([]Incident, error) {
rows, err := m.ledger.ByTarget(ctx, m.orgID, strings.TrimSpace(t.Kind), strings.TrimSpace(t.ID), maxHistory)
if err != nil {
return nil, err
}
out := make([]Incident, 0, len(rows))
for _, r := range rows {
if r.RunID == runID {
continue
}
in, err := incident(r)
if err != nil {
return nil, err
}
out = append(out, in)
}
return out, nil
}
// Finish records action outcomes. It requests a root-cause fix if at least
// threshold incidents in the target's recent history share the current cause,
// regardless of their action outcomes. A run with no recorded incident is ignored.
func (m *Module) Finish(ctx context.Context, runID uuid.UUID, actions []Action, threshold int) (Review, error) {
current, ok, err := m.ledger.Incident(ctx, m.orgID, runID)
if err != nil || !ok {
return Review{}, err
}
raw, err := json.Marshal(actions)
if err != nil {
return Review{}, fmt.Errorf("encode actions: %w", err)
}
if err := m.ledger.SetActions(ctx, m.orgID, runID, raw); err != nil {
return Review{}, err
}
rows, err := m.ledger.ByTarget(ctx, m.orgID, current.TargetKind, current.TargetID, maxHistory)
if err != nil {
return Review{}, err
}
var same []store.Incident
for _, r := range rows {
if r.Cause == current.Cause {
same = append(same, r)
}
}
review := Review{Repeats: len(same)}
if review.Repeats < threshold {
return review, nil
}
proposal, err := m.ledger.Propose(ctx, m.orgID, store.Proposal{
ID: uuid.New(), TargetKind: current.TargetKind, TargetID: current.TargetID, Cause: current.Cause,
Incidents: review.Repeats, Body: proposalBody(current, same),
})
if err != nil {
return Review{}, err
}
review.Proposal = proposal.Body
return review, nil
}
func incident(r store.Incident) (Incident, error) {
out := Incident{At: r.At, Cause: r.Cause, Summary: r.Summary}
if len(r.Actions) > 0 {
if err := json.Unmarshal(r.Actions, &out.Actions); err != nil {
return Incident{}, fmt.Errorf("decode actions of incident %s: %w", r.ID, err)
}
}
return out, nil
}
// proposalBody expects matching incidents in newest-first order so it can
// report the date of the oldest match.
func proposalBody(current store.Incident, same []store.Incident) string {
var tried []string
for _, r := range same {
in, err := incident(r)
if err != nil {
continue
}
for _, a := range in.Actions {
if line := a.Action + " on " + a.Target; !slices.Contains(tried, line) {
tried = append(tried, line)
}
}
}
body := fmt.Sprintf("%q caused %d recorded incidents on %s %s since %s. Identify and fix the underlying problem.",
current.Cause, len(same), current.TargetKind, current.TargetID, same[len(same)-1].At.Format("2006-01-02"))
if len(tried) > 0 {
body += " Recorded actions: " + strings.Join(tried, "; ") + "."
}
return body
}