Files
archie/modules/memory/internal/store/notes.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

351 lines
14 KiB
Go

package store
import (
"context"
"fmt"
"time"
"github.com/google/uuid"
)
// Note is one remembered item in one memory class.
type Note struct {
ID uuid.UUID `db:"id"`
Class string `db:"class"`
Scope string `db:"scope"`
State string `db:"state"`
OwnerID string `db:"owner_id"`
SharedBy string `db:"shared_by"`
Purpose string `db:"purpose"`
Text string `db:"text"`
SessionID *uuid.UUID `db:"session_id"`
Collection *string `db:"collection"`
DisabledAt *time.Time `db:"disabled_at"`
RetainUntil *time.Time `db:"retain_until"`
Version int `db:"version"`
CreatedAt time.Time `db:"created_at"`
UpdatedAt time.Time `db:"updated_at"`
}
// Version is one published version of a shared note.
type Version struct {
NoteID uuid.UUID `db:"note_id"`
Version int `db:"version"`
Text string `db:"text"`
Purpose string `db:"purpose"`
PublisherID string `db:"publisher_id"`
PublishedAt time.Time `db:"published_at"`
}
const noteColumns = `id, class, scope, state, owner_id, shared_by, purpose, text,
session_id, collection, disabled_at, retain_until, version, created_at, updated_at`
// AddNote stores a note and returns it as stored, with the database's clock.
func (s *Store) AddNote(ctx context.Context, orgID string, n Note) (Note, error) {
var out []Note
if err := s.db.SelectContext(ctx, &out, `
INSERT INTO memory.notes (id, org_id, class, scope, state, owner_id, shared_by, purpose,
text, session_id, collection, version, retain_until)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
RETURNING `+noteColumns,
n.ID, orgID, n.Class, n.Scope, n.State, n.OwnerID, n.SharedBy, n.Purpose,
n.Text, n.SessionID, n.Collection, n.Version, n.RetainUntil); err != nil {
return Note{}, fmt.Errorf("remember note: %w", err)
}
if len(out) == 0 {
return Note{}, fmt.Errorf("remember note: nothing was stored for %s", n.ID)
}
return out[0], nil
}
// Owns reports whether owner has a personal note with this id, which is what a
// deletion checks before recording anything.
func (s *Store) Owns(ctx context.Context, orgID, owner string, id uuid.UUID) (bool, error) {
var exists bool
if err := s.db.GetContext(ctx, &exists, `
SELECT EXISTS (SELECT 1 FROM memory.notes
WHERE org_id = $1 AND owner_id = $2 AND scope = 'person' AND id = $3)`, orgID, owner, id); err != nil {
return false, fmt.Errorf("read note: %w", err)
}
return exists, nil
}
// SharedExists reports whether the org has a shared note with this id, published
// or proposed.
func (s *Store) SharedExists(ctx context.Context, orgID string, id uuid.UUID) (bool, error) {
var exists bool
if err := s.db.GetContext(ctx, &exists, `
SELECT EXISTS (SELECT 1 FROM memory.notes WHERE org_id = $1 AND scope = 'shared' AND id = $2)`, orgID, id); err != nil {
return false, fmt.Errorf("read shared note: %w", err)
}
return exists, nil
}
// Notes returns the notes of one class that owner may read: their own, and the
// ones published to the org. The filter is in the query, so a reader without a
// scope sees nothing rather than being filtered afterwards.
func (s *Store) Notes(ctx context.Context, orgID, owner, class string, limit int) ([]Note, error) {
var out []Note
if err := s.db.SelectContext(ctx, &out, `
SELECT `+noteColumns+` FROM memory.notes
WHERE org_id = $1 AND class = $2 AND disabled_at IS NULL
AND (retain_until IS NULL OR retain_until > now())
AND ((scope = 'person' AND owner_id = $3) OR (scope = 'shared' AND state = 'published'))
ORDER BY created_at LIMIT $4`, orgID, class, owner, limit); err != nil {
return nil, fmt.Errorf("list notes: %w", err)
}
return out, nil
}
// Owned returns every note of one class in owner's own scope, including the
// ones they disabled or that have outlived their retention. It is the inspection
// read: a person can see and re-enable what they turned off, while a
// conversation reads only what Notes returns.
func (s *Store) Owned(ctx context.Context, orgID, owner, class string, limit int) ([]Note, error) {
var out []Note
if err := s.db.SelectContext(ctx, &out, `
SELECT `+noteColumns+` FROM memory.notes
WHERE org_id = $1 AND owner_id = $2 AND class = $3 AND scope = 'person'
ORDER BY created_at LIMIT $4`, orgID, owner, class, limit); err != nil {
return nil, fmt.Errorf("list own notes: %w", err)
}
return out, nil
}
// Correct replaces the text of one of owner's own notes and returns it.
func (s *Store) Correct(ctx context.Context, orgID, owner string, id uuid.UUID, text string) (Note, bool, error) {
var out []Note
if err := s.db.SelectContext(ctx, &out, `
UPDATE memory.notes SET text = $4, updated_at = now()
WHERE org_id = $1 AND owner_id = $2 AND scope = 'person' AND id = $3
RETURNING `+noteColumns, orgID, owner, id, text); err != nil {
return Note{}, false, fmt.Errorf("correct note: %w", err)
}
if len(out) == 0 {
return Note{}, false, nil
}
return out[0], true, nil
}
// SetDisabled keeps one of owner's own notes but stops reading it, or resumes.
func (s *Store) SetDisabled(ctx context.Context, orgID, owner string, id uuid.UUID, disabled bool) (bool, error) {
res, err := s.db.ExecContext(ctx, `
UPDATE memory.notes SET disabled_at = CASE WHEN $4 THEN now() ELSE NULL END, updated_at = now()
WHERE org_id = $1 AND owner_id = $2 AND scope = 'person' AND id = $3`,
orgID, owner, id, disabled)
if err != nil {
return false, fmt.Errorf("disable note: %w", err)
}
n, err := res.RowsAffected()
return n > 0, err
}
// CommitDeletion removes one of owner's own notes and witnesses the deletion in
// the same transaction. A deletion and its witness commit together, so the record
// outside the database can never be asked to account for a deletion that did not
// happen, or miss one that did.
func (s *Store) CommitDeletion(ctx context.Context, orgID, owner string, id uuid.UUID) (bool, error) {
return s.commitDeletion(ctx, `
DELETE FROM memory.notes WHERE org_id = $1 AND owner_id = $3 AND scope = 'person' AND id = $2`,
orgID, id, owner)
}
// Pending returns the shared notes waiting for an administrator to publish them.
func (s *Store) Pending(ctx context.Context, orgID string, limit int) ([]Note, error) {
var out []Note
if err := s.db.SelectContext(ctx, &out, `
SELECT `+noteColumns+` FROM memory.notes
WHERE org_id = $1 AND scope = 'shared' AND state = 'pending'
ORDER BY created_at LIMIT $2`, orgID, limit); err != nil {
return nil, fmt.Errorf("list pending notes: %w", err)
}
return out, nil
}
// Shared returns the notes published to the org.
func (s *Store) Shared(ctx context.Context, orgID, class string, limit int) ([]Note, error) {
var out []Note
if err := s.db.SelectContext(ctx, &out, `
SELECT `+noteColumns+` FROM memory.notes
WHERE org_id = $1 AND class = $2 AND scope = 'shared' AND state = 'published'
ORDER BY created_at LIMIT $3`, orgID, class, limit); err != nil {
return nil, fmt.Errorf("list shared notes: %w", err)
}
return out, nil
}
// Publish makes a pending shared note readable to everyone, recording its first
// published version.
func (s *Store) Publish(ctx context.Context, orgID string, id uuid.UUID, publisher string) (Note, bool, error) {
tx, err := s.db.BeginTxx(ctx, nil)
if err != nil {
return Note{}, false, fmt.Errorf("publish note: %w", err)
}
defer func() { _ = tx.Rollback() }()
var out []Note
if err := tx.SelectContext(ctx, &out, `
UPDATE memory.notes SET state = 'published', version = 1, updated_at = now()
WHERE org_id = $1 AND id = $2 AND scope = 'shared' AND state = 'pending'
RETURNING `+noteColumns, orgID, id); err != nil {
return Note{}, false, fmt.Errorf("publish note: %w", err)
}
if len(out) == 0 {
return Note{}, false, nil
}
if _, err := tx.ExecContext(ctx, `
INSERT INTO memory.note_versions (note_id, version, text, purpose, publisher_id)
VALUES ($1, $2, $3, $4, $5)`, out[0].ID, out[0].Version, out[0].Text, out[0].Purpose, publisher); err != nil {
return Note{}, false, fmt.Errorf("record published version: %w", err)
}
if err := tx.Commit(); err != nil {
return Note{}, false, fmt.Errorf("publish note: %w", err)
}
return out[0], true, nil
}
// Versions returns a shared note's published versions, newest first.
func (s *Store) Versions(ctx context.Context, noteID uuid.UUID) ([]Version, error) {
var out []Version
if err := s.db.SelectContext(ctx, &out, `
SELECT note_id, version, text, purpose, publisher_id, published_at
FROM memory.note_versions WHERE note_id = $1 ORDER BY version DESC`, noteID); err != nil {
return nil, fmt.Errorf("list note versions: %w", err)
}
return out, nil
}
// Rollback republishes the text of an earlier version as a new version.
func (s *Store) Rollback(ctx context.Context, orgID string, id uuid.UUID, version int, publisher string) (Note, bool, error) {
tx, err := s.db.BeginTxx(ctx, nil)
if err != nil {
return Note{}, false, fmt.Errorf("roll back note: %w", err)
}
defer func() { _ = tx.Rollback() }()
var old []Version
if err := tx.SelectContext(ctx, &old, `
SELECT note_id, version, text, purpose, publisher_id, published_at
FROM memory.note_versions WHERE note_id = $1 AND version = $2`, id, version); err != nil {
return Note{}, false, fmt.Errorf("read note version: %w", err)
}
if len(old) == 0 {
return Note{}, false, nil
}
var out []Note
if err := tx.SelectContext(ctx, &out, `
UPDATE memory.notes SET text = $3, purpose = $4, version = version + 1, updated_at = now()
WHERE org_id = $1 AND id = $2 AND scope = 'shared' AND state = 'published'
RETURNING `+noteColumns, orgID, id, old[0].Text, old[0].Purpose); err != nil {
return Note{}, false, fmt.Errorf("roll back note: %w", err)
}
if len(out) == 0 {
return Note{}, false, nil
}
if _, err := tx.ExecContext(ctx, `
INSERT INTO memory.note_versions (note_id, version, text, purpose, publisher_id)
VALUES ($1, $2, $3, $4, $5)`, out[0].ID, out[0].Version, out[0].Text, out[0].Purpose, publisher); err != nil {
return Note{}, false, fmt.Errorf("record rolled back version: %w", err)
}
if err := tx.Commit(); err != nil {
return Note{}, false, fmt.Errorf("roll back note: %w", err)
}
return out[0], true, nil
}
// CommitSharedDeletion removes a note from the shared scope, published or
// pending, and witnesses it, for the reason CommitDeletion does.
func (s *Store) CommitSharedDeletion(ctx context.Context, orgID string, id uuid.UUID) (bool, error) {
return s.commitDeletion(ctx, `
DELETE FROM memory.notes WHERE org_id = $1 AND id = $2 AND scope = 'shared'`, orgID, id, "")
}
// commitDeletion runs one delete with its witness in a single transaction. A
// delete that matches no row writes no witness.
func (s *Store) commitDeletion(ctx context.Context, deleteSQL, orgID string, id uuid.UUID, owner string) (bool, error) {
tx, err := s.db.BeginTxx(ctx, nil)
if err != nil {
return false, fmt.Errorf("delete note: %w", err)
}
defer func() { _ = tx.Rollback() }()
args := []any{orgID, id}
if owner != "" {
args = append(args, owner)
}
res, err := tx.ExecContext(ctx, deleteSQL, args...)
if err != nil {
return false, fmt.Errorf("delete note: %w", err)
}
n, err := res.RowsAffected()
if err != nil {
return false, fmt.Errorf("delete note: %w", err)
}
if n == 0 {
return false, nil
}
if _, err := tx.ExecContext(ctx, `
INSERT INTO memory.deletion_witness (note_id, org_id) VALUES ($1, $2)
ON CONFLICT (note_id) DO NOTHING`, id, orgID); err != nil {
return false, fmt.Errorf("witness deletion: %w", err)
}
if err := tx.Commit(); err != nil {
return false, fmt.Errorf("delete note: %w", err)
}
return true, nil
}
// Witness is one committed deletion the record has to account for.
type Witness struct {
NoteID uuid.UUID `db:"note_id"`
OrgID string `db:"org_id"`
}
// Witnesses returns every committed deletion, oldest first.
func (s *Store) Witnesses(ctx context.Context) ([]Witness, error) {
var out []Witness
if err := s.db.SelectContext(ctx, &out, `
SELECT note_id, org_id FROM memory.deletion_witness ORDER BY at, note_id`); err != nil {
return nil, fmt.Errorf("read deletion witnesses: %w", err)
}
return out, nil
}
// DeleteNotes removes the notes with these ids from one org, and witnesses each
// deletion in the same transaction. It is how a deletion recorded outside the
// database is applied again after a restore, so it takes no owner: the record
// already says which org the note belonged to. Witnessing matters here for the
// next restore: the snapshot being replaced predates these deletions, so without
// it nothing in the database would say they happened.
func (s *Store) DeleteNotes(ctx context.Context, orgID string, ids []uuid.UUID) (int, error) {
if len(ids) == 0 {
return 0, nil
}
tx, err := s.db.BeginTxx(ctx, nil)
if err != nil {
return 0, fmt.Errorf("reapply deletions: %w", err)
}
defer func() { _ = tx.Rollback() }()
removed := 0
for _, id := range ids {
res, err := tx.ExecContext(ctx, `DELETE FROM memory.notes WHERE org_id = $1 AND id = $2`, orgID, id)
if err != nil {
return 0, fmt.Errorf("reapply deletion of note %s: %w", id, err)
}
n, err := res.RowsAffected()
if err != nil {
return 0, fmt.Errorf("reapply deletion of note %s: %w", id, err)
}
removed += int(n)
// The witness is restored with the deletion it witnesses: the snapshot this
// is applied to was taken before the deletion, so nothing else in the
// database records that it happened.
if _, err := tx.ExecContext(ctx, `
INSERT INTO memory.deletion_witness (note_id, org_id) VALUES ($1, $2)
ON CONFLICT (note_id) DO NOTHING`, id, orgID); err != nil {
return 0, fmt.Errorf("witness the replayed deletion of note %s: %w", id, err)
}
}
if err := tx.Commit(); err != nil {
return 0, fmt.Errorf("reapply deletions: %w", err)
}
return removed, nil
}