@aigne/afs-index 1.12.0-beta.5

package/dist/types.d.cts

@@ -0,0 +1,393 @@
+import { IndexBackend } from "./backend/types.cjs";
+import { AFSRoot } from "@aigne/afs";
+
+//#region src/types.d.ts
+interface Anchor {
+  type: string;
+  confidence: number;
+  [key: string]: unknown;
+}
+interface TimeAnchor extends Anchor {
+  type: "time";
+  timestamp?: string;
+  interval?: {
+    start?: string;
+    end?: string;
+  };
+  granularity?: string;
+}
+/**
+ * Named granularities that `generateTimeKeys` can emit per time anchor.
+ * Used by `AFSIndexOptions.timeKeyGranularity` to cap write amplification.
+ */
+type TimeKeyGranularity = "year" | "month" | "day" | "quarter" | "week" | "season" | "weekday" | "daytime";
+interface LocationAnchor extends Anchor {
+  type: "location";
+  geohash: string;
+  city?: string;
+  place?: {
+    country?: string;
+    region?: string;
+    city?: string;
+    name?: string;
+  };
+  precision?: number;
+}
+interface PersonAnchor extends Anchor {
+  type: "person";
+  personRef?: string;
+  name?: string;
+  role?: string;
+}
+interface TopicAnchor extends Anchor {
+  type: "topic";
+  value: string;
+}
+type EntryState = "active" | "stale" | "removed";
+interface IndexedEntry {
+  entryPath: string;
+  sourcePath?: string;
+  sourceHash?: string;
+  domain: string;
+  state: EntryState;
+  extractorId?: string;
+  indexedAt: string;
+  updatedAt: string;
+  anchorCount: number;
+  meta?: Record<string, unknown>;
+}
+interface AnchorData {
+  entryPath: string;
+  anchorType: string;
+  confidence: number;
+  rawAnchor: string;
+}
+/**
+ * Query recall strategy for `.actions/query` / `QueryEngine.query`. Per-mode
+ * semantics live in `query/engine.ts`:
+ * - "anchor"   — pure anchor-based query
+ * - "fts"      — pure full-text search
+ * - "combined" — RRF fusion of anchor + FTS ranked lists
+ * - "semantic" — RRF fusion + embedding fallback
+ *
+ * `SEARCH_MODES` is the single source of truth — the `.actions/query` zod enum,
+ * `QueryInput.mode`, and the `AFS_INDEX_SEARCH_MODE` env coercion all derive
+ * from it, so a new mode is added in exactly one place.
+ */
+declare const SEARCH_MODES: readonly ["anchor", "fts", "combined", "semantic"];
+type SearchMode = (typeof SEARCH_MODES)[number];
+/**
+ * Default query mode when a caller doesn't pass `mode` and the deployment
+ * didn't configure `AFSIndexOptions.defaultSearchMode`. Kept at the historical
+ * `.actions/query` default so an unconfigured deployment is byte-identical.
+ */
+declare const DEFAULT_SEARCH_MODE: SearchMode;
+/**
+ * Coerce an untrusted string (typically the `AFS_INDEX_SEARCH_MODE` env var)
+ * into a `SearchMode`. Source-agnostic — receives an already-read string and
+ * never touches `process.env`/`env`, so it behaves identically in Cloudflare
+ * Workers and Node (same discipline as `parseBool` from `@aigne/afs/utils/env`).
+ * lower-case + trim + allow-list; anything unrecognized (including
+ * `undefined`/empty) falls back to `DEFAULT_SEARCH_MODE` and never throws —
+ * mirrors the CF `resolveVectorIndexBackend` shape for `AFS_INDEX_VECTOR_BACKEND`.
+ */
+declare function coerceSearchMode(value?: string): SearchMode;
+interface StaleFilter {
+  extractorId?: string;
+  domain?: string;
+  scope?: string;
+  anchorType?: string;
+  /**
+   * Cross-blocklet tenant boundary (`domain IN (...)`): restrict the operation
+   * to the caller's own declared domains. The provider injects
+   * `AFSIndexOptions.boundDomains` here so `reindex`/`cleanup` can't touch
+   * another blocklet's rows in the shared per-user index — the write/mutate
+   * counterpart of the query-path `AnchorQuery.domains`. Orthogonal to the
+   * backend's own tenant `scope` column (cross-user).
+   */
+  boundDomains?: string[];
+}
+interface EntryFilter {
+  domain?: string;
+  state?: EntryState;
+  extractorId?: string;
+  scope?: string;
+  /** See `StaleFilter.boundDomains` — same cross-blocklet boundary for reads/counts. */
+  boundDomains?: string[];
+}
+interface AnchorQuery {
+  keys: {
+    type: string;
+    values: string[];
+  }[];
+  scope?: string;
+  /** entry_path prefix filter (`entry_path LIKE '{pathPrefix}%'`) — see `QueryOpts.pathPrefix`. */
+  pathPrefix?: string;
+  /**
+   * Restrict results to entries whose `domain` is one of these values
+   * (`ie.domain IN (...)`). Used by the `boundDomains` query-time fallback
+   * (see `AFSIndexOptions.boundDomains`) — never set by client-facing
+   * `.actions/query` args directly.
+   */
+  domains?: string[];
+  minConfidence?: number;
+  limit?: number;
+  metaFilter?: Record<string, unknown>;
+}
+interface QueryOpts {
+  scope?: string;
+  /**
+   * Restrict results to entries whose `entry_path` starts with this prefix
+   * (`entry_path LIKE '{pathPrefix}%'`), pushed into the backend BEFORE
+   * `ORDER BY … LIMIT` so the top-K comes from the subtree, not from the whole
+   * scope filtered afterwards. Distinct from `scope` (which FTS treats as a
+   * domain-name shorthand — see sqlite `fts_query`): `pathPrefix` is always a
+   * literal entry_path prefix. Used by `SessionUserAFS.search` to scope a
+   * `/user/<sub>` search to its subtree so a text query returns that subtree's
+   * items instead of being crowded out of the cross-collection top-K (and then
+   * falling through to the O(N) naive scan). Applied to the already
+   * MATCH/anchor-bounded result set over the `(scope, entry_path)` index, so it
+   * adds no full-table scan at scale.
+   */
+  pathPrefix?: string;
+  decay?: {
+    lambda: number;
+  };
+  minConfidence?: number;
+  limit?: number;
+  /**
+   * Opaque continuation cursor returned by `.actions/query`.
+   * Consumers must treat it as an implementation detail; changing any query
+   * dimension invalidates the cursor.
+   */
+  cursor?: string;
+  minResults?: number;
+  /** Filter entries by meta field values. Each key is a meta field name, value is exact match or array (OR). Applied at the backend level before limit. */
+  metaFilter?: Record<string, unknown>;
+  /**
+   * Treat the query `anchors` as a HARD FILTER (constraint) rather than a soft
+   * RRF fusion signal (Epic #932 S2/S3 facet search): when true, results MUST
+   * match the anchors AND (if `text`/`embedding` given) the text — the
+   * anchor-matching set intersects the text results instead of being unioned
+   * into the fusion. Facet-only (no text) returns the anchor set directly.
+   * Default false preserves the existing combined/semantic fusion behavior for
+   * every current consumer (memory recall, arch-qa, …).
+   */
+  anchorFilter?: boolean;
+  /**
+   * Relevance floor for PURE-embedding matches (semantic mode). An entry that
+   * matched only via the embedding list (no FTS/anchor signal) is dropped when
+   * its cosine similarity is below this value; entries with an FTS/anchor match
+   * always pass. Undefined = no floor (top-K nearest neighbors returned as-is).
+   * The value is model-specific (e5-small compresses cosines ~0.75–0.85, bge-m3
+   * spreads wider) — set it where the embed model is wired, not here.
+   */
+  embeddingFloor?: number;
+  /**
+   * Debug/explainability mode (issue #1069 — "为什么某条能被匹配/record，把原因
+   * log 出来"). When true, each `QueryResult` is decorated with a human-readable
+   * `explanation` of why it matched (which signal(s): anchor filter / FTS query
+   * / cosine similarity, plus rank + raw sub-score, and — for combined/semantic
+   * fusion — every contributing source with its RRF math), and anchor-mode
+   * results additionally carry the entry's actual matched `AnchorData[]`.
+   * Default false: zero cost, byte-identical `results` shape for every existing
+   * caller. This is per-RESULT explainability — narrower than the existing
+   * `AFSIndex` provider-level `opts.explain` (see index-provider.ts
+   * `buildExplanation`), which answers the aggregate "why is the whole
+   * response empty" question (planning/memory-system-improvements/design.md
+   * §P4). The provider passes its own `explain` flag straight through into
+   * this field so one `explain: true` on `.actions/query` turns on both.
+   */
+  explain?: boolean;
+}
+type MatchType = "anchor" | "fts" | "embedding";
+interface QueryResult {
+  entryPath: string;
+  matchType: MatchType;
+  score: number;
+  /**
+   * The entry's actual matched anchors (only populated when `QueryOpts.explain`
+   * is true AND `matchType === "anchor"`) — the anchor types requested by the
+   * query, as actually stored on this entry. See planning/index-provider/README.md
+   * "Score 与排序策略" §2026-03-08 for the original design intent this fulfills.
+   */
+  anchors?: AnchorData[];
+  /**
+   * Human-readable "why did this match" string, only populated when
+   * `QueryOpts.explain` is true — see `QueryOpts.explain` for the full
+   * contract. Log-friendly (issue #1069: "可以把它 log 出来，或者显示在某个地方").
+   */
+  explanation?: string;
+}
+interface QueryPageMeta {
+  cursor?: string;
+  hasMore?: boolean;
+  truncated?: boolean;
+}
+interface QueryPage {
+  results: QueryResult[];
+  meta?: QueryPageMeta;
+}
+interface AnchorResult {
+  entryPath: string;
+  score: number;
+}
+interface FTSResult {
+  entryPath: string;
+  rank: number;
+}
+interface VectorResult {
+  entryPath: string;
+  similarity: number;
+}
+interface CombinedResult {
+  entryPath: string;
+  anchorScore?: number;
+  ftsRank?: number;
+  score: number;
+}
+type KeyGenerator = (anchor: Anchor) => string[];
+interface AnchorTypeDefinition {
+  name: string;
+  schema?: Record<string, unknown>;
+  keyGenerator?: KeyGenerator | string;
+}
+interface IndexConfig {
+  indexable?: string[];
+  skip?: string[];
+}
+interface ExtractorHint {
+  path: string;
+  mode: "sync" | "async";
+}
+interface DomainDefinition {
+  name: string;
+  scope?: string;
+  types: AnchorTypeDefinition[];
+  config?: IndexConfig;
+  extractor?: ExtractorHint;
+}
+interface ExtractorRegistration {
+  id: string;
+  scope: string;
+  mode: "sync" | "async";
+  extractor?: string;
+}
+interface ExtractionResult {
+  anchors: Anchor[];
+  summary?: string;
+  embedding?: number[];
+}
+interface AFSIndexOptions {
+  /** Provider name (defaults to "index") */
+  name?: string;
+  /** Path to SQLite database file. ":memory:" for in-memory. */
+  dbPath?: string;
+  /** AFS path of the LLM provider (e.g., "/llm/") */
+  llmProvider?: string;
+  /**
+   * AFS path of the chat-completion action used by query rewriting
+   * strategies (e.g., "/dev/ai/.actions/chat"). Required
+   * when callers pass `rewriter: "multi-query"` to the query action;
+   * the index calls this path to generate query paraphrases. Falls
+   * back to `<llmProvider>/.actions/chat` if unset.
+   */
+  chatProvider?: string;
+  /** Whether to enable embedding fallback */
+  embeddingEnabled?: boolean;
+  /**
+   * Default relevance floor for pure-embedding matches (semantic mode), applied
+   * when a query doesn't pass `opts.embeddingFloor`. Set this per deployment
+   * where the embed model is known — the floor is model-specific (see
+   * `QueryOpts.embeddingFloor`). Undefined = no floor.
+   */
+  embeddingFloor?: number;
+  /**
+   * Explicit AFS root that `autoEmbed` execs the `llmProvider` embed/chat
+   * action against, overriding the mount `afsRoot`. Needed when the index is
+   * mounted inside an OVERLAY view (e.g. a per-caller `SessionUserAFS` session
+   * view) whose `exec` does NOT fall through to the system `/dev/ai` hubs — the
+   * mount afsRoot then can't reach the embedding provider. Point this at the
+   * underlying `base` (which does mount `/dev/ai`). When unset, `autoEmbed`
+   * uses the mount `afsRoot` (the Node global-mount case, unchanged). See CF
+   * `/user/index` vs `/instance/index`, issue #658.
+   */
+  embeddingAfsRoot?: AFSRoot;
+  /** Default domain for entries without explicit domain */
+  defaultDomain?: string;
+  /**
+   * Default query mode for `.actions/query` when the caller doesn't pass an
+   * explicit `mode`. Wired per deployment from the `AFS_INDEX_SEARCH_MODE` env
+   * var at each runtime's single env-read point (CF `resolveSpaceBindings`,
+   * Node daemon/system-mount boot) via `coerceSearchMode`. An explicit
+   * per-query `mode` always wins; `undefined` falls back to
+   * `DEFAULT_SEARCH_MODE` (`"combined"`), so an unconfigured deployment is
+   * byte-identical. Does NOT affect the generic `@Search` (`afs.search()`)
+   * route, which stays pinned to `"fts"`.
+   */
+  defaultSearchMode?: SearchMode;
+  /**
+   * Runtime hook to run the catch-up-on-query indexing OFF the response path.
+   * `execQuery` fires `follower.runCatchUp()` through this instead of awaiting
+   * it, so a search returns immediately from the current index and the
+   * caught-up rows surface on the NEXT query (issue #1168 — a blocking
+   * catch-up added latency and, on Cloudflare's free tier, put its subrequests
+   * on the same invocation as the query). On CF wire this to
+   * `ctx.waitUntil` (the promise must survive past the response); the passed
+   * function is called PER query and reads the current request's ctx. Unset
+   * (Node / standalone / tests, not subrequest-capped) → catch-up stays inline
+   * so this query sees the fresh rows.
+   */
+  scheduleBackground?: (task: Promise<unknown>) => void;
+  /**
+   * Query-time domain filter fallback, used when a caller's `.actions/query`
+   * doesn't pass an explicit `opts.scope` (the client never knows its own
+   * HMAC-derived storage scope, so it can't construct one). When set, an
+   * unscoped query is restricted to `domain IN (boundDomains)` — mirroring
+   * how the CF `D1IndexBackend` is already scope-bound per caller at
+   * construction time. Node's shared `user-index.db` (composite domain
+   * `{name}:{scope}`, see design.md §4.4) is the primary consumer: each
+   * per-caller `AFSIndex` handle is constructed with the caller's own
+   * composite domain names as `boundDomains`, so a query that omits
+   * `opts.scope` still can't scan another caller's rows in the same file.
+   *
+   * A caller that DOES pass an explicit `opts.scope` is never overridden —
+   * that value wins outright (see `QueryEngine`'s `domainsFilter`).
+   * `undefined`/empty (the default) is a strict no-op: the global
+   * `/modules/index` mount and every existing standalone-backend caller see
+   * byte-identical behavior. See issue #936 P4 isolation-leak repro:
+   * planning/index-provider/blocklet-index-e2e/logs/p4-isolation-leak-repro.md.
+   */
+  boundDomains?: string[];
+  /** Provider description */
+  description?: string;
+  /** Injected backend instance (overrides dbPath if provided) */
+  backend?: IndexBackend;
+  /**
+   * FTS5 tokenizer string. Default: `"unicode61 remove_diacritics 2"`
+   * (good for English/Latin; relies on `segmentCJK` write-time + query-time
+   * char-level segmentation for CJK content).
+   *
+   * Alternatives:
+   * - `"trigram"` — FTS5 built-in trigram tokenizer. Better for multi-char
+   *   CJK terms because every 3-char sliding window becomes a token, no
+   *   pre-segmentation needed. Trade-off: ~3× larger FTS index, slightly
+   *   slower writes. Recommended for Chinese/Japanese/Korean-heavy corpora.
+   *
+   * See planning/memory-system-improvements/design.md §P3 for the
+   * PerLTQA-zh data that motivated making this configurable.
+   */
+  ftsTokenizer?: string;
+  /**
+   * Subset of time key granularities to emit per time anchor.
+   * Defaults to all 8 (`year`, `month`, `day`, `quarter`, `week`, `season`,
+   * `weekday`, `daytime`). Pass a subset to reduce `idx_anchor_key` write
+   * amplification — for personal/Aside-scale deployments where only
+   * time-range queries are needed, `["year","month","day"]` is sufficient
+   * and cuts time-key rows by ~60 %. (Issue #1215)
+   */
+  timeKeyGranularity?: TimeKeyGranularity[];
+}
+//#endregion
+export { AFSIndexOptions, Anchor, AnchorData, AnchorQuery, AnchorResult, AnchorTypeDefinition, CombinedResult, DEFAULT_SEARCH_MODE, DomainDefinition, EntryFilter, EntryState, ExtractionResult, ExtractorHint, ExtractorRegistration, FTSResult, IndexConfig, IndexedEntry, KeyGenerator, LocationAnchor, MatchType, PersonAnchor, QueryOpts, QueryPage, QueryPageMeta, QueryResult, SEARCH_MODES, SearchMode, StaleFilter, TimeAnchor, TimeKeyGranularity, TopicAnchor, VectorResult, coerceSearchMode };
+//# sourceMappingURL=types.d.cts.map

package/dist/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","names":[],"sources":["../src/types.ts"],"mappings":"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"}