@restormel/graphrag-core 0.1.0

package/dist/seed-set-constructor.d.ts

@@ -0,0 +1,53 @@
+import type { HybridCandidate } from "./hybrid-candidate-generation.js";
+import { type RetrievalOriginBalanceKey } from "./kg-balance.js";
+export type SeedRole = 'support' | 'objection' | 'reply' | 'definition_distinction';
+export interface SeedCandidate extends HybridCandidate {
+    claim_type: string;
+    embedding?: number[] | null;
+    /** Optional: used by inquiry-time KG balance (retrieval). */
+    domain?: string;
+    source_url?: string | null;
+    source_source_type?: string | null;
+}
+export interface SeedBalanceStats {
+    selection_strategy: 'mmr_quota_v1' | 'mmr_quota_kg_balance_v1';
+    mmr_lambda: number;
+    role_counts_pool: Record<SeedRole, number>;
+    role_counts_selected: Record<SeedRole, number>;
+    role_quotas: Record<SeedRole, number>;
+    quota_satisfied_roles: SeedRole[];
+    avg_pairwise_similarity_before: number;
+    avg_pairwise_similarity_after: number;
+    objection_reply_presence_before: boolean;
+    objection_reply_presence_after: boolean;
+    mono_perspective_before: boolean;
+    mono_perspective_after: boolean;
+    /** Present when retrieval applies ideal SEP/Gutenberg/domain balance (not DB snapshot metrics). */
+    kg_balance?: {
+        ideal_origin: Record<RetrievalOriginBalanceKey, number>;
+        selected_origin_counts: Record<RetrievalOriginBalanceKey, number>;
+        domains_in_pool: string[];
+        selected_domain_counts: Record<string, number>;
+    };
+}
+export interface SeedSetConstructionResult<T extends SeedCandidate> {
+    seeds: T[];
+    stats: SeedBalanceStats;
+}
+export declare function constructSeedSet<T extends SeedCandidate>(params: {
+    candidates: T[];
+    topK: number;
+    queryEmbedding?: number[];
+    mmrLambda?: number;
+    /**
+     * Optional inquiry-time balance: ideal origin mix + uniform domain targets among domains
+     * present in the candidate pool (see `knowledgeGraphRetrievalBalance.ts`).
+     */
+    kgBalance?: {
+        idealOrigin: Record<RetrievalOriginBalanceKey, number>;
+        domainsInPool: Set<string>;
+        getOrigin: (c: T) => RetrievalOriginBalanceKey;
+        getDomainKey: (c: T) => string;
+    };
+}): SeedSetConstructionResult<T>;
+//# sourceMappingURL=seed-set-constructor.d.ts.map

package/dist/seed-set-constructor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-set-constructor.d.ts","sourceRoot":"","sources":["../src/seed-set-constructor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,wBAAwB,CAAC;AAEpF,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC5B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,kBAAkB,EAAE,cAAc,GAAG,yBAAyB,CAAC;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC3C,oBAAoB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/C,WAAW,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACtC,qBAAqB,EAAE,QAAQ,EAAE,CAAC;IAClC,8BAA8B,EAAE,MAAM,CAAC;IACvC,6BAA6B,EAAE,MAAM,CAAC;IACtC,+BAA+B,EAAE,OAAO,CAAC;IACzC,8BAA8B,EAAE,OAAO,CAAC;IACxC,uBAAuB,EAAE,OAAO,CAAC;IACjC,sBAAsB,EAAE,OAAO,CAAC;IAChC,mGAAmG;IACnG,UAAU,CAAC,EAAE;QACX,YAAY,EAAE,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC;QACxD,sBAAsB,EAAE,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC;QAClE,eAAe,EAAE,MAAM,EAAE,CAAC;QAC1B,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChD,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC,SAAS,aAAa;IAChE,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAgJD,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,aAAa,EAAE,MAAM,EAAE;IAChE,UAAU,EAAE,CAAC,EAAE,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE;QACV,WAAW,EAAE,MAAM,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC;QACvD,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3B,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,yBAAyB,CAAC;QAC/C,YAAY,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;KAChC,CAAC;CACH,GAAG,yBAAyB,CAAC,CAAC,CAAC,CAwH/B"}

package/dist/seed-set-constructor.js

@@ -0,0 +1,247 @@
+import { computeKgBalanceMultiplier, } from "./kg-balance.js";
+const ROLE_ORDER = ['support', 'objection', 'reply', 'definition_distinction'];
+function normalizeText(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, ' ')
+        .split(/\s+/)
+        .filter(Boolean);
+}
+function cosineSimilarity(a, b) {
+    if (!a || !b || a.length === 0 || b.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let aNorm = 0;
+    let bNorm = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        aNorm += a[i] * a[i];
+        bNorm += b[i] * b[i];
+    }
+    if (aNorm === 0 || bNorm === 0)
+        return 0;
+    return dot / (Math.sqrt(aNorm) * Math.sqrt(bNorm));
+}
+function tokenOverlapSimilarity(aText, bText) {
+    const aSet = new Set(normalizeText(aText));
+    const bSet = new Set(normalizeText(bText));
+    if (aSet.size === 0 || bSet.size === 0)
+        return 0;
+    let overlap = 0;
+    for (const token of aSet) {
+        if (bSet.has(token))
+            overlap += 1;
+    }
+    return overlap / Math.max(aSet.size, bSet.size);
+}
+function pairwiseSimilarity(a, b) {
+    const vectorSim = cosineSimilarity(a.embedding, b.embedding);
+    if (vectorSim > 0)
+        return vectorSim;
+    return tokenOverlapSimilarity(a.text, b.text);
+}
+function roleForCandidate(candidate) {
+    const claimType = candidate.claim_type.toLowerCase();
+    if (claimType === 'objection')
+        return 'objection';
+    if (claimType === 'response' || claimType === 'reply')
+        return 'reply';
+    if (claimType === 'definition' || normalizeText(candidate.text).includes('distinction')) {
+        return 'definition_distinction';
+    }
+    return 'support';
+}
+function makeEmptyRoleCounts() {
+    return {
+        support: 0,
+        objection: 0,
+        reply: 0,
+        definition_distinction: 0
+    };
+}
+function makeEmptyOriginCounts() {
+    return { sep: 0, gutenberg: 0, other: 0 };
+}
+function averagePairwiseSimilarity(candidates) {
+    if (candidates.length < 2)
+        return 0;
+    let sum = 0;
+    let pairs = 0;
+    for (let i = 0; i < candidates.length; i++) {
+        for (let j = i + 1; j < candidates.length; j++) {
+            sum += pairwiseSimilarity(candidates[i], candidates[j]);
+            pairs += 1;
+        }
+    }
+    return pairs === 0 ? 0 : sum / pairs;
+}
+function hasObjectionReplyPresence(roleCounts) {
+    return roleCounts.objection > 0 && roleCounts.reply > 0;
+}
+function isMonoPerspective(roleCounts, total) {
+    if (total === 0)
+        return true;
+    return roleCounts.support >= total || Math.max(...ROLE_ORDER.map((role) => roleCounts[role])) >= total * 0.85;
+}
+function computeDefaultQuotas(topK) {
+    const quotas = makeEmptyRoleCounts();
+    if (topK >= 4) {
+        quotas.support = 1;
+        quotas.objection = 1;
+        quotas.reply = 1;
+        quotas.definition_distinction = 1;
+        quotas.support += topK - 4;
+    }
+    else if (topK === 3) {
+        quotas.support = 1;
+        quotas.objection = 1;
+        quotas.reply = 1;
+    }
+    else if (topK === 2) {
+        quotas.support = 1;
+        quotas.objection = 1;
+    }
+    else {
+        quotas.support = 1;
+    }
+    return quotas;
+}
+function adaptQuotasToPool(quotas, poolCounts, topK) {
+    const adapted = { ...quotas };
+    let used = 0;
+    for (const role of ROLE_ORDER) {
+        adapted[role] = Math.min(adapted[role], poolCounts[role]);
+        used += adapted[role];
+    }
+    if (used >= topK)
+        return adapted;
+    const topUpOrder = ['support', 'objection', 'reply', 'definition_distinction'];
+    while (used < topK) {
+        let topped = false;
+        for (const role of topUpOrder) {
+            if (adapted[role] < poolCounts[role]) {
+                adapted[role] += 1;
+                used += 1;
+                topped = true;
+                if (used >= topK)
+                    break;
+            }
+        }
+        if (!topped)
+            break;
+    }
+    return adapted;
+}
+function relevanceToQuery(candidate, queryEmbedding) {
+    const vectorSim = cosineSimilarity(candidate.embedding, queryEmbedding ?? null);
+    if (vectorSim > 0)
+        return vectorSim;
+    return Math.max(0, candidate.confidence);
+}
+export function constructSeedSet(params) {
+    const { candidates, topK, queryEmbedding, mmrLambda = 0.72, kgBalance } = params;
+    const cappedCandidates = candidates.slice(0, Math.max(topK * 4, topK));
+    const targetSize = Math.min(topK, cappedCandidates.length);
+    const roleCountsPool = makeEmptyRoleCounts();
+    const candidateRole = new Map();
+    for (const candidate of cappedCandidates) {
+        const role = roleForCandidate(candidate);
+        candidateRole.set(candidate.id, role);
+        roleCountsPool[role] += 1;
+    }
+    const defaultQuotas = computeDefaultQuotas(targetSize);
+    const adaptedQuotas = adaptQuotasToPool(defaultQuotas, roleCountsPool, targetSize);
+    const selected = [];
+    const selectedIds = new Set();
+    const roleCountsSelected = makeEmptyRoleCounts();
+    const selectedOriginCounts = makeEmptyOriginCounts();
+    const selectedDomainCounts = new Map();
+    const relevanceById = new Map();
+    for (const candidate of cappedCandidates) {
+        relevanceById.set(candidate.id, relevanceToQuery(candidate, queryEmbedding));
+    }
+    while (selected.length < targetSize) {
+        const remaining = cappedCandidates.filter((candidate) => !selectedIds.has(candidate.id));
+        if (remaining.length === 0)
+            break;
+        const unmetRoles = ROLE_ORDER.filter((role) => roleCountsSelected[role] < adaptedQuotas[role]);
+        const roleRestricted = unmetRoles.length > 0
+            ? remaining.filter((candidate) => unmetRoles.includes(candidateRole.get(candidate.id) ?? 'support'))
+            : remaining;
+        const pool = roleRestricted.length > 0 ? roleRestricted : remaining;
+        let best = null;
+        let bestScore = Number.NEGATIVE_INFINITY;
+        const totalSel = selected.length;
+        for (const candidate of pool) {
+            const relevance = relevanceById.get(candidate.id) ?? 0;
+            let maxSimilarity = 0;
+            for (const chosen of selected) {
+                maxSimilarity = Math.max(maxSimilarity, pairwiseSimilarity(candidate, chosen));
+            }
+            let balanceMult = 1;
+            if (kgBalance && totalSel > 0) {
+                balanceMult = computeKgBalanceMultiplier({
+                    origin: kgBalance.getOrigin(candidate),
+                    domain: kgBalance.getDomainKey(candidate),
+                    selectedOriginCounts,
+                    selectedDomainCounts,
+                    totalSelected: totalSel,
+                    idealOrigin: kgBalance.idealOrigin,
+                    domainsInPool: kgBalance.domainsInPool
+                });
+            }
+            else if (kgBalance && totalSel === 0) {
+                balanceMult = 1;
+            }
+            const score = mmrLambda * relevance * balanceMult - (1 - mmrLambda) * maxSimilarity;
+            if (score > bestScore) {
+                best = candidate;
+                bestScore = score;
+            }
+        }
+        if (!best)
+            break;
+        selected.push(best);
+        selectedIds.add(best.id);
+        const role = candidateRole.get(best.id) ?? 'support';
+        roleCountsSelected[role] += 1;
+        if (kgBalance) {
+            const o = kgBalance.getOrigin(best);
+            selectedOriginCounts[o] += 1;
+            const dk = kgBalance.getDomainKey(best);
+            selectedDomainCounts.set(dk, (selectedDomainCounts.get(dk) ?? 0) + 1);
+        }
+    }
+    const baseline = cappedCandidates.slice(0, targetSize);
+    const baselineRoleCounts = makeEmptyRoleCounts();
+    for (const candidate of baseline) {
+        baselineRoleCounts[candidateRole.get(candidate.id) ?? 'support'] += 1;
+    }
+    const quotaSatisfiedRoles = ROLE_ORDER.filter((role) => roleCountsSelected[role] >= adaptedQuotas[role]);
+    const kgStats = kgBalance && selected.length > 0
+        ? {
+            ideal_origin: { ...kgBalance.idealOrigin },
+            selected_origin_counts: { ...selectedOriginCounts },
+            domains_in_pool: [...kgBalance.domainsInPool].sort(),
+            selected_domain_counts: Object.fromEntries([...selectedDomainCounts.entries()].sort((a, b) => a[0].localeCompare(b[0])))
+        }
+        : undefined;
+    return {
+        seeds: selected,
+        stats: {
+            selection_strategy: kgBalance ? 'mmr_quota_kg_balance_v1' : 'mmr_quota_v1',
+            mmr_lambda: mmrLambda,
+            role_counts_pool: roleCountsPool,
+            role_counts_selected: roleCountsSelected,
+            role_quotas: adaptedQuotas,
+            quota_satisfied_roles: quotaSatisfiedRoles,
+            avg_pairwise_similarity_before: averagePairwiseSimilarity(baseline),
+            avg_pairwise_similarity_after: averagePairwiseSimilarity(selected),
+            objection_reply_presence_before: hasObjectionReplyPresence(baselineRoleCounts),
+            objection_reply_presence_after: hasObjectionReplyPresence(roleCountsSelected),
+            mono_perspective_before: isMonoPerspective(baselineRoleCounts, baseline.length),
+            mono_perspective_after: isMonoPerspective(roleCountsSelected, selected.length),
+            ...(kgStats ? { kg_balance: kgStats } : {})
+        }
+    };
+}

package/dist/surreal-retrieval-enhancements.d.ts

@@ -0,0 +1,39 @@
+import type { GraphStore } from "./ports.js";
+export declare function isRetrievalBm25Enabled(): boolean;
+export declare function isRetrievalNativeGraphEnabled(): boolean;
+export declare function fetchBm25ClaimCandidates(store: GraphStore, params: {
+    terms: string[];
+    limit: number;
+    reviewFilter: string;
+}): Promise<Array<{
+    id: string;
+    text: string;
+    confidence: number;
+}>>;
+export declare function fetchNativeGraphNeighbors(store: GraphStore, params: {
+    seedIds: string[];
+    limit: number;
+}): Promise<string[]>;
+export declare function ensureClaimSearchIndex(db: {
+    query: (sql: string) => Promise<unknown>;
+}): Promise<void>;
+export declare function isRetrievalPassageGroundedEnabled(): boolean;
+export declare function isRetrievalTaxonomyRoutingEnabled(): boolean;
+export declare function isKgEnforcePassageOnAcceptEnabled(): boolean;
+export declare function fetchPassageGroundedClaimIds(store: GraphStore, params: {
+    queryEmbedding: number[];
+    limit: number;
+    reviewFilter: string;
+}): Promise<string[]>;
+export declare function fetchTaxonomySeedClaimIds(store: GraphStore, params: {
+    terms: string[];
+    limit: number;
+    reviewFilter: string;
+}): Promise<string[]>;
+export declare function ensurePassageEmbeddingIndex(db: {
+    query: (sql: string) => Promise<unknown>;
+}): Promise<void>;
+export declare function ensureClaimAcceptPassageEvent(db: {
+    query: (sql: string) => Promise<unknown>;
+}): Promise<void>;
+//# sourceMappingURL=surreal-retrieval-enhancements.d.ts.map

package/dist/surreal-retrieval-enhancements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surreal-retrieval-enhancements.d.ts","sourceRoot":"","sources":["../src/surreal-retrieval-enhancements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD;AAED,wBAAgB,6BAA6B,IAAI,OAAO,CAGvD;AAED,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE;IACN,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB,GACA,OAAO,CAAC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAelE;AAED,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE;IACN,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf,GACA,OAAO,CAAC,MAAM,EAAE,CAAC,CA2BnB;AAED,wBAAsB,sBAAsB,CAAC,EAAE,EAAE;IAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAM5G;AAED,wBAAgB,iCAAiC,IAAI,OAAO,CAG3D;AAED,wBAAgB,iCAAiC,IAAI,OAAO,CAG3D;AAED,wBAAgB,iCAAiC,IAAI,OAAO,CAG3D;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE;IACN,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB,GACA,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBnB;AAED,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE;IACN,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB,GACA,OAAO,CAAC,MAAM,EAAE,CAAC,CAwBnB;AAED,wBAAsB,2BAA2B,CAAC,EAAE,EAAE;IAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAKjH;AAED,wBAAsB,6BAA6B,CAAC,EAAE,EAAE;IAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAWnH"}

package/dist/surreal-retrieval-enhancements.js

@@ -0,0 +1,139 @@
+export function isRetrievalBm25Enabled() {
+    const v = (process.env.RETRIEVAL_USE_BM25 ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+export function isRetrievalNativeGraphEnabled() {
+    const v = (process.env.RETRIEVAL_NATIVE_GRAPH ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+export async function fetchBm25ClaimCandidates(store, params) {
+    if (params.terms.length === 0)
+        return [];
+    const searchQuery = params.terms.slice(0, 8).join(" ");
+    try {
+        const rows = await store.query(`SELECT id, text, confidence FROM claim
+			 WHERE text @@ $q AND ${params.reviewFilter}
+			 ORDER BY confidence DESC
+			 LIMIT $limit`, { q: searchQuery, limit: params.limit });
+        return rows ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function fetchNativeGraphNeighbors(store, params) {
+    if (!isRetrievalNativeGraphEnabled() || params.seedIds.length === 0)
+        return [];
+    try {
+        const rows = await store.query(`SELECT array::distinct(
+				array::flatten([
+					->depends_on->claim,
+					->supports->claim,
+					<-contradicts<-claim,
+					->responds_to->claim
+				])
+			) AS neighbors
+			FROM claim
+			WHERE id INSIDE $seed_ids
+			LIMIT $limit`, { seed_ids: params.seedIds, limit: params.limit });
+        const out = new Set();
+        for (const row of rows ?? []) {
+            for (const n of row.neighbors ?? []) {
+                if (typeof n?.id === "string")
+                    out.add(n.id);
+            }
+        }
+        return [...out];
+    }
+    catch {
+        return [];
+    }
+}
+export async function ensureClaimSearchIndex(db) {
+    if (!isRetrievalBm25Enabled())
+        return;
+    await db.query(`
+		DEFINE ANALYZER IF NOT EXISTS claim_english TOKENIZERS blank,class FILTERS lowercase,ascii;
+		DEFINE INDEX IF NOT EXISTS claim_search ON claim FIELDS text SEARCH ANALYZER claim_english BM25;
+	`);
+}
+export function isRetrievalPassageGroundedEnabled() {
+    const v = (process.env.RETRIEVAL_PASSAGE_GROUNDED ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+export function isRetrievalTaxonomyRoutingEnabled() {
+    const v = (process.env.RETRIEVAL_TAXONOMY_ROUTING ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+export function isKgEnforcePassageOnAcceptEnabled() {
+    const v = (process.env.KG_ENFORCE_PASSAGE_ON_ACCEPT ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+export async function fetchPassageGroundedClaimIds(store, params) {
+    if (!isRetrievalPassageGroundedEnabled())
+        return [];
+    try {
+        const rows = await store.query(`SELECT array::distinct(array::flatten(<-grounded_in<-claim.id)) AS claim_ids
+			 FROM (
+				SELECT id FROM passage
+				WHERE embedding <|$limit,64|> $query_embedding
+				LIMIT $limit
+			 )
+			 WHERE claim_ids != NONE`, { query_embedding: params.queryEmbedding, limit: params.limit });
+        const out = new Set();
+        for (const row of rows ?? []) {
+            for (const id of row.claim_ids ?? []) {
+                if (typeof id === "string")
+                    out.add(id);
+            }
+        }
+        return [...out].slice(0, params.limit);
+    }
+    catch {
+        return [];
+    }
+}
+export async function fetchTaxonomySeedClaimIds(store, params) {
+    if (!isRetrievalTaxonomyRoutingEnabled() || params.terms.length === 0)
+        return [];
+    const needles = params.terms.slice(0, 6).map((t) => t.toLowerCase());
+    try {
+        const rows = await store.query(`SELECT id FROM claim
+			 WHERE ${params.reviewFilter}
+			 AND (
+				id IN (
+					SELECT VALUE in FROM about_subject
+					WHERE out.name ~ $needle OR out.slug ~ $needle
+				)
+				OR id IN (
+					SELECT VALUE in FROM authored
+					WHERE out.name ~ $needle OR out.canonical_name ~ $needle
+				)
+			 )
+			 LIMIT $limit`, { needle: needles[0], limit: params.limit });
+        return (rows ?? []).map((r) => String(r.id)).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+export async function ensurePassageEmbeddingIndex(db) {
+    if (!isRetrievalPassageGroundedEnabled())
+        return;
+    await db.query(`
+		DEFINE INDEX IF NOT EXISTS passage_embedding ON passage FIELDS embedding HNSW DIMENSION 768 DIST COSINE;
+	`);
+}
+export async function ensureClaimAcceptPassageEvent(db) {
+    if (!isKgEnforcePassageOnAcceptEnabled())
+        return;
+    await db.query(`
+		DEFINE EVENT IF NOT EXISTS claim_accept_requires_passage ON claim
+		WHEN $event = 'CREATE' OR $event = 'UPDATE'
+		THEN {
+			IF $after.review_state = 'accepted' AND count(<-grounded_in<-passage WHERE in = $after.id) = 0 {
+				THROW 'accepted claims must link to at least one passage';
+			};
+		};
+	`);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@restormel/graphrag-core",
+  "version": "0.1.0",
+  "description": "Knowledge Retrieve pipeline — graph-aware RAG with injected GraphStore and embedding ports (no Surreal driver in package).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Allotment-Technology-Ltd/restormel-keys.git",
+    "directory": "packages/graphrag-core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@restormel/contracts": "0.1.1",
+    "@restormel/graph-core": "0.1.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "typecheck": "tsc -b tsconfig.json",
+    "test": "vitest run"
+  }
+}