@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/node_modules/@ktx/context/dist/ingest/context-candidates/candidate-dedup.service.js

@@ -0,0 +1,234 @@
+import { noopLogger } from '../../core/index.js';
+import { buildContextCandidateEmbeddingText } from './embedding-text.js';
+export class CandidateDedupService {
+    deps;
+    logger;
+    constructor(deps) {
+        this.deps = deps;
+        this.logger = deps.logger ?? noopLogger;
+    }
+    async deduplicateRun(runId) {
+        const candidates = await this.deps.store.listPendingCandidatesForDedup(runId);
+        const config = this.deps.settings;
+        if (!config.enabled) {
+            return this.rawResult(candidates, false, [], 0);
+        }
+        try {
+            const prepared = await this.prepareEmbeddings(candidates);
+            const clusters = this.clusterCandidates(prepared.candidates, config.topicSimilarityThreshold);
+            const effectiveScores = await this.persistClusters(clusters, config.scoreAggregation);
+            const mergedCount = clusters.reduce((sum, cluster) => sum + Math.max(cluster.members.length - 1, 0), 0);
+            const largestClusterSize = clusters.reduce((max, cluster) => Math.max(max, cluster.members.length), 0);
+            const representatives = clusters
+                .map((cluster) => {
+                const representative = this.stripVector(cluster.representative);
+                return {
+                    ...representative,
+                    promotionScore: effectiveScores.get(cluster.representative.id) ?? representative.promotionScore,
+                };
+            })
+                .sort((left, right) => {
+                if (right.promotionScore !== left.promotionScore) {
+                    return right.promotionScore - left.promotionScore;
+                }
+                return left.createdAt.getTime() - right.createdAt.getTime();
+            });
+            this.logger.log(`Dedup: ${candidates.length} candidates -> ${representatives.length} clusters (largest cluster ${largestClusterSize} members)`);
+            return {
+                enabled: true,
+                candidatesIn: candidates.length,
+                clustersOut: representatives.length,
+                mergedCount,
+                largestClusterSize,
+                embeddingFailures: prepared.embeddingFailures,
+                representatives,
+                warnings: prepared.warnings,
+            };
+        }
+        catch (error) {
+            const message = `Dedup failed for run ${runId}: ${error instanceof Error ? error.message : String(error)}`;
+            this.logger.warn(message);
+            return this.rawResult(candidates, true, [message], 0);
+        }
+    }
+    async prepareEmbeddings(candidates) {
+        const prepared = candidates.map((candidate) => ({
+            ...candidate,
+            embeddingVector: this.parseEmbedding(candidate.embedding),
+        }));
+        const missing = prepared.filter((candidate) => candidate.embeddingVector === null);
+        const warnings = [];
+        let embeddingFailures = 0;
+        for (let i = 0; i < missing.length; i += this.deps.embeddings.maxBatchSize) {
+            const batch = missing.slice(i, i + this.deps.embeddings.maxBatchSize);
+            const texts = batch.map((candidate) => buildContextCandidateEmbeddingText(candidate));
+            try {
+                const embeddings = await this.deps.embeddings.computeEmbeddingsBulk(texts);
+                if (embeddings.length !== batch.length) {
+                    throw new Error(`expected ${batch.length} embeddings, got ${embeddings.length}`);
+                }
+                for (let index = 0; index < batch.length; index++) {
+                    batch[index].embeddingVector = embeddings[index];
+                    await this.deps.store.updateCandidateEmbedding(batch[index].id, embeddings[index]);
+                }
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                warnings.push(`embedding bulk failed: ${reason}; falling back to per-candidate embedding for ${batch.length} candidates`);
+                for (const candidate of batch) {
+                    try {
+                        const embedding = await this.deps.embeddings.computeEmbedding(buildContextCandidateEmbeddingText(candidate));
+                        candidate.embeddingVector = embedding;
+                        await this.deps.store.updateCandidateEmbedding(candidate.id, embedding);
+                    }
+                    catch (singleError) {
+                        embeddingFailures += 1;
+                        warnings.push(`Embedding failed for candidate ${candidate.candidateKey}: ${singleError instanceof Error ? singleError.message : String(singleError)}`);
+                    }
+                }
+            }
+        }
+        return { candidates: prepared, embeddingFailures, warnings };
+    }
+    clusterCandidates(candidates, threshold) {
+        const clusters = [];
+        const sorted = [...candidates].sort((left, right) => {
+            if (right.promotionScore !== left.promotionScore) {
+                return right.promotionScore - left.promotionScore;
+            }
+            return left.createdAt.getTime() - right.createdAt.getTime();
+        });
+        for (const candidate of sorted) {
+            if (!candidate.embeddingVector) {
+                clusters.push({ representative: candidate, members: [candidate] });
+                continue;
+            }
+            const match = clusters.find((cluster) => cluster.representative.embeddingVector &&
+                candidate.embeddingVector &&
+                this.cosine(candidate.embeddingVector, cluster.representative.embeddingVector) >= threshold);
+            if (match) {
+                match.members.push(candidate);
+            }
+            else {
+                clusters.push({ representative: candidate, members: [candidate] });
+            }
+        }
+        return clusters;
+    }
+    async persistClusters(clusters, scoreAggregation) {
+        const effectiveScores = new Map();
+        for (const cluster of clusters) {
+            if (cluster.members.length <= 1) {
+                effectiveScores.set(cluster.representative.id, cluster.representative.promotionScore);
+                continue;
+            }
+            const promotionScore = this.aggregateScore(cluster.members, scoreAggregation);
+            effectiveScores.set(cluster.representative.id, promotionScore);
+            await this.deps.store.markCandidatesAsMergedToCluster({
+                representativeId: cluster.representative.id,
+                memberIds: cluster.members.slice(1).map((member) => member.id),
+                evidenceChunkIds: this.unionEvidenceChunkIds(cluster.members),
+                evidenceRefs: this.unionEvidenceRefs(cluster.members),
+                promotionScore,
+            });
+        }
+        return effectiveScores;
+    }
+    parseEmbedding(value) {
+        if (!value) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(value);
+            if (Array.isArray(parsed) && parsed.every((item) => typeof item === 'number')) {
+                return parsed;
+            }
+        }
+        catch {
+            return null;
+        }
+        return null;
+    }
+    cosine(left, right) {
+        let dot = 0;
+        let leftNorm = 0;
+        let rightNorm = 0;
+        const length = Math.min(left.length, right.length);
+        for (let i = 0; i < length; i++) {
+            dot += left[i] * right[i];
+            leftNorm += left[i] * left[i];
+            rightNorm += right[i] * right[i];
+        }
+        if (leftNorm === 0 || rightNorm === 0) {
+            return 0;
+        }
+        return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
+    }
+    unionEvidenceChunkIds(members) {
+        const seen = new Set();
+        for (const member of members) {
+            for (const chunkId of member.evidenceChunkIds) {
+                seen.add(chunkId);
+            }
+        }
+        return [...seen];
+    }
+    unionEvidenceRefs(members) {
+        const refs = [];
+        const seen = new Set();
+        for (const member of members) {
+            if (!Array.isArray(member.evidenceRefs)) {
+                continue;
+            }
+            for (const ref of member.evidenceRefs) {
+                const key = this.evidenceRefKey(ref);
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    refs.push(ref);
+                }
+            }
+        }
+        return refs;
+    }
+    evidenceRefKey(ref) {
+        if (ref && typeof ref === 'object' && !Array.isArray(ref)) {
+            const record = ref;
+            if (typeof record.stableCitationKey === 'string') {
+                return `stable:${record.stableCitationKey}`;
+            }
+            if (typeof record.chunkId === 'string') {
+                return `chunk:${record.chunkId}`;
+            }
+            if (typeof record.rawPath === 'string') {
+                return `raw:${record.rawPath}`;
+            }
+        }
+        return JSON.stringify(ref);
+    }
+    aggregateScore(members, mode) {
+        const scores = members.map((member) => member.promotionScore);
+        if (mode === 'sum') {
+            return scores.reduce((sum, score) => sum + score, 0);
+        }
+        if (mode === 'mean') {
+            return Math.round(scores.reduce((sum, score) => sum + score, 0) / scores.length);
+        }
+        return Math.max(...scores);
+    }
+    rawResult(candidates, enabled, warnings, embeddingFailures) {
+        return {
+            enabled,
+            candidatesIn: candidates.length,
+            clustersOut: candidates.length,
+            mergedCount: 0,
+            largestClusterSize: candidates.length > 0 ? 1 : 0,
+            embeddingFailures,
+            representatives: candidates,
+            warnings,
+        };
+    }
+    stripVector(candidate) {
+        const { embeddingVector: _embeddingVector, ...rest } = candidate;
+        return rest;
+    }
+}

package/node_modules/@ktx/context/dist/ingest/context-candidates/candidate-dedup.service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@ktx/context/dist/ingest/context-candidates/candidate-dedup.service.test.js

@@ -0,0 +1,216 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { CandidateDedupService } from './candidate-dedup.service.js';
+const vector = (...values) => JSON.stringify(values);
+const candidate = (overrides) => ({
+    id: `${overrides.candidateKey}-id`,
+    candidateKey: overrides.candidateKey,
+    topic: overrides.topic ?? overrides.candidateKey,
+    assertion: overrides.assertion ?? `Assertion for ${overrides.candidateKey}`,
+    promotionScore: overrides.promotionScore ?? 1,
+    createdAt: overrides.createdAt ?? new Date('2026-04-29T10:00:00.000Z'),
+    evidenceChunkIds: overrides.evidenceChunkIds ?? [],
+    evidenceRefs: overrides.evidenceRefs ?? [],
+    embedding: 'embedding' in overrides ? (overrides.embedding ?? null) : vector(1, 0, 0),
+    lane: overrides.lane ?? null,
+});
+function buildHarness(overrides = {}) {
+    const store = {
+        listPendingCandidatesForDedup: vi.fn().mockResolvedValue(overrides.candidates ?? []),
+        updateCandidateEmbedding: vi.fn().mockResolvedValue(undefined),
+        markCandidatesAsMergedToCluster: vi.fn().mockResolvedValue(undefined),
+        listBudgetExhaustedCandidatesForCarryForward: vi.fn(),
+        listCurrentRunEvidenceChunksForCarryForward: vi.fn(),
+        insertCandidate: vi.fn(),
+    };
+    const embeddings = {
+        maxBatchSize: 100,
+        computeEmbedding: vi.fn(),
+        computeEmbeddingsBulk: vi.fn(),
+    };
+    const service = new CandidateDedupService({
+        store: store,
+        embeddings: embeddings,
+        settings: {
+            enabled: overrides.enabled ?? true,
+            topicSimilarityThreshold: overrides.threshold ?? 0.85,
+            scoreAggregation: overrides.scoreAggregation ?? 'max',
+        },
+    });
+    return { service, store, embeddings };
+}
+describe('CandidateDedupService', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns raw representatives without writes when dedup is disabled', async () => {
+        const first = candidate({ candidateKey: 'first', embedding: vector(1, 0, 0) });
+        const duplicate = candidate({ candidateKey: 'duplicate', embedding: vector(0.99, 0.01, 0) });
+        const { service, store, embeddings } = buildHarness({
+            enabled: false,
+            candidates: [first, duplicate],
+        });
+        const result = await service.deduplicateRun('run-1');
+        expect(result).toMatchObject({
+            enabled: false,
+            candidatesIn: 2,
+            clustersOut: 2,
+            mergedCount: 0,
+            largestClusterSize: 1,
+            embeddingFailures: 0,
+        });
+        expect(result.representatives.map((item) => item.candidateKey)).toEqual(['first', 'duplicate']);
+        expect(store.markCandidatesAsMergedToCluster).not.toHaveBeenCalled();
+        expect(embeddings.computeEmbeddingsBulk).not.toHaveBeenCalled();
+    });
+    it('clusters near duplicates and persists representative evidence unions', async () => {
+        const rep = candidate({
+            candidateKey: 'icp-primary',
+            topic: 'ICP',
+            assertion: 'Finance operators are the ICP.',
+            promotionScore: 11,
+            evidenceChunkIds: ['00000000-0000-0000-0000-000000000001'],
+            evidenceRefs: [{ stableCitationKey: 'icp-a', rawPath: 'pages/a/page.md' }],
+            embedding: vector(1, 0, 0),
+        });
+        const duplicate = candidate({
+            candidateKey: 'icp-duplicate',
+            topic: 'Ideal customer profile',
+            assertion: 'The ICP is finance teams.',
+            promotionScore: 7,
+            evidenceChunkIds: ['00000000-0000-0000-0000-000000000002'],
+            evidenceRefs: [{ stableCitationKey: 'icp-b', rawPath: 'pages/b/page.md' }],
+            embedding: vector(0.99, 0.02, 0),
+        });
+        const unique = candidate({
+            candidateKey: 'pricing-policy',
+            promotionScore: 6,
+            evidenceChunkIds: ['00000000-0000-0000-0000-000000000003'],
+            evidenceRefs: [{ stableCitationKey: 'price-a', rawPath: 'pages/pricing/page.md' }],
+            embedding: vector(0, 1, 0),
+        });
+        const { service, store } = buildHarness({ candidates: [rep, duplicate, unique] });
+        const result = await service.deduplicateRun('run-1');
+        expect(result).toMatchObject({
+            enabled: true,
+            candidatesIn: 3,
+            clustersOut: 2,
+            mergedCount: 1,
+            largestClusterSize: 2,
+            embeddingFailures: 0,
+        });
+        expect(result.representatives.map((item) => item.candidateKey)).toEqual(['icp-primary', 'pricing-policy']);
+        expect(store.markCandidatesAsMergedToCluster).toHaveBeenCalledWith({
+            representativeId: rep.id,
+            memberIds: [duplicate.id],
+            evidenceChunkIds: ['00000000-0000-0000-0000-000000000001', '00000000-0000-0000-0000-000000000002'],
+            evidenceRefs: [
+                { stableCitationKey: 'icp-a', rawPath: 'pages/a/page.md' },
+                { stableCitationKey: 'icp-b', rawPath: 'pages/b/page.md' },
+            ],
+            promotionScore: 11,
+        });
+    });
+    it('uses the configured similarity threshold', async () => {
+        const base = candidate({ candidateKey: 'base', embedding: vector(1, 0, 0), promotionScore: 5 });
+        const borderline = candidate({ candidateKey: 'borderline', embedding: vector(0.8, 0.6, 0), promotionScore: 4 });
+        const strict = buildHarness({ candidates: [base, borderline], threshold: 0.95 });
+        const strictResult = await strict.service.deduplicateRun('run-1');
+        expect(strictResult.clustersOut).toBe(2);
+        expect(strict.store.markCandidatesAsMergedToCluster).not.toHaveBeenCalled();
+        const loose = buildHarness({ candidates: [base, borderline], threshold: 0.75 });
+        const looseResult = await loose.service.deduplicateRun('run-1');
+        expect(looseResult.clustersOut).toBe(1);
+        expect(loose.store.markCandidatesAsMergedToCluster).toHaveBeenCalledTimes(1);
+    });
+    it('fills missing embeddings in batches and persists them before clustering', async () => {
+        const first = candidate({ candidateKey: 'missing-a', embedding: null });
+        const second = candidate({ candidateKey: 'missing-b', embedding: null });
+        const { service, store, embeddings } = buildHarness({ candidates: [first, second] });
+        embeddings.computeEmbeddingsBulk.mockResolvedValueOnce([
+            [1, 0, 0],
+            [0, 1, 0],
+        ]);
+        const result = await service.deduplicateRun('run-1');
+        expect(result.embeddingFailures).toBe(0);
+        expect(embeddings.computeEmbeddingsBulk).toHaveBeenCalledWith([
+            'missing-a - Assertion for missing-a',
+            'missing-b - Assertion for missing-b',
+        ]);
+        expect(store.updateCandidateEmbedding).toHaveBeenCalledWith(first.id, [1, 0, 0]);
+        expect(store.updateCandidateEmbedding).toHaveBeenCalledWith(second.id, [0, 1, 0]);
+    });
+    it('isolates a single embedding failure and keeps that candidate as a singleton', async () => {
+        const first = candidate({ candidateKey: 'embed-ok', embedding: null });
+        const second = candidate({ candidateKey: 'embed-fail', embedding: null });
+        const { service, store, embeddings } = buildHarness({ candidates: [first, second] });
+        embeddings.computeEmbeddingsBulk.mockRejectedValueOnce(new Error('bulk provider unavailable'));
+        embeddings.computeEmbedding
+            .mockResolvedValueOnce([1, 0, 0])
+            .mockRejectedValueOnce(new Error('single candidate failed'));
+        const result = await service.deduplicateRun('run-1');
+        expect(result.embeddingFailures).toBe(1);
+        expect(result.clustersOut).toBe(2);
+        expect(result.warnings).toEqual(expect.arrayContaining([
+            expect.stringContaining('embedding bulk failed: bulk provider unavailable; falling back to per-candidate embedding for 2 candidates'),
+            expect.stringContaining('Embedding failed for candidate embed-fail'),
+        ]));
+        expect(store.updateCandidateEmbedding).toHaveBeenCalledTimes(1);
+        expect(store.updateCandidateEmbedding).toHaveBeenCalledWith(first.id, [1, 0, 0]);
+    });
+    it('applies mean and sum score aggregation modes', async () => {
+        const rep = candidate({ candidateKey: 'score-rep', promotionScore: 9, embedding: vector(1, 0, 0) });
+        const duplicate = candidate({
+            candidateKey: 'score-duplicate',
+            promotionScore: 3,
+            embedding: vector(0.99, 0.02, 0),
+        });
+        const mean = buildHarness({ candidates: [rep, duplicate], scoreAggregation: 'mean' });
+        await mean.service.deduplicateRun('run-1');
+        expect(mean.store.markCandidatesAsMergedToCluster).toHaveBeenCalledWith(expect.objectContaining({ promotionScore: 6 }));
+        const sum = buildHarness({ candidates: [rep, duplicate], scoreAggregation: 'sum' });
+        await sum.service.deduplicateRun('run-1');
+        expect(sum.store.markCandidatesAsMergedToCluster).toHaveBeenCalledWith(expect.objectContaining({ promotionScore: 12 }));
+    });
+    it('rounds mean score aggregation for the integer promotion score column', async () => {
+        const rep = candidate({ candidateKey: 'rounded-rep', promotionScore: 10, embedding: vector(1, 0, 0) });
+        const duplicate = candidate({
+            candidateKey: 'rounded-duplicate',
+            promotionScore: 7,
+            embedding: vector(0.99, 0.02, 0),
+        });
+        const { service, store } = buildHarness({ candidates: [rep, duplicate], scoreAggregation: 'mean' });
+        await service.deduplicateRun('run-1');
+        expect(store.markCandidatesAsMergedToCluster).toHaveBeenCalledWith(expect.objectContaining({ promotionScore: 9 }));
+    });
+    it('is a no-op on a rerun after non-representatives are already merged', async () => {
+        const rep = candidate({ candidateKey: 'rerun-rep', promotionScore: 9, embedding: vector(1, 0, 0) });
+        const duplicate = candidate({
+            candidateKey: 'rerun-duplicate',
+            promotionScore: 3,
+            embedding: vector(0.99, 0.02, 0),
+        });
+        const { service, store } = buildHarness();
+        store.listPendingCandidatesForDedup.mockResolvedValueOnce([rep, duplicate]).mockResolvedValueOnce([rep]);
+        const first = await service.deduplicateRun('run-1');
+        const second = await service.deduplicateRun('run-1');
+        expect(first.mergedCount).toBe(1);
+        expect(second.mergedCount).toBe(0);
+        expect(second.clustersOut).toBe(1);
+        expect(store.markCandidatesAsMergedToCluster).toHaveBeenCalledTimes(1);
+    });
+    it('returns raw candidates with a warning when cluster persistence throws', async () => {
+        const rep = candidate({ candidateKey: 'persist-rep', promotionScore: 9, embedding: vector(1, 0, 0) });
+        const duplicate = candidate({
+            candidateKey: 'persist-duplicate',
+            promotionScore: 3,
+            embedding: vector(0.99, 0.02, 0),
+        });
+        const { service, store } = buildHarness({ candidates: [rep, duplicate] });
+        store.markCandidatesAsMergedToCluster.mockRejectedValueOnce(new Error('database unavailable'));
+        const result = await service.deduplicateRun('run-1');
+        expect(result.clustersOut).toBe(2);
+        expect(result.mergedCount).toBe(0);
+        expect(result.representatives.map((item) => item.candidateKey)).toEqual(['persist-rep', 'persist-duplicate']);
+        expect(result.warnings).toEqual([expect.stringContaining('Dedup failed for run run-1')]);
+    });
+});

package/node_modules/@ktx/context/dist/ingest/context-candidates/context-candidate-carryforward.service.d.ts

@@ -0,0 +1,31 @@
+import { type KtxLogger } from '../../core/index.js';
+import type { ContextCandidateStorePort } from './store.js';
+import type { ContextCandidateCarryforwardSettings } from './types.js';
+export interface ContextCandidateCarryforwardArgs {
+    runId: string;
+    connectionId: string;
+    sourceKey: string;
+}
+export interface ContextCandidateCarryforwardResult {
+    considered: number;
+    carriedForward: number;
+    skippedNotReemitted: number;
+    remappedEvidenceRefs: number;
+    staleEvidenceRefs: number;
+    warnings: string[];
+}
+export interface ContextCandidateCarryforwardServiceDeps {
+    store: ContextCandidateStorePort;
+    settings: ContextCandidateCarryforwardSettings;
+    logger?: KtxLogger;
+}
+export declare class ContextCandidateCarryforwardService {
+    private readonly deps;
+    private readonly logger;
+    constructor(deps: ContextCandidateCarryforwardServiceDeps);
+    carryForward(args: ContextCandidateCarryforwardArgs): Promise<ContextCandidateCarryforwardResult>;
+    private remapEvidence;
+    private stableCitationKey;
+    private currentEvidenceRef;
+    private buildWarnings;
+}

package/node_modules/@ktx/context/dist/ingest/context-candidates/context-candidate-carryforward.service.js

@@ -0,0 +1,131 @@
+import { createHash } from 'node:crypto';
+import { noopLogger } from '../../core/index.js';
+export class ContextCandidateCarryforwardService {
+    deps;
+    logger;
+    constructor(deps) {
+        this.deps = deps;
+        this.logger = deps.logger ?? noopLogger;
+    }
+    async carryForward(args) {
+        const candidates = await this.deps.store.listBudgetExhaustedCandidatesForCarryForward({
+            connectionId: args.connectionId,
+            sourceKey: args.sourceKey,
+            currentRunId: args.runId,
+        });
+        const chunks = await this.deps.store.listCurrentRunEvidenceChunksForCarryForward(args.runId);
+        const chunksByStableKey = new Map(chunks.map((chunk) => [chunk.stableCitationKey, chunk]));
+        const allowStaleEvidence = this.deps.settings.reExamineBudgetExhaustedOnRerun;
+        let carriedForward = 0;
+        let skippedNotReemitted = 0;
+        let remappedEvidenceRefs = 0;
+        let staleEvidenceRefs = 0;
+        for (const candidate of candidates) {
+            const remap = this.remapEvidence(candidate, chunksByStableKey);
+            if (remap.remappedCount === 0 && !allowStaleEvidence) {
+                skippedNotReemitted += 1;
+                continue;
+            }
+            await this.deps.store.insertCandidate({
+                runId: args.runId,
+                connectionId: args.connectionId,
+                sourceKey: args.sourceKey,
+                candidateKey: candidate.candidateKey,
+                topic: candidate.topic,
+                assertion: candidate.assertion,
+                rationale: candidate.rationale,
+                evidenceChunkIds: remap.evidenceChunkIds,
+                evidenceRefs: remap.evidenceRefs,
+                suggestedPageKey: candidate.suggestedPageKey,
+                actionHint: candidate.actionHint,
+                durabilityScore: candidate.durabilityScore,
+                authorityScore: candidate.authorityScore,
+                reuseScore: candidate.reuseScore,
+                noveltyScore: candidate.noveltyScore,
+                riskScore: candidate.riskScore,
+                promotionScore: candidate.promotionScore,
+                status: 'pending',
+                rejectionReason: null,
+                lane: candidate.lane,
+                embedding: null,
+            });
+            carriedForward += 1;
+            remappedEvidenceRefs += remap.remappedCount;
+            staleEvidenceRefs += remap.staleCount;
+        }
+        const warnings = this.buildWarnings({ carriedForward, skippedNotReemitted, staleEvidenceRefs });
+        if (carriedForward > 0 || skippedNotReemitted > 0) {
+            this.logger.log(`Budget carryforward: considered ${candidates.length}, carried ${carriedForward}, skipped ${skippedNotReemitted}`);
+        }
+        return {
+            considered: candidates.length,
+            carriedForward,
+            skippedNotReemitted,
+            remappedEvidenceRefs,
+            staleEvidenceRefs,
+            warnings,
+        };
+    }
+    remapEvidence(candidate, chunksByStableKey) {
+        const refs = Array.isArray(candidate.evidenceRefs) ? candidate.evidenceRefs : [];
+        const remappedRefs = [];
+        const remappedChunkIds = [];
+        for (const ref of refs) {
+            const stableKey = this.stableCitationKey(ref);
+            const currentChunk = stableKey ? chunksByStableKey.get(stableKey) : undefined;
+            if (!currentChunk) {
+                continue;
+            }
+            remappedChunkIds.push(currentChunk.chunkId);
+            remappedRefs.push(this.currentEvidenceRef(currentChunk));
+        }
+        if (remappedRefs.length > 0) {
+            return {
+                evidenceChunkIds: [...new Set(remappedChunkIds)],
+                evidenceRefs: remappedRefs,
+                remappedCount: remappedRefs.length,
+                staleCount: 0,
+            };
+        }
+        return {
+            evidenceChunkIds: candidate.evidenceChunkIds,
+            evidenceRefs: candidate.evidenceRefs,
+            remappedCount: 0,
+            staleCount: refs.length,
+        };
+    }
+    stableCitationKey(ref) {
+        if (!ref || typeof ref !== 'object' || Array.isArray(ref)) {
+            return null;
+        }
+        const value = ref.stableCitationKey;
+        return typeof value === 'string' ? value : null;
+    }
+    currentEvidenceRef(chunk) {
+        return {
+            chunkId: chunk.chunkId,
+            stableCitationKey: chunk.stableCitationKey,
+            syncId: chunk.syncId,
+            rawPath: chunk.rawPath,
+            title: chunk.title,
+            path: chunk.path,
+            url: chunk.url,
+            lastEditedAt: chunk.lastEditedAt?.toISOString() ?? null,
+            snippetHash: createHash('sha256').update(chunk.content).digest('hex'),
+            citation: chunk.citation,
+        };
+    }
+    buildWarnings(params) {
+        const warnings = [];
+        if (params.carriedForward > 0) {
+            warnings.push(`Re-examined ${params.carriedForward} prior budget-exhausted context candidate${params.carriedForward === 1 ? '' : 's'}.`);
+        }
+        if (params.skippedNotReemitted > 0) {
+            warnings.push(`Skipped ${params.skippedNotReemitted} budget-exhausted context candidate${params.skippedNotReemitted === 1 ? '' : 's'} because its evidence was not re-emitted in this run.`);
+        }
+        if (params.staleEvidenceRefs > 0) {
+            warnings.push(`Carried ${params.staleEvidenceRefs} budget-exhausted evidence ref${params.staleEvidenceRefs === 1 ? '' : 's'} without a current-run chunk remap.`);
+        }
+        return warnings;
+    }
+}

package/node_modules/@ktx/context/dist/ingest/context-candidates/context-candidate-carryforward.service.test.d.ts

@@ -0,0 +1 @@
+export {};