store

type ApplyFile struct {
	Path    string // Path relative to vault root (e.g., "vault.yaml" or "Goal/some-goal.yaml")
	SHA256  string // SHA-256 hash of content (hex, 64 chars)
	Content []byte // File content
}

type ApplyJournal interface {
	// PutUnit writes a new unit with applied=false.
	PutUnit(ctx context.Context, unit ApplyUnit) error

	// MarkApplied marks a unit as applied and updates the index. Called in the
	// same transaction as index updates (rebuild, rehydration, reference indexing).
	MarkApplied(ctx context.Context, unitID string) error

	// ListUnapplied returns every unit with applied=false, oldest first.
	ListUnapplied(ctx context.Context) ([]ApplyUnit, error)

	// PruneOld removes applied units older than the given count (keeps the most
	// recent `keepCount` applied units). A keepCount of 0 or less means unlimited.
	PruneOld(ctx context.Context, keepCount int) error

	// WithinTransaction runs fn against the journal in a transaction (adapters
	// that support transactions). Idempotent with database adapters.
	WithinTransaction(ctx context.Context, fn func(ctx context.Context, tx ApplyJournal) error) error
}

type ApplyUnit struct {
	ID       string      // Unique identifier for this unit (uuid)
	On       time.Time   // When the mutation happened
	Operator string      // Who performed it (actor, "local" for file operations)
	Reason   string      // Why (for exclusion, recovery, or user-supplied reason)
	Files    []ApplyFile // Files to write: {path, sha256, content}
	Applied  bool        // Whether this unit was applied (committed to files and index)
}

type Bundle struct {
	Location string
	Paths    map[string]string
}

type BundleStore interface {
	// PutBundle stores files (name to content) for one project at one
	// version, all or nothing, and returns where they went.
	PutBundle(ctx context.Context, projectID string, version int, files map[string][]byte) (Bundle, error)
}

type Chunk struct {
	Seq  int64
	Data []byte
}

type ConflictError struct {
	Kind   string
	ID     string
	Ours   []byte
	Theirs []byte
}

type DocStore interface {
	// Create records a new document for a manifest with its first
	// snapshot, unless the manifest already has one. created is false,
	// and docID the existing document's, when another writer got there
	// first; the caller then loads that one and discards its own.
	Create(ctx context.Context, kind, id, docID string, snapshot []byte) (existing string, created bool, err error)
	// DocumentFor returns the document id of a manifest's draft, or
	// ErrNoDocument.
	DocumentFor(ctx context.Context, kind, id string) (string, error)
	// ManifestFor returns the manifest a document belongs to, or
	// ErrNoDocument.
	ManifestFor(ctx context.Context, docID string) (kind, id string, err error)
	// Append stores a chunk and returns its sequence number, which is
	// greater than every earlier one for the document.
	Append(ctx context.Context, docID string, data []byte) (int64, error)
	// Load returns the snapshot and every chunk since, oldest first.
	Load(ctx context.Context, docID string) (snapshot []byte, chunks []Chunk, err error)
	// Since returns the chunks after seq, oldest first; always non-nil.
	Since(ctx context.Context, docID string, after int64) ([]Chunk, error)
	// Compact replaces the snapshot with one that includes every chunk
	// up to and including upTo, and drops those chunks. Chunks appended
	// after upTo, even while compacting, are kept.
	Compact(ctx context.Context, docID string, snapshot []byte, upTo int64) error
}

type Exclusion struct {
	Kind     string    // Manifest kind
	ID       string    // Manifest id
	Name     string    // Manifest name at time of exclusion
	On       time.Time // When excluded
	Reason   string    // Why excluded
	Operator string    // Who excluded it
}

type ManifestDraft struct {
	Kind string
	ID   string
	YAML []byte
	On   time.Time
}

type ManifestStore interface {
	// PutVersion appends a new version. The caller is responsible for
	// computing Number as one more than the current version (or 1 for a
	// new manifest); an adapter rejects a Number that is not exactly that,
	// which is what guards immutability under concurrent writers.
	PutVersion(ctx context.Context, v Version) error

	// GetCurrent returns the highest-numbered version of a manifest.
	GetCurrent(ctx context.Context, kind, id string) (Version, bool, error)

	// GetVersion returns one specific historical version.
	GetVersion(ctx context.Context, kind, id string, number int) (Version, bool, error)

	// ListVersions returns every version of a manifest, oldest first.
	ListVersions(ctx context.Context, kind, id string) ([]Version, error)

	// ListAllVersions returns every version of every manifest across all
	// kinds, newest first, with optional pagination (limit defaults to 20,
	// cursor is opaque and returned by the preceding call). Used by the
	// snapshots list endpoint.
	ListAllVersions(ctx context.Context, limit int, cursor string) (versions []Version, nextCursor string, err error)

	// ListSummaries returns the current version of every manifest of a
	// kind, optionally filtered by a case-insensitive substring match over
	// id and name (query, ignored when empty) and by zero or more
	// reference filters (refs; a manifest must have a current outgoing
	// reference matching every one of them - logical AND, ignored when
	// empty). Always returns a non-nil, possibly empty, slice.
	ListSummaries(ctx context.Context, kind, query string, refs []RefFilter) ([]Summary, error)

	// ListIDs returns the id of every manifest of a kind that has a
	// current version.
	ListIDs(ctx context.Context, kind string) ([]string, error)

	// Counts returns the number of manifests (by id, not by version) for
	// every kind that has at least one.
	Counts(ctx context.Context) (map[string]int, error)

	// IndexReferences replaces the recorded outgoing references for one
	// manifest's current version. The engine calls this once per commit,
	// right after PutVersion, inside the same transaction, with every
	// x-cartograph-ref value found by walking that kind's schema.
	IndexReferences(ctx context.Context, fromKind, fromID string, refs []Ref) error

	// ListReferencedBy returns every outgoing reference recorded for one
	// manifest's current version.
	ListReferencedBy(ctx context.Context, fromKind, fromID string) ([]Ref, error)

	// ListReferencing returns the current summary of every manifest that
	// has an outgoing reference to toKind/toID.
	ListReferencing(ctx context.Context, toKind, toID string) ([]Summary, error)

	// PutWorking writes a manifest's YAML as the working copy without creating
	// a version. Used for autosave writes that don't create an explicit
	// snapshot. The working copy is updated, but no version entry is created.
	PutWorking(ctx context.Context, kind, id string, yamlBytes []byte) error

	// GetWorking returns a manifest's working copy (the file on disk that may
	// not yet be versioned). Returns found=false when no working copy exists.
	GetWorking(ctx context.Context, kind, id string) ([]byte, bool, error)

	// WithinTransaction runs fn against a ManifestStore that commits all of
	// its writes together, or none of them if fn returns an error.
	WithinTransaction(ctx context.Context, fn func(ctx context.Context, tx ManifestStore) error) error

	// Exclude removes a manifest from vault.yaml and records the exclusion.
	// The file remains on disk. Returns an error if the manifest does not exist
	// (use GetCurrent to check first). Refused if the manifest is referenced by
	// a live manifest (call ListReferencing first).
	Exclude(ctx context.Context, kind, id, name, reason, operator string) error

	// ListExcluded returns every excluded manifest, newest first.
	ListExcluded(ctx context.Context) ([]Exclusion, error)

	// Recover re-adds an excluded manifest to vault.yaml and removes the
	// exclusion record. Returns an error if the file is missing from disk.
	Recover(ctx context.Context, kind, id, reason, operator string) error
}

type NotFoundError struct {
	Kind string
	ID   string
}

type OperationalStore interface {
	// PutProjectStateTransition appends one row to a project's state
	// history (the table is append-only; the current state is the most
	// recent row). A project with no rows is implicitly "draft".
	PutProjectStateTransition(ctx context.Context, e ProjectStateEntry) error

	// ListProjectStateHistory returns every state transition for a
	// project, oldest first. Empty (never nil) when the project has never
	// moved out of the implicit "draft" state.
	ListProjectStateHistory(ctx context.Context, projectID string) ([]ProjectStateEntry, error)
}

type ProjectStateEntry struct {
	ProjectID string
	State     string
	Actor     string
	Reason    string
	On        time.Time
	Snapshot  int
	Bundle    string
}

type Ref struct {
	Path   string
	ToKind string
	ToID   string
}

type RefFilter struct {
	Kind string
	ID   string
}

type StateStore interface {
	// Name is the state manifest's own id (metadata.id).
	Name() string

	// Included returns every ref ("Kind/id") the state manifest includes,
	// in the order it lists them.
	Included(ctx context.Context) ([]string, error)

	// ListUnapplied returns every manifest the adapter can see that is
	// neither included nor excluded: what a person could apply next.
	ListUnapplied(ctx context.Context) ([]UnappliedRef, error)

	// Apply includes the given refs. Applying a ref that is already
	// included is quiet; a ref the adapter cannot find is refused with
	// an error that names it. Returns how many refs were newly included.
	Apply(ctx context.Context, refs []string) (added int, err error)

	// StateYAML returns the state manifest's own bytes, or found=false
	// when the adapter has not written one yet.
	StateYAML(ctx context.Context) (yaml []byte, found bool, err error)

	// Rehydrate reloads the live state from the adapter's source of
	// truth. Called after Apply or Recover changed what is included.
	Rehydrate(ctx context.Context) error
}

type Summary struct {
	Kind      string
	ID        string
	Name      string
	Version   int
	UpdatedOn time.Time

	// Labels is metadata.labels, carried on the summary so a list can be
	// grouped and filtered by them. Nil where the manifest sets none.
	Labels map[string]string

	// Draft is true only for a synthetic Summary standing in for a
	// project that has only ever been saved as a draft, never committed
	// (includeDrafts=true): Version is then 0 and UpdatedOn is the
	// draft's own save time. False (the zero value) for every ordinary,
	// committed Summary a store adapter's own ListSummaries builds.
	Draft bool
}

type UnappliedRef struct {
	Kind string
	ID   string
	Name string
}

type VaultIndex interface {
	ManifestStore                  // versions, summaries, references, working copies, exclusions
	Journal() ApplyJournal         // the two-phase apply journal
	Operational() OperationalStore // project state history (same database)
	Docs() DocStore                // the shared drafts' CRDT documents (same database)

	// File hashes: what the vault compares a file against on open and on a watcher event.
	GetFileHash(ctx context.Context, kind, id string) (sha256 string, found bool, err error)
	PutFileHash(ctx context.Context, kind, id, sha256, mtime string) error
	DeleteFileHash(ctx context.Context, kind, id string) error

	// Meta: small key/value facts about the index itself (the recorded vault.yaml hash, rebuild time).
	GetMeta(ctx context.Context, key string) (value string, found bool, err error)
	PutMeta(ctx context.Context, key, value string) error

	Close() error
}

type Version struct {
	Kind   string
	ID     string
	Number int
	YAML   []byte
	Actor  string
	Reason string
	On     time.Time
}