localproject

type Key struct {
	Kind    Kind
	Locator string
}

type Kind string

type Memory struct {
	Name        string
	Description string
	Type        MemoryType
	// SessionID and UpdatedAt are this memory's own provenance, which is why
	// there is no sidecar metadata file: a lone Markdown document needed one
	// because it had nowhere to record who wrote it, and per-file frontmatter
	// removes that need rather than moving it.
	SessionID string
	UpdatedAt time.Time
	// VerifiedAt is the date a memory that caches something expensive was last
	// checked against its source of truth. Nil for the ordinary memory that
	// asserts nothing it does not itself hold. Only the date is meaningful.
	VerifiedAt *time.Time
	Body       string
}

type MemorySet struct {
	// Memories are the usable ones, ordered by name so the index is stable.
	Memories []Memory
	Skipped  []SkippedMemory
}

type MemoryType string

type MemoryWrite struct {
	Name        string
	Description string
	Type        MemoryType
	Body        string
	SessionID   string
	PriorDigest string
	// VerifiedAt is the date this memory was last checked against the source of
	// truth its body names. Nil leaves an existing date alone -- rewording a
	// body is not re-verifying it -- and clearing one is a hand edit, not
	// something a run does on the way past.
	VerifiedAt *time.Time
}

type Project struct {
	Version int    `json:"version"`
	ID      string `json:"id"`
	Name    string `json:"name"`
	Kind    Kind   `json:"kind"`

	// DefaultWorkspace is where a new Desktop run opens by default. For a Git
	// Project it is one of possibly several worktrees and may change without
	// identity changing; for a directory Project it is also the locator.
	DefaultWorkspace string `json:"default_workspace"`
	// GitCommonDir is set only when Kind is KindGit.
	GitCommonDir string `json:"git_common_dir,omitempty"`

	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
	LastUsedAt time.Time `json:"last_used_at"`
}

type SkippedMemory struct {
	File   string
	Reason string
}

type Store interface {
	// Resolve returns the Project registered for key, registering proposed
	// when there is none.
	//
	// Creation is serialized by the catalog writer lock and repeats the lookup
	// after acquiring it. That second lookup is the point: CLI and Desktop
	// starting in the same new repository at the same moment must agree on one
	// Project ID rather than mint two and split its memory. proposed is used
	// only on that path; when a Project already exists it is discarded and the
	// stored one's last_used_at is advanced.
	//
	// A locator claimed by two Projects is ErrDuplicateLocator: choosing one
	// would silently join or split a memory domain, so repair is the user's.
	Resolve(ctx context.Context, key Key, proposed Project) (Project, error)

	// Find returns the Project registered for key, or ErrNotFound. Unlike
	// Resolve it registers nothing, which is what a diagnostic needs: a command
	// that reports which Project a directory belongs to must not be the thing
	// that decides it belongs to one.
	Find(ctx context.Context, key Key) (Project, error)

	// Get returns one Project by ID, or ErrNotFound. It is the authoritative
	// read: it opens the bundle rather than trusting the catalog projection.
	Get(ctx context.Context, id string) (Project, error)

	// List returns the catalog projection, rebuilding it from the bundles when
	// it is missing or unusable.
	List(ctx context.Context) ([]Summary, error)

	// Update changes presentation or relinks a moved Project. It takes the
	// catalog writer lock, because a locator change has to be visible in the
	// projection at the same moment it is visible in the bundle.
	Update(ctx context.Context, id string, update Update) error

	// Delete removes a Project bundle and its row.
	//
	// It deletes nothing outside that bundle. Sessions are owned by the session
	// store and are not cascaded by a Project going away — a caller that means
	// to remove them says so there, having shown the user which ones. See
	// docs/design/local-project-memory.md §15.
	Delete(ctx context.Context, id string) error

	// Memories returns every memory of the Project, plus the files it could
	// not use. A Project that has never written one reads as empty, not as an
	// error: no memories and no memory directory are the same state to every
	// caller.
	Memories(ctx context.Context, projectID string) (MemorySet, error)

	// WriteMemory creates or replaces exactly one memory under the memory
	// writer lock, and regenerates the index from the files.
	//
	// Creating a name that does not exist is always accepted. Replacing an
	// existing memory requires MemoryWrite.PriorDigest to match the body on
	// disk: an empty one is ErrMemoryUnread, since the writer has not seen what
	// it would overwrite, and a stale one is ErrMemoryConflict. Both refusals
	// return the stored memory so the caller can say which version won.
	WriteMemory(ctx context.Context, projectID string, write MemoryWrite) (Memory, error)

	// DeleteMemory removes one memory and its index line.
	DeleteMemory(ctx context.Context, projectID, name string) error

	// ClearMemories removes every memory file and leaves an empty index,
	// returning how many were removed. It touches nothing else in the bundle.
	ClearMemories(ctx context.Context, projectID string) (int, error)
}

type Summary struct {
	ID               string    `json:"id"`
	Name             string    `json:"name"`
	Kind             Kind      `json:"kind"`
	Locator          string    `json:"locator"`
	DefaultWorkspace string    `json:"default_workspace"`
	LastUsedAt       time.Time `json:"last_used_at"`
}

type Update struct {
	Name *string
	// DefaultWorkspace moves where a Project opens by default. For a directory
	// Project it also relocates the locator, which is what an explicit relink
	// after a move does.
	DefaultWorkspace *string
	// GitCommonDir relinks a Git Project whose repository moved. It is only
	// ever set by an explicit user decision: no heuristic may join two memory
	// domains, so nothing infers this from a remote URL or a directory name.
	GitCommonDir *string
	// TouchLastUsed advances last_used_at, which orders the picker.
	TouchLastUsed bool
}