@wirecat/cli-core 0.20.0 → 0.262.0

package/dist/store/store.d.ts

@@ -0,0 +1,843 @@
+import type { TextRange } from "../conversations/chunks.js";
+import type { Link, LinkInput } from "../conversations/link.js";
+import type { DownloadedFile } from "../domain/attachments.js";
+import type { ChannelTagMatch } from "../domain/channel-tags.js";
+import type { CounterObservations, CounterState } from "../domain/counters.js";
+import type { Chat, ChatKind, Contact, Id, Member, Message, MessageHit, Page, PersonAlias, Provider, Reactions, WindowedMessage } from "../domain/models.js";
+import type { RetentionOptions } from "../domain/retention.js";
+import type { MeetingContextStore, MeetingSearchIndexStore, MeetingSearchStore, MeetingStore, MeetingTranscriptReceiptStore, MeetingTranscriptStore } from "../meetings/index.js";
+import type { PeopleLookup } from "../resolve.js";
+import { type AccountGroups, type Profiles } from "../search/account-list.js";
+import type { QueryExecution } from "../search/lucene/resolved.js";
+import type { Stemmers } from "../search/stem.js";
+import { type AccountStore } from "./account-store.js";
+import { type AdminStoreRequest, type AdminStoreResult } from "./sqlite/admin-statistics.js";
+import { type AgentActionsStore } from "./sqlite/agent-actions.js";
+import type { AttachmentTextEntry, AttachmentView, FileAttachment } from "./sqlite/attachment-texts.js";
+import { type BotUpdateStore } from "./sqlite/bot-updates.js";
+import type { ChatMetadata } from "./sqlite/chats.js";
+import type { ChatCompleteness } from "./sqlite/completeness.js";
+import { type ConversationEligibility } from "./sqlite/conversation-eligibility.js";
+import { type CounterTarget } from "./sqlite/counters.js";
+import { type DocumentLinkMessage } from "./sqlite/document-links.js";
+import { type MailStore } from "./sqlite/emails.js";
+import { type FactsStore } from "./sqlite/facts.js";
+import { type InvolvementStore } from "./sqlite/involvements.js";
+import { type KnowledgeStore } from "./sqlite/knowledge.js";
+import type { QueryGroup, QueryGrouping } from "./sqlite/lucene.js";
+import type { MeetingReadCapabilities } from "./sqlite/meeting-reads.js";
+import { type MeetingVectors } from "./sqlite/meeting-vectors.js";
+import { type MemoriesStore } from "./sqlite/memories.js";
+import { type NotesStore } from "./sqlite/notes.js";
+import type { PrivateContact, PrivateContactNote } from "./sqlite/private-people.js";
+import { type ProposedActionsStore } from "./sqlite/proposed-actions.js";
+import { type RankedEvidence, type RankingEvidenceRequest } from "./sqlite/ranking-evidence.js";
+import { type RankedStoreFound, type RankingRequest } from "./sqlite/rankings.js";
+import { type RetentionResult } from "./sqlite/retention.js";
+import type { MemberCount, MemberStay, ProfileRevision, RosterChange, RosterRead, TrackedChat } from "./sqlite/roster.js";
+import type { SearchIndexFill, SearchIndexState } from "./sqlite/search-index.js";
+import type { SearchRecord, StoredSearch } from "./sqlite/searches.js";
+import type { StemsFill, StemsState } from "./sqlite/stems.js";
+import type { StoredTag, TagFilter, TagTarget } from "./sqlite/tags.js";
+import { type StoreTaskStore } from "./sqlite/tasks.js";
+import type { ChunkToEmbed } from "./sqlite/vectors.js";
+import type { ScoredHit, SearchScope, WordOptions, WordQuery } from "./sqlite/words.js";
+/** Which account of which messenger a call is about. */
+export interface AccountKey {
+    provider: Provider;
+    account: Id;
+    scope?: "personal" | "work";
+}
+/** An account as the store holds it: `id` is what `meetings` and `mail` take. */
+export interface StoredAccount {
+    id: number;
+    provider: Provider;
+    account: Id;
+    name: string | null;
+    scope: "personal" | "work";
+}
+/** Whether a stored chat may hold a message deleted without naming its chat. */
+export type DeletionScope = (chat: Pick<Chat, "id" | "kind" | "providerMetadata">) => boolean;
+/** How a message reached the store — `history`, `send`, `backfill`, `update`. Diagnostic. */
+export type IngestedVia = string;
+export interface StoredHit extends MessageHit {
+    locator: string;
+}
+/** What a provider says about a person. `null` or absent never erases what was known. */
+export interface PersonFacts {
+    id: Id;
+    name: string | null;
+    username?: string | null;
+    isBot?: boolean | null;
+    description?: string | null;
+}
+/**
+ * Which messages `find` returns. At least `text` or `senders`.
+ *
+ * `together` keeps only the chats where **every** sender has a message in this store — written
+ * there, as far as this copy knows, which is not the same as being a member.
+ */
+/** One identity in one messenger, by the messenger's own id. `provider` is any string: `email` is one. */
+export interface IdentityRef {
+    provider: Provider;
+    id: Id;
+}
+/** How a link was decided (`manual`, `same-email`) and who decided it (`owner`, a program's name). */
+export interface LinkOptions {
+    method: string;
+    by: string;
+}
+export interface LinkedIdentity extends IdentityRef {
+    name: string | null;
+    username: string | null;
+    isBot: boolean | null;
+    /** The accounts in this store that have seen it. */
+    accounts: Id[];
+    method: string;
+    linkedBy: string;
+    linkedAt: string;
+}
+/** A person across messengers: `uid` stays the same however their names change. */
+export interface PersonRecord {
+    uid: string;
+    name: string | null;
+    identities: LinkedIdentity[];
+}
+/** What a search of one account's messages takes, the account given apart. */
+export interface AccountMessageFilter {
+    senders?: Id[];
+    together?: boolean;
+    text?: string;
+    /**
+     * Tested against each stored message's text, newest first, in JavaScript — no index serves it, so
+     * it reads the chat (or the account) until `limit` match. Not with `text` or `perChat`.
+     */
+    pattern?: RegExp;
+    signal?: AbortSignal;
+    /** Only this chat of the account. */
+    chatId?: Id;
+    /** With `perChat`, the newest `limit` of each chat rather than of all of them together. */
+    limit: number;
+    perChat?: boolean;
+}
+/** A chat id is one account's, so `chatId` comes only with `account`. */
+export type MessageFilter = AccountMessageFilter & {
+    provider?: Provider;
+    /** Several accounts of `provider`, by native id — a read across some of them, never all by accident. */
+    accounts?: Id[];
+} & ({
+    account: AccountKey;
+} | {
+    account?: undefined;
+    chatId?: undefined;
+});
+export interface Delta {
+    chats?: Chat[];
+    people?: PersonFacts[];
+    members?: Map<Id, Id[]>;
+    state?: Record<string, string>;
+}
+export interface StoredChatFilter {
+    query?: string;
+    kind?: Chat["kind"];
+    unread?: boolean;
+}
+export interface MessageStore {
+    /** Answers the store's id for the account, which `meetings` and `mail` take. */
+    saveAccount(key: AccountKey, account: {
+        name: string | null;
+    }): Promise<number>;
+    saveChats(key: AccountKey, chats: Chat[]): Promise<void>;
+    /** A scheduled message is not kept: it is not history yet. */
+    /**
+     * `seenAt` is when the messenger was asked: a message it still returned is not deleted, so a
+     * tombstone older than that is lifted. A tombstone set after it stays — the deletion is newer.
+     */
+    saveMessages(key: AccountKey, chatId: Id, messages: Message[], options: {
+        via: IngestedVia;
+        seenAt?: number;
+    }): Promise<void>;
+    /** Newest first. `query` matches three letters or more of a title; `unread` keeps chats with unread messages. */
+    chats(key: AccountKey, window: {
+        limit?: number;
+        offset?: number;
+    } & StoredChatFilter): Promise<Page<Chat>>;
+    countChats(key: AccountKey, filter?: StoredChatFilter): Promise<number>;
+    /** Replaces who is in a chat with this list, whole: a person left out has left. */
+    saveMembers(key: AccountKey, chatId: Id, memberIds: Id[]): Promise<void>;
+    /** Who is in a chat, by name, as the last list said; empty when no list was ever saved. */
+    members(key: AccountKey, chatId: Id): Promise<Member[]>;
+    /**
+     * One read of a group's member list: stays opened and kept, a stay closed only when the read was whole,
+     * profiles revised when they differ, today's count. The chat's present members become the list read whole.
+     */
+    saveRoster(key: AccountKey, chatId: Id, read: RosterRead): Promise<RosterChange>;
+    /** Stays open at `since` (ISO) or begun after it, oldest first; every stay without it. */
+    memberStays(key: AccountKey, chatId: Id, options?: {
+        since?: string;
+    }): Promise<MemberStay[]>;
+    /** One row a day, oldest first; from `since` (`YYYY-MM-DD`) when given. */
+    memberCounts(key: AccountKey, chatId: Id, options?: {
+        since?: string;
+    }): Promise<MemberCount[]>;
+    /** Every profile the chat's members were seen with, oldest first. */
+    profileRevisions(key: AccountKey, chatId: Id, options?: {
+        since?: string;
+    }): Promise<ProfileRevision[]>;
+    /** Starts or stops `serve`'s daily fetch of the chat's members; history already kept stays. */
+    trackMembers(key: AccountKey, chatId: Id, tracked: boolean): Promise<void>;
+    trackedChats(key: AccountKey): Promise<TrackedChat[]>;
+    /** The chats a person is in, newest first — as far as the saved member lists go. */
+    chatsWith(key: AccountKey, memberId: Id): Promise<Chat[]>;
+    /** What a sync remembered under `name` for this account, and when; a caller encodes a number itself. */
+    syncState(key: AccountKey, name: string): Promise<{
+        value: string;
+        at: string;
+    } | undefined>;
+    setSyncState(key: AccountKey, name: string, value: string): Promise<void>;
+    clearSyncState(key: AccountKey, name: string): Promise<void>;
+    /**
+     * A catch-up's whole answer in one transaction, so a reader never sees half of it: chats, people,
+     * each listed chat's members (replaced whole) and sync state such as a delta marker.
+     */
+    applyDelta(key: AccountKey, delta: Delta): Promise<void>;
+    /**
+     * Takes the stretch of a chat at `anchor` for `forMs`; answers whether `holder` has it. Refused
+     * while another holder's lease runs; the same holder renews its own.
+     */
+    claim(key: AccountKey, chatId: Id, anchor: string, holder: string, forMs: number): Promise<boolean>;
+    /** Gives the stretch back, if `holder` still has it. */
+    release(key: AccountKey, chatId: Id, anchor: string, holder: string): Promise<void>;
+    /** What a voice message said, when it was heard before, and by what. */
+    transcript(key: AccountKey, chatId: Id, messageId: Id): Promise<{
+        text: string;
+        source: string;
+    } | undefined>;
+    /** Keeps a finished transcript; an empty one is not kept, so the message is heard again. */
+    keepTranscript(key: AccountKey, chatId: Id, messageId: Id, text: string, source: string): Promise<void>;
+    /**
+     * Where `messages download` saved a held message's files, for reading them later. Answers how many
+     * attachments it recorded: a file it cannot tell apart from another is not recorded.
+     */
+    keepDownloads(key: AccountKey, chatId: Id, messageId: Id, files: readonly DownloadedFile[]): Promise<number>;
+    /** File attachments of this account's live messages, newest first, below `beforePk`; never one an agent wrote. */
+    fileAttachments(key: AccountKey, page: {
+        chatId?: Id;
+        messageId?: Id;
+        beforePk?: number;
+        limit: number;
+    }): Promise<FileAttachment[]>;
+    /** File attachments of live messages and what is held of their text, newest first; never the text. */
+    attachments(key: AccountKey, filter: {
+        chatId?: Id;
+        messageId?: Id;
+        needsText?: boolean;
+        offset?: number;
+        limit: number;
+    }): Promise<AttachmentView[]>;
+    /** Where the file of one attachment was saved, when that is recorded. */
+    localPathOf(attachmentPk: number): Promise<string | null>;
+    /** An extraction never replaces an agent's text; answers whether it was kept. */
+    keepAttachmentText(attachmentPk: number, entry: AttachmentTextEntry): Promise<boolean>;
+    /** A chat's live messages for the conversation rules, oldest first; pass `next` back as `after`. */
+    linkInputs(key: AccountKey, chatId: Id, page: {
+        after?: string;
+        limit: number;
+    }): Promise<{
+        items: LinkInput[];
+        next: string | null;
+    }>;
+    /** Who wrote in the chat, by lowercased username: what an `@mention` names. */
+    senderHandles(key: AccountKey, chatId: Id): Promise<Map<string, Id>>;
+    /**
+     * The chat's provider and rule links and its conversations, rebuilt: written as a new build in short
+     * transactions and made current in one, so readers never see half of it and a failed build changes nothing.
+     */
+    replaceConversations(key: AccountKey, chatId: Id, build: ConversationBuild): Promise<void>;
+    /** Newest first; `after` and `before` bound when a conversation started. */
+    conversations(key: AccountKey, chatId: Id, window: {
+        limit: number;
+        after?: string;
+        before?: string;
+    }): Promise<Page<ConversationSummary>>;
+    /** Its messages oldest first; `undefined` when the account has no such conversation. */
+    conversation(key: AccountKey, id: string): Promise<{
+        summary: ConversationSummary;
+        messages: Message[];
+    } | undefined>;
+    /** Which conversation a message is in, once the chat is built. */
+    conversationOf(key: AccountKey, chatId: Id, messageId: Id): Promise<string | undefined>;
+    /** The conversation of the current build each message is in, in the same order; `undefined` where none. */
+    conversationsOfMessages(key: AccountKey, refs: {
+        chatId: Id;
+        messageId: Id;
+    }[]): Promise<(ConversationSummary | undefined)[]>;
+    /** Every link a message has, the messenger's first. */
+    links(key: AccountKey, chatId: Id, messageId: Id, options?: {
+        limit: number;
+    }): Promise<StoredLink[]>;
+    replies?(key: AccountKey, chatId: Id, messageId: Id, limit: number): Promise<Page<{
+        messageId: Id;
+    }>>;
+    /** The user's agent's current answer per message: its parent, or `null` for "starts a conversation". */
+    agentAnswers(key: AccountKey, chatId: Id): Promise<Map<Id, Id | null>>;
+    /** Stores the agent's answer to a batch, checked whole first; answers how many were stored (A5). */
+    saveAnswers(key: AccountKey, batch: string, answer: AgentAnswer): Promise<{
+        chat: Id;
+        stored: number;
+    }>;
+    /** Drops the agent's answers for a chat, or one model's; answers how many. Messages are never touched. */
+    clearAnswers(key: AccountKey, chatId: Id, model?: string): Promise<number>;
+    /** How many messages still need the user's agent, and their characters (phase 4). */
+    batchStatus(key: AccountKey, chatId: Id): Promise<{
+        messages: number;
+        characters: number;
+    }>;
+    /** The earliest window holding a message the agent has not answered; `undefined` when none is left. */
+    nextBatch(key: AccountKey, chatId: Id, options: {
+        size: number;
+    }): Promise<LinkBatch | undefined>;
+    /** Chunks of the chat's current build with no vector of `model`, by hash after `after` (phase 5). */
+    chunksToEmbed(key: AccountKey, chatId: Id, model: string, options: {
+        after?: string;
+        limit: number;
+    }): Promise<ChunkToEmbed[]>;
+    saveVectors(model: string, dims: number, vectors: {
+        hash: string;
+        vector: Float32Array;
+    }[]): Promise<void>;
+    /** The current build's distinct chunks, and how many have a vector of `model`. */
+    vectorStatus(key: AccountKey, chatId: Id, model: string): Promise<{
+        chunks: number;
+        embedded: number;
+    }>;
+    /** Drops the chat's vectors, or one model's; a vector another chat's chunk shares stays. */
+    clearVectors(key: AccountKey, chatId: Id, model?: string): Promise<number>;
+    /** The conversations nearest in meaning to `query`, in one chat or every one of the account, best first. */
+    nearestConversations(key: AccountKey, options: {
+        chatId?: Id;
+        model: string;
+        since?: string;
+        limit: number;
+        query: Float32Array;
+        exclude?: string;
+        conversations?: string[];
+        scope?: "personal" | "work";
+        projectId?: string;
+        personId?: string;
+        before?: string;
+    }): Promise<ConversationHit[]>;
+    /**
+     * A conversation of the current build: how many chunks it has, and the vectors of `model` of those whose
+     * messages did not change since — none when it is not the account's or not current.
+     */
+    conversationVectors(key: AccountKey, id: string, model: string): Promise<{
+        chunks: number;
+        vectors: Float32Array[];
+    }>;
+    /**
+     * How fresh each built chat's conversations and `model`'s vectors are — one chat, or every chat whose
+     * conversations were ever built. A chat never built answers `builtAt: null`.
+     */
+    readiness(key: AccountKey, options: {
+        chatId?: Id;
+        model: string;
+    }): Promise<StoredReadiness[]>;
+    /** Group chats with stored messages whose conversations were never built, the newest message first. */
+    unbuiltGroups(key: AccountKey): Promise<Id[]>;
+    /** Chats in scope embedded with another model and not with `model`, which a search with it cannot see. */
+    embeddedOnlyElsewhere(key: AccountKey, options: {
+        chatId?: Id;
+        model: string;
+    }): Promise<Id[]>;
+    /** Whether the chat's conversations were built, and when; `undefined` when never. */
+    conversationState(key: AccountKey, chatId: Id): Promise<{
+        enabledAt: string;
+        builtAt: string | null;
+        algorithmVersion: number | null;
+    } | undefined>;
+    /** Oldest to newest, like a provider's history page. */
+    /** `threadId` keeps one forum topic's; `outgoing` only the owner's (true) or only the others' (false). */
+    messages(key: AccountKey, chatId: Id, window: {
+        limit: number;
+        before?: Id;
+        since?: string;
+        threadId?: Id;
+        outgoing?: boolean;
+    }): Promise<Page<Message>>;
+    /** How many stored messages the chat has, sent at `since` or later when it is given. */
+    countMessages(key: AccountKey, chatId: Id, options?: {
+        since?: string;
+    }): Promise<number>;
+    /** The chat's messages that may hold a Google document link, newest first, with the documents linked from each. */
+    documentLinkMessages(key: AccountKey, chatId: Id): Promise<DocumentLinkMessage[]>;
+    /** Saved or edited after `at` (ISO, this machine's clock), oldest first, and the ids deleted after it. */
+    changes(key: AccountKey, chatId: Id, at: string): Promise<{
+        messages: Message[];
+        deleted: Id[];
+    }>;
+    /**
+     * By time rather than by id: `before` messages sent at `at` or earlier and `after` sent later,
+     * oldest first. `around` answers the same question for a message id.
+     */
+    messagesWindow(key: AccountKey, chatId: Id, window: {
+        at: string;
+        before: number;
+        after: number;
+    }): Promise<Message[]>;
+    /**
+     * A stored message and its stored neighbours, oldest first, the one asked for with `anchor`. Until
+     * backfill records which stretches are complete, a neighbour here is the nearest one kept, not
+     * necessarily the next one sent.
+     */
+    around(key: AccountKey, chatId: Id, messageId: Id, window: {
+        before: number;
+        after: number;
+    }): Promise<WindowedMessage[]>;
+    /**
+     * One message by its id. Without `chatId` it is looked up across the account, which is enough
+     * where ids are unique per account (MAX) and refused where two chats share one (Telegram).
+     */
+    message(key: AccountKey, messageId: Id, options?: {
+        chatId?: Id;
+    }): Promise<Message | undefined>;
+    /**
+     * Everything one account holds — its chats, messages, members, state, leases, transcripts and whom
+     * it has seen — for `cache clear`. Other accounts, and identities they share, stay.
+     */
+    purge(key: AccountKey): Promise<void>;
+    /**
+     * Given every chat the account is in, marks the rest `left` and says how many it marked. Only
+     * ever from a complete list: a page or a cut list says nothing about the chats it leaves out.
+     * Remembers when, so a search can say the store knows the account's whole chat list.
+     */
+    markChatsLeft(key: AccountKey, present: Id[]): Promise<number>;
+    /** The chats marked left and the messages they hold; with `clear`, deletes them and all under them. */
+    leftChats(key: AccountKey, options?: {
+        clear?: boolean;
+    }): Promise<{
+        chats: number;
+        messages: number;
+    }>;
+    /**
+     * A tombstone, not a removal: the row stays, so a copy fetched before the deletion does not bring
+     * the message back, and reads and search stop returning it. Its text goes — from the row, the
+     * search copy, the edit history and the transcript. Only the messenger returning it again, when
+     * asked after the deletion, lifts the tombstone (`saveMessages`' `seenAt`).
+     *
+     * Without `chatId`, a message is tombstoned only when exactly one live message with its id is left
+     * in the chats `among` accepts. Without `among`, nothing is: only the messenger knows which of its
+     * chats a deletion without one may belong to (`Messenger.deletedWithoutChat`).
+     */
+    markDeleted(key: AccountKey, messageIds: Id[], options?: {
+        chatId?: Id;
+        among?: DeletionScope;
+    }): Promise<number>;
+    /** Newest first. At least three characters: a trigram index answers a shorter query with nothing. */
+    search(query: string, options: {
+        limit: number;
+        account?: AccountKey;
+    }): Promise<Page<StoredHit>>;
+    /** Newest first — by text, by who wrote it, or both. */
+    find(filter: MessageFilter): Promise<Page<StoredHit>>;
+    /**
+     * The word index, ranked by bm25, ties newest first (phase 2 plan S4 steps 1, 2 and 4). Chats marked
+     * not searchable are left out unless the scope names the chat.
+     */
+    rankingDiscussionChats?(account: AccountKey, chatId: string): Promise<string[]>;
+    rankingEvidence?(execution: QueryExecution, request: RankingEvidenceRequest): Promise<RankedEvidence>;
+    retention?(key: AccountKey, chatId: Id, options: RetentionOptions, evidence?: {
+        cohort: string;
+        cursor?: string;
+    }): Promise<RetentionResult>;
+    adminStatisticsQuery?(execution: QueryExecution, request: AdminStoreRequest): Promise<AdminStoreResult>;
+    rankQuery?(execution: QueryExecution, request: RankingRequest): Promise<RankedStoreFound>;
+    directReplies?(parents: {
+        account: AccountKey;
+        chatId: Id;
+        id: Id;
+    }[], limit: number): Promise<Page<StoredHit>>;
+    matchQuery?(execution: QueryExecution): Promise<Page<ScoredHit>>;
+    conversationEligibility?(execution: QueryExecution): Promise<ConversationEligibility>;
+    /** The same matches as `matchQuery`, each counted once, grouped by chat, sender or quarter hour. */
+    countQuery?(execution: QueryExecution, by: QueryGrouping): Promise<QueryGroup[]>;
+    matchWords(query: WordQuery, scope: SearchScope, options: WordOptions): Promise<Page<ScoredHit>>;
+    /** The substring index, newest first (step 5); pieces under three letters are dropped. */
+    matchSubstring(query: WordQuery, scope: SearchScope, options: {
+        limit: number;
+    }): Promise<Page<ScoredHit>>;
+    /** The kinds of attachment held, for `has:` to name the ones it can find. */
+    attachmentKinds(): Promise<string[]>;
+    /** Messages matching the scope alone, newest first: a search with filters and no word. */
+    matchFilters(scope: SearchScope, options: {
+        limit: number;
+    }): Promise<Page<ScoredHit>>;
+    /** Per chat: whether its history is held up to date, without gaps, back to its start. */
+    chatCompleteness(key: AccountKey, chatIds: Id[]): Promise<ChatCompleteness[]>;
+    /** Of `terms`, those the index knows as a word or the beginning of one. */
+    knownTerms(terms: string[]): Promise<Set<string>>;
+    /** Known words sharing these trigrams, within the lengths, most shared first. */
+    termCandidates(trigrams: string[], lengths: {
+        shortest: number;
+        longest: number;
+    }): Promise<{
+        term: string;
+        docs: number;
+    }[]>;
+    /** How far the word index is built; `undefined` on a file before it existed. */
+    searchIndexState(): Promise<SearchIndexState | undefined>;
+    /**
+     * Builds the word index towards "ready" in short batches — the normalized text, the messages up to
+     * the watermark, the typo vocabulary — until done or `until` says stop. Each batch is its own write.
+     */
+    fillSearchIndex(options?: {
+        until?: () => boolean;
+    }): Promise<SearchIndexFill>;
+    /** How far the stems are built, and by which stemmer choices; `undefined` on a file before they existed. */
+    stemsState(): Promise<StemsState | undefined>;
+    /** Builds the stems towards "ready" in short batches until done or `until` says stop; never rebuilds. */
+    fillStems(options?: {
+        until?: () => boolean;
+    }): Promise<StemsFill>;
+    /**
+     * The stemmer choices saved in the store for every profile, tg and MAX; `undefined` while the defaults
+     * apply, `null` when a newer tool saved one this build does not know.
+     */
+    stemmers(): Promise<Stemmers | null | undefined>;
+    /** Saves them; stems built by other choices wait for `store reindex` or `store migrate`. */
+    saveStemmers(stemmers: Stemmers): Promise<void>;
+    /** The account groups `--source group:<name>` reads: each group's entries as saved, store-wide. */
+    accountGroups(): Promise<AccountGroups>;
+    /** Saves one group's entries; `undefined` removes the group. */
+    saveAccountGroup(name: string, members: string[] | undefined): Promise<void>;
+    /** Per app command, each profile's account: how `--source max:default` finds a profile of another app. */
+    profiles(): Promise<Profiles>;
+    /** Records which account a profile of `app` is; a no-op when the store already says so. */
+    saveProfile(app: string, profile: string, key: AccountKey): Promise<void>;
+    savePeople(key: AccountKey, people: PersonFacts[]): Promise<void>;
+    /**
+     * The people this account has a one-to-one chat with — as far as the saved member lists go —
+     * newest conversation first or by name. `query` matches three letters or more of a name or
+     * username.
+     */
+    contacts(key: AccountKey, options: {
+        order: "recent" | "name";
+        query?: string;
+        limit: number;
+        offset?: number;
+    }): Promise<Page<Contact>>;
+    countContacts(key: AccountKey, options?: {
+        query?: string;
+    }): Promise<number>;
+    /** Works out again when each contact was last written to, from their one-to-one chats. */
+    refreshRecency(key: AccountKey): Promise<void>;
+    /** Every account of every messenger the file holds, by messenger then id. */
+    accounts(): Promise<AccountKey[]>;
+    /** Every account with the store's id for it, by provider then external id. */
+    storedAccounts(): Promise<StoredAccount[]>;
+    /** One account by provider and external id, never created: `not_found` when the store has none. */
+    storedAccount(key: AccountKey): Promise<StoredAccount>;
+    /** The name the messenger last gave for this account; `null` when it never did. */
+    accountName(key: AccountKey): Promise<string | null>;
+    /** Everyone this provider's accounts have seen; with `account`, only who that account has seen. */
+    people(provider: Provider, options?: {
+        account?: Id;
+        accounts?: Id[];
+    }): Promise<PeopleLookup>;
+    personOf(identity: IdentityRef): Promise<PersonRecord | undefined>;
+    /** The person a `person:<uid>` reference names. */
+    personSeenInAccounts(uid: string, accountIds: readonly number[]): Promise<boolean>;
+    personByUid(uid: string): Promise<PersonRecord | undefined>;
+    /** Records the decision in `identity_link_events`; `unlinkIdentity` undoes it. */
+    linkIdentities(person: IdentityRef, other: IdentityRef, options: LinkOptions): Promise<PersonRecord>;
+    unlinkIdentity(identity: IdentityRef, options: LinkOptions): Promise<PersonRecord>;
+    /** Messages of the account that name this person, newest first. */
+    mentioning(key: AccountKey, person: {
+        id: Id;
+        username: string | null;
+    }, limit: number): Promise<Page<StoredHit>>;
+    /** A message's reactions as they are now; answers whether the message is held at all. */
+    saveReactions(key: AccountKey, chatId: Id, messageId: Id, reactions: Reactions, options?: {
+        observation?: CounterObservations["reactions"];
+    }): Promise<boolean>;
+    counterTargets?(execution: QueryExecution, options: {
+        now: number;
+        maxAge: number;
+    }): Promise<{
+        items: CounterTarget[];
+        hasMore: boolean;
+    }>;
+    counterStates?(key: AccountKey, chatId: Id, messageId: Id, options: {
+        now: number;
+        maxAge: number;
+    }): Promise<CounterState[]>;
+    updateCounterObservations?(key: AccountKey, chatId: Id, messageId: Id, observations: CounterObservations): Promise<number>;
+    /**
+     * Records that every message from `from` to `to` (inclusive, by ordering key) is held, merging it
+     * with the stretches it overlaps or touches. Answers the merged stretch.
+     */
+    markRange(key: AccountKey, chatId: Id, from: number, to: number): Promise<Range>;
+    /** Per chat that has messages: how many, the oldest and newest, and when the last one was stored. */
+    chatStats(key: AccountKey, chatId?: Id): Promise<ChatStats[]>;
+    /** Per chat that spoke since `since` (ms): its newest message and who sent it when stored, never the text. */
+    chatActivity(key: AccountKey, since: number): Promise<{
+        chats: ChatActivity[];
+        storedAt: string | null;
+    }>;
+    /** One person's stored messages per chat of this account, newest first. */
+    senderStats(key: AccountKey, senderId: Id): Promise<SenderChatStats[]>;
+    /** Every name and username this account's store recorded for one person, the current ones included. */
+    personNames(key: AccountKey, personId: Id): Promise<PersonAlias[]>;
+    /** The stretches held completely, oldest first. */
+    ranges(key: AccountKey, chatId: Id): Promise<Range[]>;
+    /** Labels one stored chat, person or message; answers the tags it did not have. `not_found` for one not held. */
+    chatMetadata(key: AccountKey, chatId: Id): Promise<ChatMetadata | undefined>;
+    saveChatMetadata(key: AccountKey, entry: Omit<ChatMetadata, "fetchedAt">): Promise<ChatMetadata>;
+    replaceAutoTags(key: AccountKey, chatId: Id, algorithm: string, tags: ChannelTagMatch[]): Promise<void>;
+    privateContact(key: AccountKey, personId: Id): Promise<PrivateContact>;
+    setContactAlias(key: AccountKey, personId: Id, alias: string | null): Promise<{
+        personId: Id;
+        alias: string | null;
+    }>;
+    addContactNote(key: AccountKey, personId: Id, text: string): Promise<PrivateContactNote>;
+    contactNote(key: AccountKey, personId: Id, id: string): Promise<PrivateContactNote>;
+    editContactNote(key: AccountKey, personId: Id, id: string, text: string, revision: number): Promise<PrivateContactNote>;
+    removeContactNote(key: AccountKey, personId: Id, id: string): Promise<{
+        id: string;
+        personId: Id;
+        removed: boolean;
+    }>;
+    addTags(key: AccountKey, target: TagTarget, tags: string[]): Promise<string[]>;
+    /** Answers the tags it had. */
+    removeTags(key: AccountKey, target: TagTarget, tags: string[], source?: "manual" | "auto"): Promise<string[]>;
+    /** The account's tagged chats and messages, and its messenger's tagged people. */
+    tags(key: AccountKey, filter?: TagFilter): Promise<StoredTag[]>;
+    /** One run of a search or stats; the same unnamed run again counts on its row. `saved` is the saved search it ran. */
+    recordSearch(run: SearchRecord, options?: {
+        saved?: string;
+    }): Promise<void>;
+    /** A saved search by name; a name already taken is refused unless `replace`. */
+    saveSearch(name: string, search: SearchRecord, options?: {
+        replace?: boolean;
+    }): Promise<StoredSearch>;
+    /** A saved search by name, or any row by id. */
+    storedSearch(reference: string): Promise<StoredSearch | undefined>;
+    savedSearches(): Promise<StoredSearch[]>;
+    /** Runs, newest first, one more than `limit` when there are more. */
+    searchHistory(limit: number): Promise<StoredSearch[]>;
+    deleteSearch(reference: string): Promise<StoredSearch>;
+    /** Drops the unnamed runs; answers how many. */
+    clearSearchHistory(): Promise<number>;
+    /** Open tasks waiting on the owner, for the task service in `src/tasks/`. */
+    readonly botUpdates: BotUpdateStore;
+    readonly involvements: InvolvementStore;
+    readonly tasks: StoreTaskStore;
+    readonly knowledge: KnowledgeStore;
+    /** Notes, the links between anything and anything, and the owner's organisations and projects. */
+    readonly notes: NotesStore;
+    /** Choices that hold until replaced, each with its evidence. */
+    readonly facts: FactsStore;
+    /** What agents concluded: summaries, digests, facts, preferences, each with evidence and a scope. */
+    readonly memories: MemoriesStore;
+    /** What an agent wants done outside the store, waiting for the owner's approval. */
+    readonly proposedActions: ProposedActionsStore;
+    /** One row per tool an agent called, never its arguments. */
+    readonly agentActions: AgentActionsStore;
+    /** Meetings and calendar events: the port `src/meetings/` defines. */
+    readonly meetingVectors: MeetingVectors;
+    readonly meetings: MeetingStore & MeetingTranscriptStore & MeetingReadCapabilities & MeetingSearchStore & MeetingTranscriptReceiptStore & MeetingContextStore & MeetingSearchIndexStore;
+    /** Email threads, emails, recipients and mailboxes. */
+    readonly mail: MailStore;
+    /** The same store with this account bound — what a service of one account reads and writes through. */
+    forAccount(key: AccountKey): AccountStore;
+    close(): Promise<void>;
+}
+/** One sender's stored messages in one chat. */
+export interface SenderChatStats {
+    chatId: Id;
+    title: string | null;
+    kind: ChatKind;
+    messages: number;
+    firstAt: string | null;
+    lastAt: string | null;
+}
+export interface ChatActivity {
+    chatId: Id;
+    title: string | null;
+    kind: ChatKind;
+    lastMessageAt: string;
+    /** `null` while the newest message is not stored: the chat list says the chat moved, nothing more. */
+    lastMessageId: Id | null;
+    /** `null` when the newest message is not stored, or the messenger did not say who sent it. */
+    lastFromOwner: boolean | null;
+}
+export interface ChatStats {
+    chatId: Id;
+    title: string | null;
+    messages: number;
+    oldestAt: string | null;
+    newestAt: string | null;
+    lastStoredAt: string | null;
+}
+/** One build of a chat's conversations, by message id; phase 3 plan C3. */
+export interface ConversationBuild {
+    check?: () => void;
+    /** When the build started reading: a change after it is not in the build. */
+    startedAt: number;
+    algorithmVersion: number;
+    links: Link[];
+    /** Message ids, each conversation oldest first. */
+    conversations: Id[][];
+    /** Each conversation's chunks, in the same order as `conversations` (phase 5). */
+    chunks?: {
+        firstId: Id;
+        lastId: Id;
+        hash: string;
+        range?: TextRange;
+    }[][];
+}
+/**
+ * A conversation found by meaning: the chunk that matched best, and how near it is (−1 to 1). `stale` when
+ * the chunk's messages no longer read as they did when it was embedded (NEED-550 B).
+ */
+export interface ConversationHit {
+    summary: ConversationSummary;
+    chunk: {
+        firstMessageId: Id;
+        lastMessageId: Id;
+    };
+    score: number;
+    stale: boolean;
+}
+export interface StoredReadiness {
+    chatId: Id;
+    builtAt: string | null;
+    algorithmVersion: number | null;
+    /** Messages the current build has not seen. */
+    pending: {
+        new: number;
+        edited: number;
+        deleted: number;
+    };
+    /** The current build's distinct chunk texts: `current` + `stale` + `missing`; `embedded` have any vector. */
+    vectors: {
+        chunks: number;
+        embedded: number;
+        current: number;
+        stale: number;
+        missing: number;
+    };
+}
+export interface ConversationSummary {
+    id: string;
+    chatId: Id;
+    firstMessageId: Id;
+    firstAt: string;
+    lastAt: string;
+    messageCount: number;
+    /** How many people wrote in it. */
+    senders: number;
+    builtAt: string;
+    algorithmVersion: number;
+}
+/** One message as the user's agent sees it in a batch (phase 4 plan A4). */
+export interface BatchMessage {
+    id: Id;
+    at: string;
+    sender: {
+        id: Id | null;
+        name: string | null;
+    };
+    text: string;
+    /** The message it answers, by the messenger's own record. */
+    replyTo?: Id;
+    thread?: Id;
+    mentions?: Id[];
+    /** `true`: the agent is asked which earlier message this one answers. `false`: context only. */
+    answer: boolean;
+    /** For a message to answer: the current build's messenger and rule links, strongest first. */
+    candidates?: {
+        parent: Id | null;
+        source: string;
+        kind: string;
+        confidence: number;
+    }[];
+}
+/** What the user's agent returns for a batch (phase 4 plan A5), as read from stdin. */
+export interface AgentAnswer {
+    /** The model that answered; stored as the link's method. */
+    model: string;
+    /** The skill's version, when the skill sends it. */
+    skill?: string;
+    answers: {
+        message: Id;
+        parent: Id | null;
+        confidence: number;
+    }[];
+}
+/** A window of a chat for the agent: the messages to answer and the ones before them (A1). */
+export interface LinkBatch {
+    /** Names the window, so an answer can be checked against it (A3). */
+    batch: string;
+    chat: Id;
+    messages: BatchMessage[];
+    /** Messages still needing the agent after this batch, and their characters. */
+    remaining: {
+        messages: number;
+        characters: number;
+    };
+}
+export interface StoredLink {
+    /** `null`: the source says the message starts a conversation. */
+    parentId: Id | null;
+    source: "provider" | "rule" | "agent";
+    kind: string;
+    confidence: number;
+    method: string;
+    version: string | null;
+    createdAt: string;
+    /** An end changed after the link was written; it is not chosen. */
+    stale: boolean;
+}
+export interface Range {
+    from: number;
+    to: number;
+}
+export interface StoreOptions {
+    path?: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    /** The CLI's own name, for the advice a failed migration gives. */
+    command?: string;
+}
+/** About 40 ms of the first open (129k rows/s measured at 1M, 2026-09-30); Tab opens the store too. */
+export declare const BACKFILL_ON_OPEN = 5000;
+export declare const openStore: ({ path, env, now, command }?: StoreOptions) => Promise<MessageStore>;
+export type { CounterField, CounterObservations, CounterState } from "../domain/counters.js";
+export type { RetentionOptions } from "../domain/retention.js";
+export { accountGroupsOf } from "./sqlite/account-groups.js";
+export type { AdminStoreRequest, AdminStoreResult } from "./sqlite/admin-statistics.js";
+export { type AttachmentTextEntry, type AttachmentView, type FileAttachment, resetAttachmentWords, type TextOrigin, } from "./sqlite/attachment-texts.js";
+export { pendingNormalization } from "./sqlite/backfill.js";
+export { CHAT_LIST_KEY, type ChatCompleteness, fetchedKey, historyStartKey } from "./sqlite/completeness.js";
+export type { CounterTarget } from "./sqlite/counters.js";
+export { messageOfEmail, threadConversation } from "./sqlite/emails.js";
+export { orphanPointers } from "./sqlite/entity-types.js";
+export { involvementStoreOver } from "./sqlite/involvements.js";
+export type { MeetingReadCapabilities } from "./sqlite/meeting-reads.js";
+export type { MeetingVectors } from "./sqlite/meeting-vectors.js";
+export { drainNoteIndex, noteIndexState, resetNoteIndex } from "./sqlite/note-index.js";
+export type { Link as ThingLink } from "./sqlite/notes.js";
+export type { ProposedAction } from "./sqlite/proposed-actions.js";
+export type { RankedEvidence, RankingEvidenceItem, RankingEvidenceRequest } from "./sqlite/ranking-evidence.js";
+export type { RankedStoreFound, RankedStoreRow, RankingRequest } from "./sqlite/rankings.js";
+export type { RetentionResult } from "./sqlite/retention.js";
+export type { MemberCount, MemberStay, ProfileRevision, RosterChange, RosterRead, TrackedChat, } from "./sqlite/roster.js";
+export { fillSearchIndex, resetSearchIndex, searchIndexState } from "./sqlite/search-index.js";
+export type { SearchCommand, SearchRecord, StoredSearch } from "./sqlite/searches.js";
+export { fillStems, resetStems, type StemsState, savedStemmers, stemmerCache, stemmersOrigin, stemsState, } from "./sqlite/stems.js";
+export type { StoredTag, TagFilter, TagTarget } from "./sqlite/tags.js";
+export { inboxKey } from "./sqlite/tasks.js";
+export type { MatchPlace, ScoredHit, SearchScope, WordOptions, WordQuery } from "./sqlite/words.js";
+export type { TaskDetails } from "./sqlite/work-tasks.js";
+//# sourceMappingURL=store.d.ts.map