@gmickel/gno 1.46.0 → 2.0.0

package/src/store/sqlite/eligibility.ts

@@ -0,0 +1,174 @@
+import type { Database } from "bun:sqlite";
+
+import type { DocumentEligibilityOptions } from "../types";
+
+import { matchesExcludedText } from "../../pipeline/exclude";
+
+/** Unbounded owner selection; compose with FTS rowids or chunk mirror ownership
+ * before ranking/LIMIT. EXISTS keeps multiple tags/scopes from duplicating owners.
+ * Retains store filter semantics; lexical runtime language remains reserved. */
+export function buildEligibleDocumentQuery(
+  options: DocumentEligibilityOptions,
+  db?: Database
+): { sql: string; params: (string | number)[] } {
+  // Build tag filter conditions using EXISTS subqueries
+  const conditions: string[] = ["d.active = 1"];
+  const params: (string | number)[] = [];
+  if (options.chunkLanguage) {
+    conditions.push(
+      "EXISTS (SELECT 1 FROM content_chunks lc WHERE lc.mirror_hash = d.mirror_hash AND lc.language = ?)"
+    );
+    params.push(options.chunkLanguage);
+  }
+
+  // tagsAny: document has at least one of these tags
+  if (options.tagsAny && options.tagsAny.length > 0) {
+    const placeholders = options.tagsAny.map(() => "?").join(",");
+    conditions.push(
+      `EXISTS (SELECT 1 FROM doc_tags dt WHERE dt.document_id = d.id AND dt.tag IN (${placeholders}))`
+    );
+    params.push(...options.tagsAny);
+  }
+
+  // tagsAll: document has all of these tags
+  if (options.tagsAll && options.tagsAll.length > 0) {
+    for (const tag of options.tagsAll) {
+      conditions.push(
+        "EXISTS (SELECT 1 FROM doc_tags dt WHERE dt.document_id = d.id AND dt.tag = ?)"
+      );
+      params.push(tag);
+    }
+  }
+
+  if (options.since) {
+    conditions.push("d.source_mtime >= ?");
+    params.push(options.since);
+  }
+  if (options.until) {
+    conditions.push("d.source_mtime <= ?");
+    params.push(options.until);
+  }
+  if (
+    !options.semanticMetadata &&
+    options.categories &&
+    options.categories.length > 0
+  ) {
+    const placeholders = options.categories.map(() => "?").join(",");
+    conditions.push(
+      `(d.content_type IN (${placeholders}) OR EXISTS (SELECT 1 FROM json_each(COALESCE(d.categories, '[]')) jc WHERE jc.value IN (${placeholders})))`
+    );
+    params.push(...options.categories, ...options.categories);
+  }
+  if (!options.semanticMetadata && options.author) {
+    conditions.push("LOWER(COALESCE(d.author, '')) LIKE ?");
+    params.push(`%${options.author.toLowerCase()}%`);
+  }
+
+  if (options.allowedMirrorHashes !== undefined) {
+    conditions.push("d.mirror_hash IN (SELECT value FROM json_each(?))");
+    params.push(JSON.stringify(options.allowedMirrorHashes));
+  }
+  if (options.collection) {
+    conditions.push("d.collection = ?");
+    params.push(options.collection);
+  }
+  if (options.relPathPrefix !== undefined) {
+    conditions.push(
+      "(COALESCE(NULLIF(d.record_source_path, ''), d.rel_path) = ? OR substr(COALESCE(NULLIF(d.record_source_path, ''), d.rel_path), 1, length(?) + 1) = ? || '/')"
+    );
+    params.push(
+      options.relPathPrefix,
+      options.relPathPrefix,
+      options.relPathPrefix
+    );
+  }
+  if (options.memoryScopesAny?.length) {
+    const placeholders = options.memoryScopesAny.map(() => "?").join(",");
+    conditions.push(
+      `EXISTS (SELECT 1 FROM doc_memory_scopes ms WHERE ms.document_id = d.id AND ms.scope IN (${placeholders}))`
+    );
+    params.push(...options.memoryScopesAny);
+  }
+  if (options.excludeSuperseded) {
+    conditions.push(
+      "NOT EXISTS (SELECT 1 FROM doc_edges se JOIN documents sd ON sd.id = se.src_doc_id AND sd.active = 1 WHERE se.dst_doc_id = d.id AND se.edge_type = 'supersedes')"
+    );
+  }
+  if (
+    options.exclude?.length ||
+    (options.semanticMetadata && (options.author || options.categories?.length))
+  ) {
+    if (!db)
+      throw new Error("Exclusion eligibility requires document metadata");
+    // One bulk read, preserving JavaScript Unicode case folding and exclusions
+    // across every chunk, including chunks outside a later language selection.
+    const rows = db
+      .query<
+        {
+          id: number;
+          title: string | null;
+          path: string;
+          text: string | null;
+          author: string | null;
+          content_type: string | null;
+          categories: string | null;
+        },
+        (string | number)[]
+      >(`
+      SELECT d.id, d.title, d.author, d.content_type, d.categories, COALESCE(d.record_source_path, d.rel_path) AS path, cc.text
+      FROM documents d LEFT JOIN content_chunks cc ON cc.mirror_hash = d.mirror_hash
+      WHERE ${conditions.join(" AND ")}
+    `)
+      .iterate(...params);
+    const denied = new Set<number>();
+    for (const row of rows) {
+      const categories: unknown =
+        options.semanticMetadata || options.excludeMetadata
+          ? JSON.parse(row.categories ?? "[]")
+          : [];
+      if (
+        !Array.isArray(categories) ||
+        !categories.every((value): value is string => typeof value === "string")
+      ) {
+        denied.add(row.id);
+        continue;
+      }
+      if (options.semanticMetadata) {
+        const wanted = options.categories?.map((value) => value.toLowerCase());
+        if (
+          (options.author &&
+            !(row.author ?? "")
+              .toLowerCase()
+              .includes(options.author.toLowerCase())) ||
+          (wanted?.length &&
+            ![row.content_type ?? "", ...categories].some((value) =>
+              wanted.includes(value.toLowerCase())
+            ))
+        ) {
+          denied.add(row.id);
+          continue;
+        }
+      }
+      if (
+        matchesExcludedText(
+          [
+            row.title ?? "",
+            row.path,
+            row.text ?? "",
+            ...(options.excludeMetadata
+              ? [row.author ?? "", row.content_type ?? "", ...categories]
+              : []),
+          ],
+          options.exclude ?? []
+        )
+      )
+        denied.add(row.id);
+    }
+    conditions.push("d.id NOT IN (SELECT value FROM json_each(?))");
+    params.push(JSON.stringify([...denied]));
+  }
+  return {
+    sql: `SELECT d.id, d.mirror_hash FROM documents d WHERE ${conditions.join(" AND ")}`,
+    params,
+  };
+}

package/src/store/sqlite/graph-edge-application.ts

@@ -0,0 +1,66 @@
+import type { Database } from "bun:sqlite";
+
+import type { DocEdgeConfidence, DocEdgeSource } from "../types";
+
+export interface DesiredGraphEdge {
+  sourceId: number;
+  targetId: number;
+  edgeType: string;
+  confidence: DocEdgeConfidence;
+  source: DocEdgeSource;
+}
+
+/** Apply an exact scoped set without replacing retained edge identities/timestamps.
+ * Synchronous staging and application run in one transaction, including nested
+ * projection transactions. The temporary table is connection-local scratch only. */
+export function applyGraphEdges(
+  db: Database,
+  edges: DesiredGraphEdge[],
+  sources: DocEdgeSource[],
+  sourceIds?: number[]
+): number {
+  return db.transaction(() => {
+    db.exec(`CREATE TEMP TABLE IF NOT EXISTS graph_edge_application (
+      src_doc_id INTEGER NOT NULL, dst_doc_id INTEGER NOT NULL,
+      edge_type TEXT NOT NULL, confidence TEXT NOT NULL, source TEXT NOT NULL,
+      PRIMARY KEY(src_doc_id, dst_doc_id, edge_type, source)
+    )`);
+    db.run("DELETE FROM graph_edge_application");
+    const stage = db.query(`INSERT INTO graph_edge_application
+      (src_doc_id, dst_doc_id, edge_type, confidence, source) VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(src_doc_id, dst_doc_id, edge_type, source) DO UPDATE SET confidence=excluded.confidence`);
+    for (const edge of edges)
+      stage.run(
+        edge.sourceId,
+        edge.targetId,
+        edge.edgeType,
+        edge.confidence,
+        edge.source
+      );
+    const same =
+      "s.src_doc_id=e.src_doc_id AND s.dst_doc_id=e.dst_doc_id AND s.edge_type=e.edge_type AND s.source=e.source";
+    db.run(
+      `DELETE FROM doc_edges AS e
+      WHERE e.source IN (SELECT value FROM json_each(?))
+      ${sourceIds ? "AND e.src_doc_id IN (SELECT value FROM json_each(?))" : ""}
+      AND NOT EXISTS (SELECT 1 FROM graph_edge_application s WHERE ${same})`,
+      sourceIds
+        ? [JSON.stringify(sources), JSON.stringify(sourceIds)]
+        : [JSON.stringify(sources)]
+    );
+    db.run(`UPDATE doc_edges AS e SET confidence=(
+      SELECT s.confidence FROM graph_edge_application s WHERE ${same})
+      WHERE e.src_doc_id IN (SELECT src_doc_id FROM graph_edge_application)
+      AND EXISTS (SELECT 1 FROM graph_edge_application s WHERE ${same} AND s.confidence IS NOT e.confidence)`);
+    db.run(`INSERT INTO doc_edges(src_doc_id, dst_doc_id, edge_type, confidence, source)
+      SELECT s.src_doc_id, s.dst_doc_id, s.edge_type, s.confidence, s.source
+      FROM graph_edge_application s
+      WHERE NOT EXISTS (SELECT 1 FROM doc_edges e WHERE ${same})
+      ORDER BY s.rowid`);
+    // Bun run().changes includes trigger side effects; SQLite changes() does not.
+    return (
+      db.query<{ count: number }, []>("SELECT changes() AS count").get()
+        ?.count ?? 0
+    );
+  })();
+}

package/src/store/sqlite/graph-reference-state.ts

@@ -0,0 +1,194 @@
+import type { Database } from "bun:sqlite";
+
+import type {
+  GraphProjectionState,
+  GraphReferenceDocument,
+  GraphReferenceInventory,
+  GraphReferenceStore,
+} from "../types";
+
+import { buildWikiMatchExpression } from "../../core/graph-resolver";
+import { normalizeWikiName } from "../../core/links";
+
+const SNAPSHOT_COLUMNS = `document_id AS documentId, collection, rel_path AS relPath,
+  docid, uri, title, mirror_hash AS mirrorHash, source_hash AS sourceHash,
+  content_type AS contentType`;
+
+/** Raw references preserve resolver precedence; resolution belongs to ingestion.
+ * Keep old snapshots through deletion/rename until the affected closure is consumed.
+ * No second parsed-link inventory: use doc_links alongside these frontmatter rows. */
+export function createGraphReferenceStore(db: Database): GraphReferenceStore {
+  function state(
+    version: number,
+    configFingerprint: string
+  ): GraphProjectionState {
+    const row = db
+      .query<
+        {
+          epoch: number;
+          version: number | null;
+          configFingerprint: string | null;
+          dirty: number;
+          inProgress: number;
+        },
+        []
+      >(`SELECT epoch, version, config_fingerprint AS configFingerprint, dirty, in_progress AS inProgress
+      FROM graph_projection_state WHERE id = 1`)
+      .get();
+    if (!row)
+      throw new Error("Missing graph projection state; rebuild required");
+    return {
+      ...row,
+      dirty: row.dirty !== 0,
+      inProgress: row.inProgress !== 0,
+      complete:
+        row.dirty === 0 &&
+        row.inProgress === 0 &&
+        row.version === version &&
+        row.configFingerprint === configFingerprint,
+    };
+  }
+  return {
+    state,
+    begin(version, configFingerprint) {
+      if (!Number.isSafeInteger(version) || version < 1 || !configFingerprint)
+        throw new Error("Invalid graph projection identity");
+      return db.transaction(() => {
+        const previous = state(version, configFingerprint);
+        if (
+          previous.version !== version ||
+          previous.configFingerprint !== configFingerprint
+        )
+          db.run("DELETE FROM graph_reference_documents");
+        db.run(
+          `UPDATE graph_projection_state SET epoch = epoch + 1, dirty = 1, in_progress = 1, version = ?, config_fingerprint = ? WHERE id = 1`,
+          [version, configFingerprint]
+        );
+        return state(version, configFingerprint).epoch;
+      })();
+    },
+    readInventory() {
+      const docs = db
+        .query<GraphReferenceDocument, []>(
+          `SELECT ${SNAPSHOT_COLUMNS} FROM graph_reference_documents ORDER BY document_id`
+        )
+        .all();
+      const refs = db
+        .query<{ sourceId: number; edgeType: string; target: string }, []>(
+          `SELECT source_doc_id AS sourceId, edge_type AS edgeType, target FROM graph_frontmatter_references ORDER BY source_doc_id, ordinal`
+        )
+        .all();
+      const inventories = new Map<number, GraphReferenceInventory>(
+        docs.map((document) => [
+          document.documentId,
+          { document, references: [] },
+        ])
+      );
+      for (const ref of refs)
+        inventories
+          .get(ref.sourceId)
+          ?.references.push({ edgeType: ref.edgeType, target: ref.target });
+      return [...inventories.values()];
+    },
+    incomingLinkSources(identities) {
+      if (identities.length === 0) return [];
+      const targets = identities.map((d) => ({
+        collection: d.collection,
+        rel_path: d.relPath,
+        title: d.title,
+        wiki_title: normalizeWikiName(
+          d.title ?? d.relPath.split("/").pop() ?? d.relPath
+        ),
+        wiki_rel: normalizeWikiName(d.relPath),
+        wiki_stem: normalizeWikiName(d.relPath.replace(/\.[^/.]+$/, "")),
+      }));
+      return db
+        .query<{ sourceId: number }, [string]>(`
+        WITH targets AS (
+          SELECT json_extract(value, '$.collection') AS collection,
+            json_extract(value, '$.rel_path') AS rel_path,
+            json_extract(value, '$.title') AS title,
+            json_extract(value, '$.wiki_title') AS wiki_title,
+            json_extract(value, '$.wiki_rel') AS wiki_rel,
+            json_extract(value, '$.wiki_stem') AS wiki_stem
+          FROM json_each(?)
+        )
+        SELECT DISTINCT dl.source_doc_id AS sourceId
+        FROM doc_links dl JOIN documents src ON src.id = dl.source_doc_id AND src.active = 1
+        JOIN targets t ON (
+          (t.collection = COALESCE(dl.target_collection, src.collection) AND (
+            (dl.link_type = 'markdown' AND dl.target_ref_norm = t.rel_path) OR
+            (dl.link_type = 'wiki' AND ${buildWikiMatchExpression("t", "dl.target_ref_norm")})
+          )) OR
+          (dl.link_type = 'wiki' AND dl.target_ref_norm IN (t.wiki_title, t.wiki_rel, t.wiki_stem))
+          OR (dl.link_type = 'markdown' AND t.collection = src.collection AND dl.target_ref_norm = t.rel_path)
+        )
+        ORDER BY dl.source_doc_id
+      `)
+        .all(JSON.stringify(targets))
+        .map((row) => row.sourceId);
+    },
+    writeInventory({ document: d, references }) {
+      db.transaction(() => {
+        db.run("UPDATE graph_projection_state SET dirty = 1 WHERE id = 1");
+        db.run(
+          `INSERT INTO graph_reference_documents
+          (document_id, collection, rel_path, docid, uri, title, mirror_hash, source_hash, content_type)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+          ON CONFLICT(document_id) DO UPDATE SET collection=excluded.collection, rel_path=excluded.rel_path,
+          docid=excluded.docid, uri=excluded.uri, title=excluded.title, mirror_hash=excluded.mirror_hash,
+          source_hash=excluded.source_hash, content_type=excluded.content_type`,
+          [
+            d.documentId,
+            d.collection,
+            d.relPath,
+            d.docid,
+            d.uri,
+            d.title,
+            d.mirrorHash,
+            d.sourceHash,
+            d.contentType,
+          ]
+        );
+        db.run(
+          "DELETE FROM graph_frontmatter_references WHERE source_doc_id = ?",
+          [d.documentId]
+        );
+        for (const [ordinal, ref] of references.entries()) {
+          db.run(
+            "INSERT INTO graph_frontmatter_references(source_doc_id, ordinal, edge_type, target) VALUES (?, ?, ?, ?)",
+            [d.documentId, ordinal, ref.edgeType, ref.target]
+          );
+        }
+      })();
+    },
+    complete(expectedEpoch) {
+      db.transaction(() => {
+        const row = db
+          .query<{ epoch: number; version: number | null }, []>(
+            "SELECT epoch, version FROM graph_projection_state WHERE id = 1"
+          )
+          .get();
+        if (!row?.version || row.epoch !== expectedEpoch)
+          throw new Error("Graph inputs changed during projection");
+        const missing = db
+          .query<{ id: number }, []>(`SELECT d.id FROM documents d
+          LEFT JOIN graph_reference_documents r ON r.document_id = d.id
+          WHERE d.active = 1 AND (r.document_id IS NULL
+          OR r.collection IS NOT d.collection OR r.rel_path IS NOT d.rel_path
+          OR r.docid IS NOT d.docid OR r.uri IS NOT d.uri OR r.title IS NOT d.title
+          OR r.mirror_hash IS NOT d.mirror_hash OR r.source_hash IS NOT d.source_hash
+          OR r.content_type IS NOT d.content_type) LIMIT 1`)
+          .get();
+        if (missing)
+          throw new Error("Graph reference inventory is incomplete or stale");
+        db.run(
+          "DELETE FROM graph_reference_documents WHERE document_id NOT IN (SELECT id FROM documents WHERE active = 1)"
+        );
+        db.run(
+          "UPDATE graph_projection_state SET dirty = 0, in_progress = 0 WHERE id = 1"
+        );
+      })();
+    },
+  };
+}

package/src/store/sqlite/legacy-vector-ownership.ts

@@ -0,0 +1,79 @@
+/** Conservative input invalidation for providers without verified variants. */
+import type { Database } from "bun:sqlite";
+
+import { formatDocForEmbedding } from "../../pipeline/contextual";
+
+type TitleRow = { title: string | null };
+export type LegacyTitleSnapshot = Map<string, (string | null)[]>;
+
+function activeTitle(db: Database, mirror: string): TitleRow | null {
+  return db
+    .query<TitleRow, [string]>(`
+    SELECT title FROM documents WHERE mirror_hash = ? AND active = 1
+    ORDER BY id LIMIT 1
+  `)
+    .get(mirror);
+}
+
+/** Must be captured within the same transaction as the document mutation. */
+export function snapshotLegacyTitles(
+  db: Database,
+  mirrors: (string | null | undefined)[]
+): LegacyTitleSnapshot {
+  const snapshot: LegacyTitleSnapshot = new Map();
+  for (const mirror of new Set(mirrors)) {
+    if (!mirror) continue;
+    const active = activeTitle(db, mirror);
+    // All inactive titles must agree before a restored source can reuse an
+    // unproven legacy row. There is no persisted legacy input provenance.
+    const titles = active
+      ? [active.title]
+      : db
+          .query<TitleRow, [string]>(
+            "SELECT DISTINCT title FROM documents WHERE mirror_hash = ?"
+          )
+          .all(mirror)
+          .map((row) => row.title);
+    snapshot.set(mirror, titles);
+  }
+  return snapshot;
+}
+
+/** Only legacy vectors are invalidated; canonical chunks and variants survive. */
+export function reconcileLegacyTitles(
+  db: Database,
+  before: LegacyTitleSnapshot
+): void {
+  for (const [mirror, titles] of before) {
+    const next = activeTitle(db, mirror);
+    // Retain vectors when the final owner disappears, for identical restore.
+    if (!next || (titles.length === 1 && titles[0] === next.title)) continue;
+    const rows = db
+      .query<{ seq: number; model: string; text: string }, [string]>(`
+      SELECT v.seq, v.model, c.text FROM content_vectors v
+      JOIN content_chunks c ON c.mirror_hash = v.mirror_hash AND c.seq = v.seq
+      WHERE v.mirror_hash = ?
+    `)
+      .all(mirror);
+    for (const row of rows) {
+      const input = formatDocForEmbedding(
+        row.text,
+        next.title ?? undefined,
+        row.model
+      );
+      if (
+        titles.length &&
+        titles.every(
+          (title) =>
+            formatDocForEmbedding(row.text, title ?? undefined, row.model) ===
+            input
+        )
+      )
+        continue;
+      db.run(
+        "DELETE FROM content_vectors WHERE mirror_hash = ? AND seq = ? AND model = ?",
+        [mirror, row.seq, row.model]
+      );
+    }
+  }
+}

package/src/store/types.ts

@@ -615,22 +615,65 @@ export interface IngestErrorInput {
 // Search Types
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** Options for FTS search */
-export interface FtsSearchOptions {
-  /** Max results to return */
-  limit?: number;
+/** Existing SQL owner filters shared by lexical and chunk candidate selection. */
+export interface GraphReferenceDocument {
+  documentId: number;
+  collection: string;
+  relPath: string;
+  docid: string;
+  uri: string;
+  title: string | null;
+  mirrorHash: string | null;
+  sourceHash: string;
+  contentType: string | null;
+}
+
+export interface GraphFrontmatterReference {
+  edgeType: string;
+  target: string;
+}
+
+export interface GraphReferenceInventory {
+  document: GraphReferenceDocument;
+  references: GraphFrontmatterReference[];
+}
+
+export interface GraphProjectionState {
+  epoch: number;
+  version: number | null;
+  configFingerprint: string | null;
+  dirty: boolean;
+  /** Interrupted projection requires full recovery; ordinary input dirtiness does not. */
+  inProgress: boolean;
+  complete: boolean;
+}
+
+/** Synchronous internal operations compose with the adapter transaction. */
+export interface GraphReferenceStore {
+  state(version: number, configFingerprint: string): GraphProjectionState;
+  begin(version: number, configFingerprint: string): number;
+  readInventory(): GraphReferenceInventory[];
+  /** Active parsed-link sources matching any old/new target candidate. */
+  incomingLinkSources(identities: GraphReferenceDocument[]): number[];
+  writeInventory(inventory: GraphReferenceInventory): void;
+  complete(expectedEpoch: number): void;
+}
+
+export interface DocumentEligibilityOptions {
+  /** Internal owner eligibility; public lexical language remains reserved. */
+  chunkLanguage?: string;
+  /** Include author, content type and categories in whole-owner exclusion. */
+  excludeMetadata?: boolean;
+  /** Internal vector/hybrid JavaScript metadata matching semantics. */
+  semanticMetadata?: boolean;
+  /** Internal caller allowlist; undefined is unrestricted, empty denies all. */
+  allowedMirrorHashes?: string[];
+  /** Whole-document title/path/chunk exclusions, applied before the budget. */
+  exclude?: string[];
   /** Filter by collection */
   collection?: string;
   /** Internal exact relative-path boundary applied before ranking and LIMIT. */
   relPathPrefix?: string;
-  /**
-   * Language hint (reserved for future use).
-   * Note: FTS5 snowball tokenizer is language-aware at index time,
-   * so runtime language filtering is not currently implemented.
-   */
-  language?: string;
-  /** Include snippet with highlights */
-  snippet?: boolean;
   /** Filter to docs with ANY of these tags */
   tagsAny?: string[];
   /** Filter to docs with ALL of these tags */
@@ -654,6 +697,19 @@ export interface FtsSearchOptions {
    * `supersedes` pointing at them). Applied inside the candidate subquery.
    */
   excludeSuperseded?: boolean;
+}
+
+export interface FtsSearchOptions extends DocumentEligibilityOptions {
+  /** Max eligible ranked results to return (filters run before this budget) */
+  limit?: number;
+  /**
+   * Language hint (reserved for future use).
+   * Note: FTS5 snowball tokenizer is language-aware at index time,
+   * so runtime language filtering is not currently implemented.
+   */
+  language?: string;
+  /** Include snippet with highlights */
+  snippet?: boolean;
   /** Match documents containing ANY positive term instead of ALL of them. */
   anyTerm?: boolean;
 }
@@ -1998,6 +2054,15 @@ export interface StorePort {
     mirrorHashes: string[]
   ): Promise<StoreResult<Map<string, ChunkRow[]>>>;
 
+  /**
+   * Optional exact (mirrorHash, seq) batch hydration. Same mapping as
+   * getChunksBatch, but only requested sequences; missing pairs are omitted.
+   * Callers fall back to whole-hash batching when this capability is absent.
+   */
+  getChunksBySequenceBatch?(
+    keys: { mirrorHash: string; seq: number }[]
+  ): Promise<StoreResult<Map<string, ChunkRow[]>>>;
+
   // ─────────────────────────────────────────────────────────────────────────
   // FTS Search
   // ─────────────────────────────────────────────────────────────────────────
@@ -2112,6 +2177,9 @@ export interface StorePort {
    */
   getLinksForDoc(documentId: number): Promise<StoreResult<DocLinkRow[]>>;
 
+  /** Missing capability or stale state requires full graph reconciliation. */
+  graphReferenceStore?(): GraphReferenceStore;
+
   /**
    * Get backlinks pointing to a document.
    * Uses target_ref_norm for matching (wiki=normalized title with path fallbacks, markdown=rel_path).

package/src/store/vector/eligibility.ts

@@ -0,0 +1,36 @@
+import type { Database } from "bun:sqlite";
+
+import type { VectorSearchOptions } from "./types";
+
+import { buildEligibleDocumentQuery } from "../sqlite/eligibility";
+
+/** Correlated canonical chunk domain; owner predicates stay in the shared builder. */
+export function buildEligibleVectorQuery(
+  db: Database,
+  options: VectorSearchOptions
+): { sql: string; params: (string | number)[] } {
+  const eligibility = options.eligibility ?? {};
+  const owners = buildEligibleDocumentQuery(
+    { ...eligibility, semanticMetadata: true },
+    db
+  );
+  const conditions = [
+    "cc.mirror_hash = v.mirror_hash",
+    "cc.seq = v.seq",
+    `cc.mirror_hash IN (SELECT mirror_hash FROM (${owners.sql}))`,
+  ];
+  const params = [...owners.params];
+  if (eligibility.language) {
+    conditions.push("cc.language = ?");
+    params.push(eligibility.language);
+  }
+  // Caller scope intersects owner scope; an explicitly empty array denies all.
+  if (options.allowedMirrorHashes !== undefined) {
+    conditions.push("cc.mirror_hash IN (SELECT value FROM json_each(?))");
+    params.push(JSON.stringify(options.allowedMirrorHashes));
+  }
+  return {
+    sql: `SELECT 1 FROM content_chunks cc WHERE ${conditions.join(" AND ")}`,
+    params,
+  };
+}