sneakoscope 7.3.0 → 7.6.0

package/dist/core/triwiki/context-graph/query/index.js

@@ -0,0 +1,178 @@
+import { CONTEXT_GRAPH_QUERY_SCHEMA, emptyContextGraphQueryResult } from '../query-types.js';
+import { CONTEXT_GRAPH_TRAVERSAL_CAPS, contextGraphQueryProfile } from '../profiles.js';
+import { isWorkspaceRelativePosixPath } from '../paths.js';
+import { explainContextGraphCandidates, toContextGraphSelectedNode, contextGraphProvenanceCoverage } from './explain.js';
+import { loadContextGraphIndex } from './load.js';
+import { packContextGraphSelection } from './pack.js';
+import { isHighRiskScope, rankContextGraphCandidates } from './rank.js';
+import { CONTEXT_GRAPH_RANKING_CONFIG } from './ranking-config.js';
+import { resolveContextGraphSeeds } from './seeds.js';
+import { traverseContextGraph } from './traverse.js';
+function add(into, reason, count) {
+    if (count <= 0)
+        return;
+    into[reason] = (into[reason] ?? 0) + count;
+}
+function usableFocusPaths(request) {
+    const out = [];
+    for (const focus of request.focusPaths ?? []) {
+        const normalized = String(focus ?? '').replace(/^\.\//, '').replace(/\/+$/, '');
+        if (normalized && isWorkspaceRelativePosixPath(normalized) && !out.includes(normalized))
+            out.push(normalized);
+    }
+    return out;
+}
+export function queryContextGraphSnapshot(index, request, options = {}) {
+    const clock = options.clock ?? Date.now;
+    const startedAt = clock();
+    const config = options.config ?? CONTEXT_GRAPH_RANKING_CONFIG;
+    const profile = contextGraphQueryProfile(request.profile);
+    const caps = CONTEXT_GRAPH_TRAVERSAL_CAPS;
+    const tokenBudget = Math.max(0, request.tokenBudget ?? caps.defaultTokenBudget);
+    const maxSelected = Math.max(0, Math.min(request.maxSelected ?? caps.maxSelectedNodes, caps.maxSelectedNodes));
+    const timeoutMs = Math.max(0, request.timeoutMs ?? caps.queryTimeoutMs);
+    const deadline = timeoutMs > 0 ? startedAt + timeoutMs : null;
+    const warnings = [...(options.warnings ?? [])];
+    const resolution = resolveContextGraphSeeds({ index, request, config, maxSeeds: caps.maxSeeds });
+    if (resolution.unknownProvidedSeeds > 0) {
+        warnings.push(`${resolution.unknownProvidedSeeds} caller-supplied seed(s) are not present in this snapshot`);
+    }
+    if (resolution.scanBudgetExhausted) {
+        warnings.push('lexical seeding stopped at its scan budget; results may be incomplete');
+    }
+    if (resolution.seeds.length === 0) {
+        warnings.push('no graph node matched this query; nothing was selected and no text fallback was attempted');
+    }
+    const focusPaths = usableFocusPaths(request);
+    const highRisk = isHighRiskScope(index, resolution.seeds, request);
+    const maxDepth = highRisk ? profile.maxDepthHighRisk : profile.maxDepth;
+    const traversal = traverseContextGraph({
+        index,
+        seeds: resolution.seeds,
+        profile,
+        maxDepth,
+        maxVisitedNodes: caps.maxVisitedNodes,
+        maxVisitedEdges: caps.maxVisitedEdges,
+        config,
+        focusPaths,
+        deadline
+    });
+    const seedsByNode = new Map(resolution.seeds.map((seed) => [seed.nodeId, seed]));
+    const ranked = rankContextGraphCandidates({
+        index,
+        states: traversal.states,
+        seedsByNode,
+        request,
+        config,
+        focusActive: focusPaths.length > 0
+    });
+    if (ranked.focusExcluded > 0) {
+        warnings.push(`${ranked.focusExcluded} reachable node(s) were outside the requested focus paths`);
+    }
+    const explainResult = explainContextGraphCandidates({
+        index,
+        states: traversal.states,
+        candidates: ranked.candidates,
+        config
+    });
+    const packed = packContextGraphSelection({
+        explained: explainResult.explained,
+        tokenBudget,
+        maxSelected,
+        profile: profile.name,
+        highRisk,
+        config
+    });
+    warnings.push(...packed.warnings);
+    const omissionReasons = { ...packed.omissions };
+    add(omissionReasons, 'stale_node', ranked.staleExcluded);
+    add(omissionReasons, 'invalidated_proof', ranked.invalidatedExcluded);
+    add(omissionReasons, 'redundant_sibling', ranked.redundantExcluded);
+    add(omissionReasons, 'no_provenance', explainResult.ungrounded);
+    add(omissionReasons, 'depth_limit', traversal.depthLimited);
+    add(omissionReasons, 'visit_cap', (traversal.nodeCapHit ? 1 : 0) + resolution.droppedSeeds);
+    add(omissionReasons, 'edge_cap', traversal.edgeCapHit ? 1 : 0);
+    add(omissionReasons, 'timeout', traversal.timedOut ? 1 : 0);
+    const selected = packed.selected.map(toContextGraphSelectedNode);
+    const truncated = packed.truncated || traversal.nodeCapHit || traversal.edgeCapHit || traversal.timedOut || resolution.droppedSeeds > 0;
+    return {
+        schema: CONTEXT_GRAPH_QUERY_SCHEMA,
+        ok: true,
+        snapshotHash: index.snapshot.snapshotHash,
+        snapshotFreshness: options.snapshotFreshness ?? 'fresh',
+        profile: profile.name,
+        seeds: resolution.seeds,
+        seedCount: resolution.seeds.length,
+        visitedNodes: traversal.visitedNodes,
+        visitedEdges: traversal.visitedEdges,
+        selected,
+        selectedNodes: selected.length,
+        explanationPathCount: selected.filter((node) => node.explanation.length > 0).length,
+        provenanceCoverage: contextGraphProvenanceCoverage(selected),
+        staleExcluded: ranked.staleExcluded,
+        invalidatedExcluded: ranked.invalidatedExcluded,
+        tokenCost: packed.tokenCost,
+        tokenBudget,
+        truncated,
+        timeout: traversal.timedOut,
+        omissionReasons,
+        warnings,
+        errors: [],
+        durationMs: Math.max(0, clock() - startedAt),
+        processSpawns: 0
+    };
+}
+function failedResult(profile, snapshotHash, errors, warnings, tokenBudget, durationMs) {
+    const base = emptyContextGraphQueryResult(snapshotHash, profile, [...errors]);
+    return { ...base, warnings: [...warnings], tokenBudget, durationMs };
+}
+export async function queryContextGraph(request, options = {}) {
+    const clock = options.clock ?? Date.now;
+    const startedAt = clock();
+    const profileName = contextGraphQueryProfile(request.profile).name;
+    const tokenBudget = Math.max(0, request.tokenBudget ?? CONTEXT_GRAPH_TRAVERSAL_CAPS.defaultTokenBudget);
+    if (options.index) {
+        return queryContextGraphSnapshot(options.index, request, options);
+    }
+    const load = await loadContextGraphIndex(request.root, options);
+    if (!load.ok || !load.index) {
+        return failedResult(profileName, load.snapshotHash, load.errors, load.warnings, tokenBudget, Math.max(0, clock() - startedAt));
+    }
+    const snapshotOptions = {
+        ...(options.config === undefined ? {} : { config: options.config }),
+        ...(options.clock === undefined ? {} : { clock: options.clock }),
+        snapshotFreshness: load.freshness,
+        warnings: [...load.warnings, ...(options.warnings ?? [])]
+    };
+    return queryContextGraphSnapshot(load.index, request, snapshotOptions);
+}
+export function contextGraphSearchMeta(result) {
+    const omissionReasons = {};
+    for (const [reason, count] of Object.entries(result.omissionReasons)) {
+        if (typeof count === 'number' && count > 0)
+            omissionReasons[reason] = count;
+    }
+    return {
+        snapshotHash: result.snapshotHash,
+        snapshotFreshness: result.snapshotFreshness,
+        profile: result.profile,
+        seedCount: result.seedCount,
+        visitedNodes: result.visitedNodes,
+        selectedNodes: result.selectedNodes,
+        explanationPathCount: result.explanationPathCount,
+        provenanceCoverage: result.provenanceCoverage,
+        staleExcluded: result.staleExcluded,
+        invalidatedExcluded: result.invalidatedExcluded,
+        tokenCost: result.tokenCost,
+        tokenBudget: result.tokenBudget,
+        omissionReasons
+    };
+}
+export { CONTEXT_GRAPH_RANKING_CONFIG, CONTEXT_GRAPH_RANKING_SCHEMA, CONTEXT_GRAPH_EXACT_SEED_CONFIDENCES, isExactContextGraphSeedConfidence } from './ranking-config.js';
+export { normalizeContextGraphQuery, resolveContextGraphSeeds, seedConfidenceFor } from './seeds.js';
+export { traverseContextGraph, contextGraphNodePath, isUnderFocusPath } from './traverse.js';
+export { rankContextGraphCandidates, contextGraphGroupKey, isInvalidatedContextGraphNode, isHighRiskScope } from './rank.js';
+export { explainContextGraphCandidates, groundContextGraphNode, toContextGraphSelectedNode, contextGraphProvenanceCoverage } from './explain.js';
+export { packContextGraphSelection } from './pack.js';
+export { loadContextGraphIndex, contextGraphRepairHint } from './load.js';
+export { CONTEXT_GRAPH_SNAPSHOT_CACHE_MAX_ENTRIES, cacheContextGraphIndex, clearContextGraphSnapshotCache, contextGraphSnapshotCacheStats, contextGraphWorkspaceKey, getCachedContextGraphIndex } from './snapshot-cache.js';

package/dist/core/triwiki/context-graph/query/load.js

@@ -0,0 +1,116 @@
+import { CONTEXT_GRAPH_CORRUPT_ERROR, CONTEXT_GRAPH_MISSING_ERROR, CONTEXT_GRAPH_REPAIR_COMMAND, CONTEXT_GRAPH_SCHEMA_REVISION, CONTEXT_GRAPH_STALE_ERROR } from '../contracts.js';
+import { readSourceHashes } from '../compiler/freshness.js';
+import { buildContextGraphIndex } from '../graph-index.js';
+import { readContextGraphMeta, readContextGraphSnapshot } from '../store/snapshot-store.js';
+import { cacheContextGraphIndex, getCachedContextGraphIndex } from './snapshot-cache.js';
+const DEFAULT_MAX_VERIFIED_SOURCES = 4000;
+export function contextGraphRepairHint() {
+    return `Run \`${CONTEXT_GRAPH_REPAIR_COMMAND}\` to rebuild the context graph.`;
+}
+function failure(code, detail, snapshotHash = '') {
+    return {
+        ok: false,
+        index: null,
+        snapshotHash,
+        errorCode: code,
+        errors: [code, detail, contextGraphRepairHint()],
+        warnings: [],
+        cacheHit: false,
+        freshness: 'stale'
+    };
+}
+function statusFailure(status) {
+    if (status.status === 'fresh')
+        return null;
+    const code = status.status === 'missing'
+        ? CONTEXT_GRAPH_MISSING_ERROR
+        : status.status === 'corrupt'
+            ? CONTEXT_GRAPH_CORRUPT_ERROR
+            : CONTEXT_GRAPH_STALE_ERROR;
+    const declared = status.reasons ?? [];
+    const reasons = declared.length > 0 ? ` (${declared.join(', ')})` : '';
+    return failure(code, `the stored context graph is ${status.status}${reasons}`, status.snapshotHash ?? '');
+}
+async function sourcesChanged(root, inputHashes, limit) {
+    const recorded = Object.keys(inputHashes).sort().slice(0, Math.max(0, limit));
+    if (recorded.length === 0)
+        return false;
+    const observed = await readSourceHashes(root, recorded);
+    for (const file of recorded) {
+        if (observed[file] !== inputHashes[file])
+            return true;
+    }
+    return false;
+}
+export async function loadContextGraphIndex(root, options = {}) {
+    const supplied = options.status;
+    if (supplied) {
+        const blocked = statusFailure(supplied);
+        if (blocked && !(supplied.status === 'stale' && options.allowStale === true))
+            return blocked;
+    }
+    const metaLoad = await readContextGraphMeta(root);
+    if (metaLoad.status === 'missing')
+        return failure(CONTEXT_GRAPH_MISSING_ERROR, 'the context graph has not been built');
+    if (metaLoad.status !== 'ok' || !metaLoad.meta) {
+        return failure(CONTEXT_GRAPH_CORRUPT_ERROR, 'the context graph metadata is unreadable');
+    }
+    const meta = metaLoad.meta;
+    const warnings = [];
+    if (options.verifySources === true) {
+        const changed = await sourcesChanged(root, meta.inputHashes ?? {}, options.maxVerifiedSources ?? DEFAULT_MAX_VERIFIED_SOURCES);
+        if (changed && options.allowStale !== true) {
+            return failure(CONTEXT_GRAPH_STALE_ERROR, 'a recorded source no longer hashes to its stored value', meta.snapshotHash);
+        }
+        if (changed)
+            warnings.push('answering over a stale context graph on request');
+    }
+    else if (!supplied) {
+        warnings.push(`context graph freshness was not verified by this query; ${contextGraphRepairHint()}`);
+    }
+    const useCache = options.cache !== false;
+    if (useCache) {
+        const cached = getCachedContextGraphIndex(root, meta.snapshotHash);
+        if (cached) {
+            return {
+                ok: true,
+                index: cached,
+                snapshotHash: meta.snapshotHash,
+                errorCode: null,
+                errors: [],
+                warnings,
+                cacheHit: true,
+                freshness: supplied?.status === 'stale' ? 'stale' : 'fresh'
+            };
+        }
+    }
+    const snapshotLoad = await readContextGraphSnapshot(root);
+    if (snapshotLoad.status === 'missing') {
+        return failure(CONTEXT_GRAPH_MISSING_ERROR, 'the context graph snapshot is absent while its metadata is present');
+    }
+    if (snapshotLoad.status !== 'ok' || !snapshotLoad.snapshot) {
+        return failure(CONTEXT_GRAPH_CORRUPT_ERROR, 'the context graph snapshot failed structural validation');
+    }
+    const snapshot = snapshotLoad.snapshot;
+    if (snapshot.snapshotHash !== meta.snapshotHash
+        || snapshot.nodeCount !== meta.nodeCount
+        || snapshot.edgeCount !== meta.edgeCount) {
+        return failure(CONTEXT_GRAPH_CORRUPT_ERROR, 'the snapshot and its metadata describe different graphs', snapshot.snapshotHash);
+    }
+    if (snapshot.schemaRevision !== CONTEXT_GRAPH_SCHEMA_REVISION) {
+        return failure(CONTEXT_GRAPH_STALE_ERROR, 'the snapshot was written by a different graph schema revision', snapshot.snapshotHash);
+    }
+    const index = buildContextGraphIndex(snapshot);
+    if (useCache)
+        cacheContextGraphIndex(root, snapshot.snapshotHash, index);
+    return {
+        ok: true,
+        index,
+        snapshotHash: snapshot.snapshotHash,
+        errorCode: null,
+        errors: [],
+        warnings,
+        cacheHit: false,
+        freshness: supplied?.status === 'stale' ? 'stale' : 'fresh'
+    };
+}

package/dist/core/triwiki/context-graph/query/pack.js

@@ -0,0 +1,117 @@
+import { compareContextGraphIds } from '../ids.js';
+function bump(into, reason) {
+    into[reason] = (into[reason] ?? 0) + 1;
+}
+function isProtectedGate(entry) {
+    return entry.candidate.node.risk === 'protected';
+}
+function isImplementationEvidence(entry) {
+    const kind = entry.candidate.node.kind;
+    return kind === 'test' || kind === 'gate';
+}
+function byScoreThenId(left, right) {
+    if (left.candidate.score !== right.candidate.score)
+        return right.candidate.score - left.candidate.score;
+    return compareContextGraphIds(left.candidate.node.id, right.candidate.node.id);
+}
+class Packer {
+    budget;
+    limit;
+    chosen = new Map();
+    perGroup = new Map();
+    omissions = {};
+    spent = 0;
+    constructor(budget, limit) {
+        this.budget = budget;
+        this.limit = limit;
+    }
+    has(entry) {
+        return this.chosen.has(entry.candidate.node.id);
+    }
+    take(entry) {
+        if (this.chosen.size >= this.limit) {
+            bump(this.omissions, 'max_selected');
+            return false;
+        }
+        const cost = entry.candidate.tokenCost;
+        if (this.spent + cost > this.budget) {
+            bump(this.omissions, 'token_budget');
+            return false;
+        }
+        this.chosen.set(entry.candidate.node.id, entry);
+        this.spent += cost;
+        const group = entry.candidate.groupKey;
+        this.perGroup.set(group, (this.perGroup.get(group) ?? 0) + 1);
+        return true;
+    }
+    groupCount(entry) {
+        return this.perGroup.get(entry.candidate.groupKey) ?? 0;
+    }
+}
+export function packContextGraphSelection(input) {
+    const { explained, tokenBudget, maxSelected, profile, highRisk, config } = input;
+    const ordered = [...explained].sort(byScoreThenId);
+    const packer = new Packer(Math.max(0, tokenBudget), Math.max(0, maxSelected));
+    const warnings = [];
+    const exactSeeds = ordered.filter((entry) => entry.candidate.exactSeed);
+    const protectedGates = ordered.filter(isProtectedGate);
+    const implementationEvidence = ordered.filter(isImplementationEvidence);
+    const reserved = [];
+    if (highRisk) {
+        for (const gate of protectedGates.slice(0, config.protectedGateReserveSlots))
+            reserved.push(gate);
+    }
+    const firstExactSeed = exactSeeds[0];
+    if (firstExactSeed)
+        reserved.push(firstExactSeed);
+    if (profile === 'implementation') {
+        for (const evidence of implementationEvidence.slice(0, config.testOrGateReserveSlots))
+            reserved.push(evidence);
+    }
+    for (const entry of reserved) {
+        if (packer.has(entry))
+            continue;
+        packer.take(entry);
+    }
+    const slotAllowance = Math.max(config.minGroupSlots, Math.ceil(Math.max(0, maxSelected) * config.moduleShareCap));
+    const distinctGroups = new Set(ordered.map((entry) => entry.candidate.groupKey)).size;
+    const diversityApplies = distinctGroups > 1;
+    for (const entry of ordered) {
+        if (packer.has(entry))
+            continue;
+        if (diversityApplies && packer.groupCount(entry) >= slotAllowance) {
+            bump(packer.omissions, 'redundant_sibling');
+            continue;
+        }
+        packer.take(entry);
+    }
+    const selected = [...packer.chosen.values()].sort(byScoreThenId);
+    const selectedIds = new Set(selected.map((entry) => entry.candidate.node.id));
+    const protectedSelected = protectedGates.filter((entry) => selectedIds.has(entry.candidate.node.id)).length;
+    const guarantees = {
+        exactSeedSelected: selected.some((entry) => entry.candidate.exactSeed),
+        exactSeedAvailable: exactSeeds.length > 0,
+        protectedGatesReachable: protectedGates.length,
+        protectedGatesSelected: protectedSelected,
+        implementationEvidenceReachable: implementationEvidence.length > 0,
+        implementationEvidenceSelected: implementationEvidence.some((entry) => selectedIds.has(entry.candidate.node.id))
+    };
+    if (guarantees.exactSeedAvailable && !guarantees.exactSeedSelected) {
+        warnings.push('exact seed did not fit the token budget; widen tokenBudget or narrow the query');
+    }
+    if (highRisk && guarantees.protectedGatesReachable > guarantees.protectedGatesSelected) {
+        warnings.push('a reachable protected gate did not fit the token budget on a high-risk query');
+    }
+    if (profile === 'implementation' && guarantees.implementationEvidenceReachable && !guarantees.implementationEvidenceSelected) {
+        warnings.push('no reachable test or gate fit the token budget on an implementation query');
+    }
+    const truncated = (packer.omissions.token_budget ?? 0) > 0 || (packer.omissions.max_selected ?? 0) > 0;
+    return {
+        selected,
+        tokenCost: packer.spent,
+        omissions: packer.omissions,
+        truncated,
+        warnings,
+        guarantees
+    };
+}

package/dist/core/triwiki/context-graph/query/rank.js

@@ -0,0 +1,142 @@
+import { compareContextGraphIds, contextGraphPathFromId } from '../ids.js';
+import { isExactContextGraphSeedConfidence } from './ranking-config.js';
+export function contextGraphGroupKey(node) {
+    const nodePath = node.path ?? contextGraphPathFromId(node.id);
+    if (nodePath) {
+        const cut = nodePath.lastIndexOf('/');
+        return cut > 0 ? nodePath.slice(0, cut) : '.';
+    }
+    const module = node.metadata.module;
+    if (typeof module === 'string' && module)
+        return `module/${module}`;
+    return `kind/${node.kind}`;
+}
+export function isInvalidatedContextGraphNode(index, node) {
+    const metadata = node.metadata;
+    if (node.kind === 'proof') {
+        if (metadata.reusable === false)
+            return true;
+        if (metadata.corrupt === true)
+            return true;
+        if (metadata.expired === true)
+            return true;
+        const reasons = metadata.invalidation_reason_count;
+        if (typeof reasons === 'number' && reasons > 0)
+            return true;
+    }
+    for (const edgeId of index.outgoing.get(node.id) ?? []) {
+        if (index.edgesById.get(edgeId)?.type === 'invalidates')
+            return true;
+    }
+    return false;
+}
+function evidenceSourceCount(index, node, state) {
+    let count = 0;
+    if (node.path && node.contentHash)
+        count += 1;
+    if (state.parentEdgeId)
+        count += 1;
+    if ((index.outgoing.get(node.id)?.length ?? 0) > 0 || (index.incoming.get(node.id)?.length ?? 0) > 0)
+        count += 1;
+    return count;
+}
+export function isHighRiskScope(index, seeds, request) {
+    if (request.risk === 'high')
+        return true;
+    for (const seed of seeds) {
+        if (index.nodesById.get(seed.nodeId)?.risk === 'protected')
+            return true;
+    }
+    return false;
+}
+function baseScore(node, state, seed, input, invalidated, tokenCost, evidence) {
+    const config = input.config;
+    const exact = seed !== null && isExactContextGraphSeedConfidence(seed.confidence);
+    const seedBonus = seed === null ? 0 : exact ? config.exactSeedBonus : config.lexicalSeedBonus;
+    const riskScale = input.request.risk === 'high' ? config.highRiskRelevanceMultiplier : 1;
+    const evidenceBonus = Math.min(config.evidenceCoverageCap, config.evidenceCoverageBonus * evidence);
+    const stalePenalty = node.freshness === 'stale' ? config.stalePenalty : 0;
+    const invalidatedPenalty = invalidated ? config.invalidatedPenalty : 0;
+    const tokenPenalty = Math.min(config.tokenCostPenaltyCap, config.tokenCostPenaltyPerToken * tokenCost);
+    return (seedBonus
+        + state.weight
+        + config.trustBonus * node.trust
+        + config.freshnessBonus[node.freshness]
+        + config.riskRelevanceBonus[node.risk] * riskScale
+        + evidenceBonus
+        - stalePenalty
+        - invalidatedPenalty
+        - tokenPenalty);
+}
+function byScoreThenId(left, right) {
+    if (left.score !== right.score)
+        return right.score - left.score;
+    return compareContextGraphIds(left.node.id, right.node.id);
+}
+export function rankContextGraphCandidates(input) {
+    const { index, states, seedsByNode, config, focusActive } = input;
+    const candidates = [];
+    const excludedNodeIds = [];
+    let staleExcluded = 0;
+    let invalidatedExcluded = 0;
+    let focusExcluded = 0;
+    for (const state of states.values()) {
+        const node = index.nodesById.get(state.nodeId);
+        if (!node)
+            continue;
+        if (focusActive && !state.focusMatched) {
+            focusExcluded += 1;
+            continue;
+        }
+        const invalidated = isInvalidatedContextGraphNode(index, node);
+        if (node.freshness === 'stale') {
+            staleExcluded += 1;
+            excludedNodeIds.push(node.id);
+            continue;
+        }
+        if (invalidated) {
+            invalidatedExcluded += 1;
+            excludedNodeIds.push(node.id);
+            continue;
+        }
+        const seed = seedsByNode.get(state.nodeId) ?? null;
+        const tokenCost = Math.max(config.minTokenCost, node.tokenCost);
+        const evidence = evidenceSourceCount(index, node, state);
+        candidates.push({
+            node,
+            state,
+            seed,
+            exactSeed: seed !== null && isExactContextGraphSeedConfidence(seed.confidence),
+            groupKey: contextGraphGroupKey(node),
+            tokenCost,
+            evidenceSources: evidence,
+            score: baseScore(node, state, seed, input, invalidated, tokenCost, evidence),
+            redundancyPenalty: 0
+        });
+    }
+    candidates.sort(byScoreThenId);
+    const perGroup = new Map();
+    const kept = [];
+    let redundantExcluded = 0;
+    for (const candidate of candidates) {
+        const prior = perGroup.get(candidate.groupKey) ?? 0;
+        if (prior >= config.maxRedundancyGroupMembers && !candidate.exactSeed) {
+            redundantExcluded += 1;
+            continue;
+        }
+        perGroup.set(candidate.groupKey, prior + 1);
+        const penalty = Math.min(config.redundancyPenaltyCap, config.redundancyPenalty * prior);
+        candidate.redundancyPenalty = penalty;
+        candidate.score -= penalty;
+        kept.push(candidate);
+    }
+    kept.sort(byScoreThenId);
+    return {
+        candidates: kept,
+        staleExcluded,
+        invalidatedExcluded,
+        redundantExcluded,
+        focusExcluded,
+        excludedNodeIds: excludedNodeIds.sort(compareContextGraphIds)
+    };
+}

package/dist/core/triwiki/context-graph/query/ranking-config.js

@@ -0,0 +1,64 @@
+export const CONTEXT_GRAPH_RANKING_SCHEMA = 'sks.context-graph-ranking.v1';
+export const CONTEXT_GRAPH_EXACT_SEED_CONFIDENCES = [
+    'exact_definition',
+    'exact_reference',
+    'manifest',
+    'file_path'
+];
+export const CONTEXT_GRAPH_RANKING_CONFIG = {
+    schema: CONTEXT_GRAPH_RANKING_SCHEMA,
+    seedConfidenceScore: {
+        exact_definition: 6,
+        exact_reference: 5,
+        manifest: 5,
+        syntactic_reference: 3.5,
+        file_path: 4,
+        text_candidate: 1.5
+    },
+    exactSeedBonus: 4,
+    lexicalSeedBonus: 0.5,
+    providedSeedScoreCeiling: 8,
+    edgeConfidenceMultiplier: {
+        exact: 1,
+        manifest: 0.95,
+        syntactic: 0.85,
+        observed: 0.7,
+        derived: 0.5
+    },
+    depthDecay: 0.6,
+    reverseEdgeMultiplier: 0.85,
+    trustBonus: 1.5,
+    freshnessBonus: { fresh: 0.75, unknown: 0, stale: -0.5 },
+    riskRelevanceBonus: { low: 0, medium: 0.25, high: 0.75, protected: 1.5 },
+    highRiskRelevanceMultiplier: 2,
+    evidenceCoverageBonus: 0.35,
+    evidenceCoverageCap: 1.05,
+    stalePenalty: 2.5,
+    invalidatedPenalty: 4,
+    redundancyPenalty: 0.6,
+    redundancyPenaltyCap: 3,
+    tokenCostPenaltyPerToken: 0.0015,
+    tokenCostPenaltyCap: 1.5,
+    minExactSeeds: 3,
+    maxLexicalSeeds: 8,
+    lexicalScanBudget: 50000,
+    lexicalMinTokenLength: 4,
+    lexicalMatchScore: 1.5,
+    maxQueryTokens: 24,
+    maxSeedsPerToken: 6,
+    timeoutCheckInterval: 512,
+    moduleShareCap: 0.4,
+    minGroupSlots: 2,
+    maxRedundancyGroupMembers: 12,
+    protectedGateReserveSlots: 8,
+    testOrGateReserveSlots: 1,
+    maxProvenancePerNode: 6,
+    minTokenCost: 1
+};
+const EXACT_SEED_CONFIDENCE_SET = new Set(CONTEXT_GRAPH_EXACT_SEED_CONFIDENCES);
+export function isExactContextGraphSeedConfidence(value) {
+    return EXACT_SEED_CONFIDENCE_SET.has(value);
+}
+export function contextGraphSeedConfidenceScore(config, confidence) {
+    return config.seedConfidenceScore[confidence];
+}