store

Documentation

Overview

Package store is the persistence layer for the memcode state engine. The event log is the source of truth; entities, edges, objectives and current_state are materialized projections. Everything sits behind the Store interface so the local SQLite backend can be swapped for a cloud backend (e.g. Postgres) later without touching callers.

Index

• type Claim
• type Edge
• type EdgeFilter
• type Entity
• type Event
• type EventFilter
• type Objective
• type PreferenceCandidate
• type State
• type Store
  • func Open(ctx context.Context, path string) (Store, error)
• type Tx

Types

type Claim

type Claim struct {
	ID               string
	Type             string // doctrine | preference | command | decision | warning
	Text             string
	Scope            string
	Status           string // candidate | current | stale | conflicted | rejected
	Confidence       string
	Evidence         string
	SourcePath       string
	SourceModifiedAt string
	ExtractedAt      time.Time
}

Claim is an adjudicated assertion extracted from sources + evidence.

type Edge

type Edge struct {
	Src       string
	Dst       string
	Kind      string
	Attrs     json.RawMessage
	ValidFrom *time.Time
	ValidTo   *time.Time
}

Edge is a typed relationship between two entities.

type EdgeFilter

type EdgeFilter struct {
	Src  string
	Dst  string
	Kind string
}

EdgeFilter narrows ListEdges. Empty fields are wildcards.

type Entity

type Entity struct {
	ID        string // "<kind>:<key>"
	Kind      string
	Key       string
	Attrs     json.RawMessage
	ValidFrom *time.Time
	ValidTo   *time.Time
}

Entity is a node in the top-down model (subsystem, concept, doctrine, …).

type Event

type Event struct {
	ID        int64
	TS        time.Time
	Kind      string
	Actor     string
	Payload   json.RawMessage
	ValidFrom *time.Time
	ValidTo   *time.Time
}

Event is one row in the append-only log — the source of truth.

type EventFilter

type EventFilter struct {
	Kinds []string // any-of; empty = all kinds
	Limit int      // 0 = no limit
}

EventFilter narrows ListEvents. Zero value matches everything.

type Objective

type Objective struct {
	ID        string
	Title     string
	Status    string
	Priority  int
	ParentID  string
	CreatedAt time.Time
	UpdatedAt time.Time
}

Objective is a human-authored goal.

type PreferenceCandidate

type PreferenceCandidate struct {
	ID            string
	Axis          string
	Text          string
	Scope         string
	Weight        float64
	SignalCount   int
	SessionCount  int
	FirstSeen     time.Time
	LastSeen      time.Time
	Status        string // candidate | confirmed | demoted
	ConfirmedPath string
	Evidence      json.RawMessage
}

PreferenceCandidate is a behavior-derived directive that accumulated enough weighted evidence to be a standing preference candidate. Materialized from preference_signal events by the prefs reducer. The event log is the source of truth; this table is a projection rebuilt atomically by prefs.Reduce.

type State

type State struct {
	Scope         string
	Layer         string
	Body          json.RawMessage
	SourceEventID *int64
	RefreshedAt   time.Time
}

State is one materialized current_state layer for a scope.

type Store

type Store interface {
	AppendEvent(ctx context.Context, e Event) (int64, error)
	ListEvents(ctx context.Context, f EventFilter) ([]Event, error)

	UpsertEntity(ctx context.Context, e Entity) error
	ListEntities(ctx context.Context, kind string) ([]Entity, error) // kind="" = all
	GetEntity(ctx context.Context, id string) (Entity, bool, error)

	UpsertEdge(ctx context.Context, e Edge) error
	ListEdges(ctx context.Context, f EdgeFilter) ([]Edge, error)

	CreateObjective(ctx context.Context, o Objective) error
	UpdateObjective(ctx context.Context, o Objective) error
	GetObjective(ctx context.Context, id string) (Objective, bool, error)
	ListObjectives(ctx context.Context) ([]Objective, error)

	PutState(ctx context.Context, s State) error
	GetState(ctx context.Context, scope, layer string) (State, bool, error)

	AddClaim(ctx context.Context, c Claim) error
	ListClaims(ctx context.Context) ([]Claim, error)
	ClearClaims(ctx context.Context) error

	AddPreferenceCandidate(ctx context.Context, c PreferenceCandidate) error
	ListPreferenceCandidates(ctx context.Context) ([]PreferenceCandidate, error)
	ClearPreferenceCandidates(ctx context.Context) error
	UpdatePreferenceCandidateStatus(ctx context.Context, id, status, confirmedPath string, weight float64) error

	// RunInTx runs fn inside a single database transaction. fn receives a Tx that
	// exposes the claim-mutation methods (and may grow more as needed). The
	// transaction commits when fn returns nil and rolls back on any error. This is
	// the atomicity seam for operations that must not leave a partial state — e.g.
	// learn.Run's clear+re-insert claim rebuild. Additive: callers that don't use
	// it are unaffected.
	RunInTx(ctx context.Context, fn func(Tx) error) error

	Close() error
}

Store is the persistence contract for the engine.

func Open

func Open(ctx context.Context, path string) (Store, error)

Open opens (creating if needed) the SQLite database at path and applies the schema. The returned Store is safe for sequential use by a single CLI process.

type Tx

type Tx interface {
	ClearClaims(ctx context.Context) error
	AddClaim(ctx context.Context, c Claim) error
	ClearPreferenceCandidates(ctx context.Context) error
	AddPreferenceCandidate(ctx context.Context, c PreferenceCandidate) error
}

Tx is a transaction-scoped handle to the claim-mutation methods. It exists so a caller can make multiple writes atomically (e.g. ClearClaims + a batch of AddClaim) without exposing the raw *sql.Tx. Methods mirror their Store counterparts — same SQL, same semantics — just executed against the transaction.