archive

type Counts struct {
	// MemoryFiles and NoteFiles count the .md entries in each tree.
	MemoryFiles int `json:"memory_files"`
	NoteFiles   int `json:"note_files"`

	// Tables maps table name to row count in the seam.db snapshot, read from
	// the snapshot after it verified rather than from the live database, so the
	// numbers describe the bytes actually in the archive. Empty for a NoDB
	// export. Enumerated from sqlite_master rather than a hand-written list, so
	// a table added by a later migration appears without anyone remembering to
	// add it here.
	Tables map[string]int `json:"tables,omitempty"`
}

type ExportOptions struct {
	// DataDir is the instance root: the directory holding seam.db, memory/ and
	// notes/. It is named explicitly rather than read from config so an export
	// can target a data dir this process does not serve.
	DataDir string

	// Out receives the gzipped tar. It is an io.Writer, not a path, because the
	// CLI writes to a temp file it renames into place and to stdout for `-o -`;
	// choosing the destination is the caller's job.
	Out io.Writer

	// NoDB exports the markdown trees only. The manifest then carries no
	// schema version, no table counts, and no embedding models: those describe
	// a database this archive does not contain, and stamping them from the live
	// file would describe bytes that are not here. seam.db is not even opened,
	// so a knowledge-only export works on a data dir with no database at all.
	NoDB bool

	// SeamlessdVersion is recorded verbatim in the manifest. It is passed in
	// because the build version is linked into package main and this package
	// sits below cmd/.
	SeamlessdVersion string

	// Host overrides the recorded source host. Empty means os.Hostname.
	Host string
}

type ImportOptions struct {
	// DataDir is the destination instance root. It may not exist yet.
	DataDir string

	// Src is the archive stream. It is an io.Reader, not a path, so `import
	// --from -` can read the archive from stdin; the reader is consumed once,
	// front to back, and never seeked.
	Src io.Reader

	// DryRun reports what the import would do and imports nothing. A fresh
	// destination is left untouched entirely (nothing is even extracted); a
	// merge still stages the archive in a temp dir and opens the destination
	// database, because the counts it promises are the real ones and the only
	// way to compute them is against both schemas.
	DryRun bool

	// Embedder vectorizes memories and notes as they are written during a
	// merge. Nil is supported and warned about: the merge imports no embeddings
	// row (vectors belong to whichever model this machine runs), so without an
	// embedder the imported items are lexically searchable and not semantically
	// until a re-embed pass runs.
	Embedder llm.Embedder

	// Logger receives the counts. Nil uses slog.Default.
	Logger *slog.Logger
}

type ImportReport struct {
	Mode    Mode
	DryRun  bool
	DataDir string

	// Manifest is the archive's own description of itself, carried through so
	// the caller can print what it was handed without re-reading the file.
	Manifest Manifest

	// Memories and Notes count corpus files written: restored verbatim for a
	// fresh import, written through the files layer for a merge. Skipped counts
	// items whose id was already present (the idempotent re-merge).
	Memories int
	Notes    int
	Skipped  int

	// Projects counts projects-table rows registered for a slug the archive's
	// corpus referenced but its projects table did not carry.
	Projects int

	// Rows is the per-table inserted count of the merge row pass, keyed by
	// table name. Empty for a fresh restore, where the whole database arrives
	// as a snapshot and the manifest's counts describe it.
	Rows map[string]int

	PathCollisions []PathCollision
	NameCollisions []NameCollision
	Warnings       []string
}

type Manifest struct {
	// FormatVersion is the container version (FormatVersion).
	FormatVersion int `json:"format_version"`

	// SchemaVersion is the migration version of the snapshot, 0 for a NoDB
	// export. A value above the reader's store.LatestSchemaVersion is
	// ErrSchemaTooNew; anything at or below it migrates forward on import.
	SchemaVersion int `json:"schema_version"`

	// SeamlessdVersion is the build that wrote the archive, supplied by the
	// caller: the version is linked into the binary, and this package sits
	// below cmd/.
	SeamlessdVersion string `json:"seamlessd_version"`

	CreatedAt  time.Time `json:"created_at"`
	SourceHost string    `json:"source_host"`

	// IncludesDB is false for a knowledge-only (NoDB) export, where the tar
	// carries the two markdown trees and nothing else.
	IncludesDB bool `json:"includes_db"`

	// EmbeddingModels is DISTINCT model FROM embeddings in the snapshot. The
	// importer compares it with the destination's configured embedder: vectors
	// from another model are not comparable, so a mismatch is the signal to
	// re-embed rather than to trust the imported rows.
	EmbeddingModels []string `json:"embedding_models,omitempty"`

	Counts Counts `json:"counts"`
}

type Mode string

type NameCollision struct {
	Table      string
	Column     string
	Value      string
	IncomingID string
	ExistingID string
}

type PathCollision struct {
	// Path is the data-dir-relative path both items want.
	Path string
	// IncomingID is the archive's item; ExistingID is the one already there,
	// empty when the file exists on disk with no readable id.
	IncomingID string
	ExistingID string
}