ports

type BookmarkCodec interface {
	// Encode writes the managed header followed by the entity's content.
	Encode(*bookmarks.Bookmark) ([]byte, error)

	// Decode requires the expected note kind and retains the original body bytes.
	Decode([]byte) (*bookmarks.Bookmark, error)
}

type BookmarkRepository interface {
	// Save persists the entity's document and refreshes its searchable projection.
	Save(context.Context, *bookmarks.Bookmark) error

	// ByID decodes the source document and verifies its kind and requested UUID.
	ByID(context.Context, uuid.UUID) (*bookmarks.Bookmark, error)

	// Update requires an existing entity and preserves its creation timestamp.
	Update(context.Context, *bookmarks.Bookmark) error
}

type HabitCodec interface {
	// Encode writes the managed header followed by the entity's content.
	Encode(*habits.Habit) ([]byte, error)

	// Decode requires the expected note kind and retains the original body bytes.
	Decode([]byte) (*habits.Habit, error)
}

type HabitRepository interface {
	// Save persists the entity's document and refreshes its searchable projection.
	Save(context.Context, *habits.Habit) error

	// ByID decodes the source document and verifies its kind and requested UUID.
	ByID(context.Context, uuid.UUID) (*habits.Habit, error)

	// Update requires an existing entity and preserves its creation timestamp.
	Update(context.Context, *habits.Habit) error
}

type IDGenerator interface {
	// Generate returns a fresh UUID for a new entity.
	Generate() uuid.UUID
}

type InboxCodec interface {
	// Encode writes the managed header followed by the entity's content.
	Encode(*inbox.Inbox) ([]byte, error)

	// Decode requires the expected note kind and retains the original body bytes.
	Decode([]byte) (*inbox.Inbox, error)
}

type InboxRepository interface {
	// Save persists the entity's document and refreshes its searchable projection.
	Save(context.Context, *inbox.Inbox) error

	// ByID decodes the source document and verifies its kind and requested UUID.
	ByID(context.Context, uuid.UUID) (*inbox.Inbox, error)

	// Update requires an existing entity and preserves its creation timestamp.
	Update(context.Context, *inbox.Inbox) error
}

type Index interface {
	// FindNotes applies type/tag filters and pagination, ordered by update time
	// descending and UUID ascending. Labels are normalized to a single line.
	FindNotes(context.Context, NoteFilter) ([]NoteSummary, error)

	// FindGroups returns normalized group names in alphabetical order, including
	// only groups currently assigned to at least one person.
	FindGroups(context.Context) ([]string, error)

	// Delete removes a note's projection and its tag/group associations.
	// Deleting an absent UUID succeeds; the source document is left untouched.
	Delete(context.Context, uuid.UUID) error

	// Project decodes a document's managed header, verifies its UUID and updates
	// the appropriate typed projection. RawNoteCodec validates body syntax before
	// raw saves; index projection itself does not validate the entire body.
	Project(context.Context, Note) error

	// Rebuild replaces all projections in one transaction. Callback errors or
	// cancellation roll back the replacement, preserving the previous index.
	// The callback must use the supplied index and must not retain it afterward.
	Rebuild(context.Context, func(Index) error) error

	// UpsertPage atomically replaces a page's metadata, title, area and tags.
	// The path identifies its already-persisted source document.
	UpsertPage(context.Context, *pages.Page, string) error

	// UpsertJournal atomically replaces a journal's metadata, date and tags.
	// A date already assigned to another UUID returns ErrJournalAlreadyExists.
	UpsertJournal(context.Context, *journals.Journal, string) error

	// JournalExists reports whether a valid date is already assigned to a journal.
	JournalExists(context.Context, calendar.Date) (bool, error)

	// UpsertBookmark atomically replaces a bookmark's metadata, URL and tags.
	UpsertBookmark(context.Context, *bookmarks.Bookmark, string) error

	// UpsertInbox atomically replaces an inbox note's metadata, content and tags.
	UpsertInbox(context.Context, *inbox.Inbox, string) error

	// UpsertHabit atomically replaces a habit's metadata, title, goal and tags.
	UpsertHabit(context.Context, *habits.Habit, string) error

	// UpsertPerson atomically replaces a person's metadata, name, groups and tags.
	// Unused group definitions may remain stored but are excluded by FindGroups.
	UpsertPerson(context.Context, *persons.Person, string) error
}

type JournalCodec interface {
	// Encode writes the managed header followed by the entity's content.
	Encode(*journals.Journal) ([]byte, error)

	// Decode requires the expected note kind and retains the original body bytes.
	Decode([]byte) (*journals.Journal, error)
}

type JournalRepository interface {
	// Save persists the entity's document and refreshes its searchable projection.
	Save(context.Context, *journals.Journal) error

	// ByID decodes the source document and verifies its kind and requested UUID.
	ByID(context.Context, uuid.UUID) (*journals.Journal, error)

	// Update requires an existing entity and preserves its creation timestamp.
	Update(context.Context, *journals.Journal) error
}

type Note struct {
	ID      uuid.UUID
	Content []byte
	Path    string
}

type NoteFilter struct {
	Type   string
	Tag    string
	Limit  int
	Offset int
}

type NoteKind string

type NoteStore interface {
	// Scan visits managed documents in stable path order without consulting the
	// index. Cancellation or a visitor error stops the scan.
	Scan(context.Context, func(Note) error) error

	// Put atomically creates or replaces the document identified by Note.ID and
	// returns its storage path. Updating its index is a separate operation.
	Put(context.Context, Note) (string, error)

	// Get reads the complete document and its path, or returns ErrNoteNotFound.
	Get(context.Context, uuid.UUID) (Note, error)

	// Delete removes the source document. Missing documents are treated as already
	// deleted; ambiguous UUIDs must be rejected before removing any file.
	Delete(context.Context, uuid.UUID) error
}

type NoteSummary struct {
	ID        uuid.UUID
	Type      string
	Label     string
	Tags      []string
	UpdatedAt time.Time
}

type PageCodec interface {
	// Encode writes the managed header followed by the entity's content.
	Encode(*pages.Page) ([]byte, error)

	// Decode requires the expected note kind and retains the original body bytes.
	Decode([]byte) (*pages.Page, error)
}

type PageRepository interface {
	// Save persists the entity's document and refreshes its searchable projection.
	Save(context.Context, *pages.Page) error

	// ByID decodes the source document and verifies its kind and requested UUID.
	ByID(context.Context, uuid.UUID) (*pages.Page, error)

	// Update requires an existing entity and preserves its creation timestamp.
	Update(context.Context, *pages.Page) error
}

type PersonCodec interface {
	// Encode writes the managed header followed by the entity's content.
	Encode(*persons.Person) ([]byte, error)

	// Decode requires the expected note kind and retains the original body bytes.
	Decode([]byte) (*persons.Person, error)
}

type PersonRepository interface {
	// Save persists the entity's document and refreshes its searchable projection.
	Save(context.Context, *persons.Person) error

	// ByID decodes the source document and verifies its kind and requested UUID.
	ByID(context.Context, uuid.UUID) (*persons.Person, error)

	// Update requires an existing entity and preserves its creation timestamp.
	Update(context.Context, *persons.Person) error
}

type RawNoteCodec interface {
	// Inspect validates identity and metadata using only the header, allowing
	// documents with invalid bodies to be opened for repair.
	Inspect([]byte) (RawNoteHeader, error)

	// Stamp replaces only the effective header update-time value, preserving all
	// other bytes. Callers validate the resulting document before persistence.
	Stamp([]byte, time.Time) ([]byte, error)

	// Decode validates supported AsciiDoc syntax and the typed domain fields. A nonempty
	// expected kind must match the header; an empty kind accepts any supported kind.
	Decode(NoteKind, []byte) (RawNoteHeader, error)
}

type RawNoteHeader struct {
	ID       uuid.UUID
	Kind     NoteKind
	Metadata shared.EntityMetadata
	// Date is the fixed calendar date for journals and empty for other kinds.
	Date string
}