@kaelio/ktx 0.0.0 → 0.1.0-rc.0

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

@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import { describe, expect, it, vi } from 'vitest';
+import { ContextCandidateCarryforwardService } from './context-candidate-carryforward.service.js';
+function candidate(overrides = {}) {
+    return {
+        sourceRunId: 'prior-run-1',
+        candidateKey: 'budget-revenue-policy',
+        topic: 'Revenue policy',
+        assertion: 'Booked revenue excludes refunds.',
+        rationale: 'The finance handbook states this reusable rule.',
+        evidenceChunkIds: ['prior-chunk-1'],
+        evidenceRefs: [
+            {
+                chunkId: 'prior-chunk-1',
+                stableCitationKey: 'notion:page-1:revenue-policy',
+                syncId: 'sync-prior',
+                rawPath: 'pages/page-1/page.md',
+            },
+        ],
+        suggestedPageKey: 'revenue-policy',
+        actionHint: 'create',
+        durabilityScore: 3,
+        authorityScore: 3,
+        reuseScore: 3,
+        noveltyScore: 2,
+        riskScore: 1,
+        promotionScore: 10,
+        lane: 'full',
+        ...overrides,
+    };
+}
+function chunk(overrides = {}) {
+    return {
+        chunkId: 'current-chunk-1',
+        stableCitationKey: 'notion:page-1:revenue-policy',
+        syncId: 'sync-current',
+        rawPath: 'pages/page-1/page.md',
+        title: 'Revenue Policy',
+        path: 'Company / Revenue Policy',
+        url: 'https://notion.example/page-1',
+        lastEditedAt: new Date('2026-04-30T12:00:00.000Z'),
+        citation: {
+            source: 'notion',
+            pageId: 'page-1',
+            syncId: 'sync-current',
+            rawPath: 'pages/page-1/page.md',
+        },
+        content: 'Booked revenue excludes refunds and test accounts.',
+        ...overrides,
+    };
+}
+function buildHarness(reExamineBudgetExhaustedOnRerun) {
+    const store = {
+        listPendingCandidatesForDedup: vi.fn(),
+        updateCandidateEmbedding: vi.fn(),
+        markCandidatesAsMergedToCluster: vi.fn(),
+        listBudgetExhaustedCandidatesForCarryForward: vi.fn(),
+        listCurrentRunEvidenceChunksForCarryForward: vi.fn(),
+        insertCandidate: vi.fn().mockResolvedValue({ id: 'new-candidate-1' }),
+    };
+    const service = new ContextCandidateCarryforwardService({
+        store: store,
+        settings: { reExamineBudgetExhaustedOnRerun },
+    });
+    return { service, store };
+}
+describe('ContextCandidateCarryforwardService', () => {
+    it('carries a prior budget-exhausted candidate with remapped current evidence', async () => {
+        const { service, store } = buildHarness(true);
+        store.listBudgetExhaustedCandidatesForCarryForward.mockResolvedValueOnce([candidate()]);
+        store.listCurrentRunEvidenceChunksForCarryForward.mockResolvedValueOnce([chunk()]);
+        const result = await service.carryForward({
+            runId: 'current-run-1',
+            connectionId: 'connection-1',
+            sourceKey: 'notion',
+        });
+        expect(result).toMatchObject({
+            considered: 1,
+            carriedForward: 1,
+            skippedNotReemitted: 0,
+            remappedEvidenceRefs: 1,
+            staleEvidenceRefs: 0,
+        });
+        expect(store.insertCandidate).toHaveBeenCalledWith(expect.objectContaining({
+            runId: 'current-run-1',
+            connectionId: 'connection-1',
+            sourceKey: 'notion',
+            candidateKey: 'budget-revenue-policy',
+            evidenceChunkIds: ['current-chunk-1'],
+            evidenceRefs: [
+                expect.objectContaining({
+                    chunkId: 'current-chunk-1',
+                    stableCitationKey: 'notion:page-1:revenue-policy',
+                    syncId: 'sync-current',
+                    snippetHash: createHash('sha256')
+                        .update('Booked revenue excludes refunds and test accounts.')
+                        .digest('hex'),
+                }),
+            ],
+            status: 'pending',
+            rejectionReason: null,
+            lane: 'full',
+            embedding: null,
+        }));
+        expect(result.warnings).toEqual(['Re-examined 1 prior budget-exhausted context candidate.']);
+    });
+    it('skips stale prior candidates when config requires current evidence re-emission', async () => {
+        const { service, store } = buildHarness(false);
+        store.listBudgetExhaustedCandidatesForCarryForward.mockResolvedValueOnce([candidate()]);
+        store.listCurrentRunEvidenceChunksForCarryForward.mockResolvedValueOnce([]);
+        const result = await service.carryForward({
+            runId: 'current-run-1',
+            connectionId: 'connection-1',
+            sourceKey: 'notion',
+        });
+        expect(result).toMatchObject({
+            considered: 1,
+            carriedForward: 0,
+            skippedNotReemitted: 1,
+            remappedEvidenceRefs: 0,
+            staleEvidenceRefs: 0,
+        });
+        expect(store.insertCandidate).not.toHaveBeenCalled();
+        expect(result.warnings).toEqual([
+            'Skipped 1 budget-exhausted context candidate because its evidence was not re-emitted in this run.',
+        ]);
+    });
+    it('carries stale prior evidence when reExamineBudgetExhaustedOnRerun is enabled', async () => {
+        const { service, store } = buildHarness(true);
+        store.listBudgetExhaustedCandidatesForCarryForward.mockResolvedValueOnce([candidate()]);
+        store.listCurrentRunEvidenceChunksForCarryForward.mockResolvedValueOnce([]);
+        const result = await service.carryForward({
+            runId: 'current-run-1',
+            connectionId: 'connection-1',
+            sourceKey: 'notion',
+        });
+        expect(result).toMatchObject({
+            considered: 1,
+            carriedForward: 1,
+            skippedNotReemitted: 0,
+            remappedEvidenceRefs: 0,
+            staleEvidenceRefs: 1,
+        });
+        expect(store.insertCandidate).toHaveBeenCalledWith(expect.objectContaining({
+            runId: 'current-run-1',
+            evidenceChunkIds: ['prior-chunk-1'],
+            evidenceRefs: [
+                {
+                    chunkId: 'prior-chunk-1',
+                    stableCitationKey: 'notion:page-1:revenue-policy',
+                    syncId: 'sync-prior',
+                    rawPath: 'pages/page-1/page.md',
+                },
+            ],
+        }));
+        expect(result.warnings).toEqual([
+            'Re-examined 1 prior budget-exhausted context candidate.',
+            'Carried 1 budget-exhausted evidence ref without a current-run chunk remap.',
+        ]);
+    });
+});

package/node_modules/@ktx/context/dist/ingest/context-candidates/curator-pagination.service.d.ts

@@ -0,0 +1,65 @@
+import type { KtxModelRole } from '@ktx/llm';
+import type { ToolSet } from 'ai';
+import type { AgentRunnerService } from '../../agent/index.js';
+import { type KtxLogger } from '../../core/index.js';
+import type { MemoryAction } from '../../memory/index.js';
+import type { ContextCandidateForDedup, CuratorPaginationPort, CuratorPaginationReport } from '../ports.js';
+import type { ReconcileCandidateForPrompt, ReconcileCandidateSummary, ReconcilePromptRunState } from '../stages/build-reconcile-context.js';
+import { type ReconciliationOutcome } from '../stages/stage-4-reconciliation.js';
+import type { StageIndex } from '../stages/stage-index.types.js';
+import type { EvictionUnit } from '../types.js';
+import type { ContextCandidateStorePort } from './store.js';
+import type { CuratorPaginationSettings } from './types.js';
+interface CuratorPaginationBudget {
+    creates: number;
+    updates: number;
+}
+interface CuratorPaginationPromptInput {
+    summary: ReconcileCandidateSummary;
+    items: ReconcileCandidateForPrompt[];
+    runState: ReconcilePromptRunState;
+}
+export interface CuratorPaginationInput {
+    runId: string;
+    sourceKey: string;
+    jobId: string;
+    stageIndex: StageIndex;
+    evictionUnit: EvictionUnit | undefined;
+    representatives: ContextCandidateForDedup[];
+    initialBudget: CuratorPaginationBudget;
+    modelRole: KtxModelRole;
+    buildSystemPrompt: () => string;
+    buildUserPrompt: (input: CuratorPaginationPromptInput) => string;
+    buildToolSet: (passNumber: number) => ToolSet;
+    getReconciliationActions: () => MemoryAction[];
+    onStepFinish?: (info: {
+        passNumber: number;
+        stepIndex: number;
+        stepBudget: number;
+    }) => void;
+}
+interface CuratorPaginationResult extends ReconciliationOutcome {
+    report: CuratorPaginationReport;
+    warnings: string[];
+}
+export interface CuratorPaginationServiceDeps {
+    store: ContextCandidateStorePort;
+    agentRunner: AgentRunnerService;
+    settings: CuratorPaginationSettings;
+    logger?: KtxLogger;
+}
+export declare class CuratorPaginationService implements CuratorPaginationPort {
+    private readonly deps;
+    private readonly logger;
+    constructor(deps: CuratorPaginationServiceDeps);
+    reconcile(input: CuratorPaginationInput): Promise<CuratorPaginationResult>;
+    private runPass;
+    private batchSummary;
+    private hasNonCandidateReconcileWork;
+    private consumeBudget;
+    private toWikiRefs;
+    private reportFromVerdicts;
+    private emptyReport;
+    private result;
+}
+export {};

package/node_modules/@ktx/context/dist/ingest/context-candidates/curator-pagination.service.js

@@ -0,0 +1,240 @@
+import { noopLogger } from '../../core/index.js';
+import { runReconciliationStage4 } from '../stages/stage-4-reconciliation.js';
+export class CuratorPaginationService {
+    deps;
+    logger;
+    constructor(deps) {
+        this.deps = deps;
+        this.logger = deps.logger ?? noopLogger;
+    }
+    async reconcile(input) {
+        const config = this.deps.settings;
+        const representatives = [...input.representatives];
+        const allCandidateKeys = representatives.map((candidate) => candidate.candidateKey);
+        const budget = {
+            creates: Math.max(0, input.initialBudget.creates),
+            updates: Math.max(0, input.initialBudget.updates),
+        };
+        const previouslyPromotedInRun = [];
+        const warnings = [];
+        let passNumber = 0;
+        let topicsExamined = 0;
+        let budgetExhausted = budget.creates === 0 && budget.updates === 0;
+        let stopReason;
+        let error;
+        let actionCursor = input.getReconciliationActions().length;
+        if (representatives.length === 0 && !this.hasNonCandidateReconcileWork(input.stageIndex, input.evictionUnit)) {
+            return this.result({
+                skipped: true,
+                stopReason,
+                error,
+                report: this.emptyReport(),
+                warnings,
+            });
+        }
+        if (representatives.length === 0) {
+            passNumber = 1;
+            const outcome = await this.runPass({
+                input,
+                candidates: [],
+                passNumber,
+                maxPasses: config.maxPasses,
+                budget,
+                previouslyPromotedInRun,
+                forceRun: false,
+            });
+            stopReason = outcome.stopReason;
+            error = outcome.error;
+            return this.result({
+                skipped: outcome.skipped,
+                stopReason,
+                error,
+                report: this.emptyReport({ passesRun: outcome.skipped ? 0 : 1 }),
+                warnings,
+            });
+        }
+        const queue = [...representatives];
+        while (queue.length > 0 && passNumber < config.maxPasses) {
+            if (budget.creates === 0 && budget.updates === 0) {
+                budgetExhausted = true;
+                await this.deps.store.markPendingCandidatesByReason({
+                    runId: input.runId,
+                    candidateKeys: queue.map((candidate) => candidate.candidateKey),
+                    rejectionReason: 'exceeded_run_budget',
+                });
+                queue.length = 0;
+                break;
+            }
+            const batch = queue.splice(0, config.batchSize);
+            const batchKeys = batch.map((candidate) => candidate.candidateKey);
+            passNumber += 1;
+            topicsExamined += batch.length;
+            const outcome = await this.runPass({
+                input,
+                candidates: batch,
+                passNumber,
+                maxPasses: config.maxPasses,
+                budget,
+                previouslyPromotedInRun,
+                forceRun: true,
+            });
+            stopReason = outcome.stopReason;
+            error = outcome.error;
+            const actions = input.getReconciliationActions();
+            const newWikiActions = actions
+                .slice(actionCursor)
+                .filter((action) => action.target === 'wiki' && (action.type === 'created' || action.type === 'updated'));
+            actionCursor = actions.length;
+            this.consumeBudget(budget, newWikiActions);
+            previouslyPromotedInRun.push(...this.toWikiRefs(newWikiActions));
+            if (outcome.stopReason === 'error' || outcome.error) {
+                const message = `Curator pass ${passNumber} failed: ${outcome.error?.message ?? outcome.stopReason ?? 'unknown error'}`;
+                warnings.push(message);
+                this.logger.warn(message);
+                await this.deps.store.markPendingCandidatesByReason({
+                    runId: input.runId,
+                    candidateKeys: batchKeys,
+                    rejectionReason: 'curator_pass_error',
+                });
+                continue;
+            }
+            if (budget.creates === 0 && budget.updates === 0) {
+                budgetExhausted = true;
+                await this.deps.store.markPendingCandidatesByReason({
+                    runId: input.runId,
+                    candidateKeys: [...batchKeys, ...queue.map((candidate) => candidate.candidateKey)],
+                    rejectionReason: 'exceeded_run_budget',
+                });
+                queue.length = 0;
+                break;
+            }
+        }
+        if (queue.length > 0) {
+            await this.deps.store.markPendingCandidatesByReason({
+                runId: input.runId,
+                candidateKeys: queue.map((candidate) => candidate.candidateKey),
+                rejectionReason: 'exceeded_curator_passes',
+            });
+        }
+        await this.deps.store.markPendingCandidatesByReason({
+            runId: input.runId,
+            candidateKeys: allCandidateKeys,
+            rejectionReason: 'exceeded_curator_passes',
+        });
+        const verdicts = await this.deps.store.summarizeCandidateVerdicts(input.runId, allCandidateKeys);
+        const report = this.reportFromVerdicts({
+            passesRun: passNumber,
+            topicsExamined,
+            budgetExhausted,
+            verdicts,
+        });
+        this.logger.log(`Curator: ${report.passesRun} passes, ${report.topicsExamined} topics examined, ${report.topicsByVerdict.promoted} promoted`);
+        return this.result({
+            skipped: false,
+            stopReason,
+            error,
+            report,
+            warnings,
+        });
+    }
+    async runPass(params) {
+        const config = this.deps.settings;
+        const candidateKeys = params.candidates.map((candidate) => candidate.candidateKey);
+        const items = await this.deps.store.listCandidatesForPromptByKeys(params.input.runId, candidateKeys);
+        const summary = this.batchSummary(items);
+        return runReconciliationStage4({
+            stageIndex: params.input.stageIndex,
+            evictionUnit: params.input.evictionUnit,
+            agentRunner: this.deps.agentRunner,
+            buildSystemPrompt: () => params.input.buildSystemPrompt(),
+            buildUserPrompt: () => params.input.buildUserPrompt({
+                summary,
+                items,
+                runState: {
+                    passNumber: params.passNumber,
+                    maxPasses: params.maxPasses,
+                    budgetRemaining: { ...params.budget },
+                    previouslyPromotedInRun: [...params.previouslyPromotedInRun],
+                },
+            }),
+            buildToolSet: () => params.input.buildToolSet(params.passNumber),
+            modelRole: params.input.modelRole,
+            stepBudget: config.stepBudgetPerPass,
+            sourceKey: params.input.sourceKey,
+            jobId: params.input.jobId,
+            forceRun: params.forceRun,
+            onStepFinish: params.input.onStepFinish
+                ? ({ stepIndex, stepBudget }) => params.input.onStepFinish?.({ passNumber: params.passNumber, stepIndex, stepBudget })
+                : undefined,
+        });
+    }
+    batchSummary(items) {
+        return items.reduce((summary, item) => {
+            summary.total += 1;
+            if (item.status === 'pending') {
+                summary.pending += 1;
+            }
+            else if (item.status === 'promoted') {
+                summary.promoted += 1;
+            }
+            else if (item.status === 'merged') {
+                summary.merged += 1;
+            }
+            else if (item.status === 'rejected') {
+                summary.rejected += 1;
+            }
+            else if (item.status === 'conflict') {
+                summary.conflict += 1;
+            }
+            return summary;
+        }, { total: 0, pending: 0, promoted: 0, merged: 0, rejected: 0, conflict: 0 });
+    }
+    hasNonCandidateReconcileWork(stageIndex, evictionUnit) {
+        return stageIndex.workUnits.some((wu) => wu.actions.length > 0) || !!evictionUnit?.deletedRawPaths.length;
+    }
+    consumeBudget(budget, actions) {
+        const creates = actions.filter((action) => action.type === 'created').length;
+        const updates = actions.filter((action) => action.type === 'updated').length;
+        budget.creates = Math.max(0, budget.creates - creates);
+        budget.updates = Math.max(0, budget.updates - updates);
+    }
+    toWikiRefs(actions) {
+        return actions.map((action) => ({
+            pageKey: action.key,
+            action: action.type,
+            summary: action.detail,
+        }));
+    }
+    reportFromVerdicts(params) {
+        return {
+            passesRun: params.passesRun,
+            topicsExamined: params.topicsExamined,
+            topicsByVerdict: {
+                promoted: params.verdicts.promoted,
+                merged: params.verdicts.merged,
+                rejected: params.verdicts.rejected,
+                conflict: params.verdicts.conflict,
+            },
+            topicsRejectedByReason: params.verdicts.rejectedByReason,
+            budgetExhausted: params.budgetExhausted,
+        };
+    }
+    emptyReport(overrides = {}) {
+        return {
+            passesRun: 0,
+            topicsExamined: 0,
+            topicsByVerdict: {
+                promoted: 0,
+                merged: 0,
+                rejected: 0,
+                conflict: 0,
+            },
+            topicsRejectedByReason: {},
+            budgetExhausted: false,
+            ...overrides,
+        };
+    }
+    result(result) {
+        return result;
+    }
+}

package/node_modules/@ktx/context/dist/ingest/context-candidates/curator-pagination.service.test.d.ts

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

package/node_modules/@ktx/context/dist/ingest/context-candidates/curator-pagination.service.test.js

@@ -0,0 +1,168 @@
+import { describe, expect, it, vi } from 'vitest';
+import { CuratorPaginationService } from './curator-pagination.service.js';
+const candidate = (key, score) => ({
+    id: `id-${key}`,
+    candidateKey: key,
+    topic: `Topic ${key}`,
+    assertion: `Assertion ${key}`,
+    promotionScore: score,
+    createdAt: new Date(`2026-04-30T10:0${score % 10}:00.000Z`),
+    evidenceChunkIds: [`chunk-${key}`],
+    evidenceRefs: [{ stableCitationKey: `ref-${key}` }],
+    embedding: null,
+    lane: 'full',
+});
+const promptCandidate = (key, score) => ({
+    candidateKey: key,
+    topic: `Topic ${key}`,
+    assertion: `Assertion ${key}`,
+    rationale: `Rationale ${key}`,
+    actionHint: 'create',
+    status: 'pending',
+    promotionScore: score,
+    suggestedPageKey: `page-${key}`,
+    evidenceRefs: [{ stableCitationKey: `ref-${key}` }],
+});
+function makeHarness(overrides = {}) {
+    const store = {
+        listPendingCandidatesForDedup: vi.fn().mockResolvedValue([]),
+        updateCandidateEmbedding: vi.fn().mockResolvedValue(undefined),
+        markCandidatesAsMergedToCluster: vi.fn().mockResolvedValue(undefined),
+        listBudgetExhaustedCandidatesForCarryForward: vi.fn().mockResolvedValue([]),
+        listCurrentRunEvidenceChunksForCarryForward: vi.fn().mockResolvedValue([]),
+        insertCandidate: vi.fn().mockResolvedValue({ id: 'candidate-1' }),
+        listCandidatesForPromptByKeys: vi
+            .fn()
+            .mockImplementation((_runId, keys) => Promise.resolve(keys.map((key) => promptCandidate(key, Number(key.replace('c', '')) || 1)))),
+        markPendingCandidatesByReason: vi.fn().mockResolvedValue(0),
+        summarizeCandidateVerdicts: vi.fn().mockResolvedValue({
+            pending: 0,
+            promoted: 1,
+            merged: 1,
+            rejected: 1,
+            conflict: 0,
+            rejectedByReason: { exceeded_curator_passes: 1 },
+        }),
+    };
+    const agentRunner = {
+        runLoop: vi.fn().mockResolvedValue({ stopReason: 'natural' }),
+    };
+    const actions = [];
+    const prompts = [];
+    const service = new CuratorPaginationService({
+        store,
+        agentRunner: agentRunner,
+        settings: {
+            batchSize: overrides.batchSize ?? 2,
+            maxPasses: overrides.maxPasses ?? 2,
+            stepBudgetPerPass: overrides.stepBudgetPerPass ?? 7,
+        },
+    });
+    const input = (representatives = [candidate('c1', 10), candidate('c2', 9), candidate('c3', 8)]) => ({
+        runId: 'run-1',
+        sourceKey: 'notion',
+        jobId: 'job-1',
+        stageIndex: {
+            jobId: 'job-1',
+            connectionId: 'c1',
+            workUnits: [],
+            conflictsResolved: [],
+            evictionsApplied: [],
+            unmappedFallbacks: [],
+        },
+        evictionUnit: undefined,
+        representatives,
+        initialBudget: { creates: 2, updates: 1 },
+        modelRole: 'curator',
+        buildSystemPrompt: () => 'system prompt',
+        buildUserPrompt: ({ runState, items }) => {
+            const prompt = `pass=${runState.passNumber}; budget=${runState.budgetRemaining.creates}/${runState.budgetRemaining.updates}; items=${items.map((item) => item.candidateKey).join(',')}; previous=${runState.previouslyPromotedInRun
+                .map((page) => page.pageKey)
+                .join(',')}`;
+            prompts.push(prompt);
+            return prompt;
+        },
+        buildToolSet: () => ({}),
+        getReconciliationActions: () => actions,
+    });
+    return { store, agentRunner, actions, prompts, service, input };
+}
+describe('CuratorPaginationService', () => {
+    it('paginates representatives and carries budget plus previous wiki writes into later passes', async () => {
+        const harness = makeHarness({ batchSize: 2, maxPasses: 2, stepBudgetPerPass: 7 });
+        harness.agentRunner.runLoop.mockImplementation(() => {
+            if (harness.actions.length === 0) {
+                harness.actions.push({ target: 'wiki', type: 'created', key: 'page-c1', detail: 'Created C1' });
+            }
+            return { stopReason: 'natural' };
+        });
+        const result = await harness.service.reconcile(harness.input());
+        expect(harness.agentRunner.runLoop).toHaveBeenCalledTimes(2);
+        expect(harness.agentRunner.runLoop).toHaveBeenCalledWith(expect.objectContaining({ modelRole: 'curator' }));
+        expect(harness.prompts[0]).toContain('pass=1');
+        expect(harness.prompts[0]).toContain('budget=2/1');
+        expect(harness.prompts[0]).toContain('items=c1,c2');
+        expect(harness.prompts[1]).toContain('pass=2');
+        expect(harness.prompts[1]).toContain('budget=1/1');
+        expect(harness.prompts[1]).toContain('previous=page-c1');
+        expect(result.report).toMatchObject({
+            passesRun: 2,
+            topicsExamined: 3,
+            topicsByVerdict: { promoted: 1, merged: 1, rejected: 1, conflict: 0 },
+            topicsRejectedByReason: { exceeded_curator_passes: 1 },
+            budgetExhausted: false,
+        });
+    });
+    it('marks unprocessed representatives when maxPasses is exhausted', async () => {
+        const harness = makeHarness({ batchSize: 1, maxPasses: 1 });
+        await harness.service.reconcile(harness.input([candidate('c1', 10), candidate('c2', 9)]));
+        expect(harness.store.markPendingCandidatesByReason).toHaveBeenCalledWith({
+            runId: 'run-1',
+            candidateKeys: ['c2'],
+            rejectionReason: 'exceeded_curator_passes',
+        });
+        expect(harness.store.markPendingCandidatesByReason).toHaveBeenCalledWith({
+            runId: 'run-1',
+            candidateKeys: ['c1', 'c2'],
+            rejectionReason: 'exceeded_curator_passes',
+        });
+    });
+    it('marks remaining pending representatives when run budget is exhausted', async () => {
+        const harness = makeHarness({ batchSize: 1, maxPasses: 5 });
+        const input = harness.input([candidate('c1', 10), candidate('c2', 9), candidate('c3', 8)]);
+        input.initialBudget = { creates: 1, updates: 0 };
+        harness.agentRunner.runLoop.mockImplementation(() => {
+            harness.actions.push({ target: 'wiki', type: 'created', key: 'page-c1', detail: 'Created C1' });
+            return { stopReason: 'natural' };
+        });
+        const result = await harness.service.reconcile(input);
+        expect(harness.agentRunner.runLoop).toHaveBeenCalledTimes(1);
+        expect(harness.store.markPendingCandidatesByReason).toHaveBeenCalledWith({
+            runId: 'run-1',
+            candidateKeys: ['c1', 'c2', 'c3'],
+            rejectionReason: 'exceeded_run_budget',
+        });
+        expect(result.report.budgetExhausted).toBe(true);
+    });
+    it('marks a failed pass with curator_pass_error and continues to later batches', async () => {
+        const harness = makeHarness({ batchSize: 1, maxPasses: 3 });
+        harness.agentRunner.runLoop
+            .mockResolvedValueOnce({ stopReason: 'error', error: new Error('provider timeout') })
+            .mockResolvedValue({ stopReason: 'natural' });
+        const result = await harness.service.reconcile(harness.input([candidate('c1', 10), candidate('c2', 9)]));
+        expect(harness.agentRunner.runLoop).toHaveBeenCalledTimes(2);
+        expect(harness.store.markPendingCandidatesByReason).toHaveBeenCalledWith({
+            runId: 'run-1',
+            candidateKeys: ['c1'],
+            rejectionReason: 'curator_pass_error',
+        });
+        expect(result.warnings).toContain('Curator pass 1 failed: provider timeout');
+    });
+    it('skips when there are no representatives and no reconciliation work', async () => {
+        const harness = makeHarness();
+        const result = await harness.service.reconcile(harness.input([]));
+        expect(result.skipped).toBe(true);
+        expect(harness.agentRunner.runLoop).not.toHaveBeenCalled();
+        expect(result.report.topicsExamined).toBe(0);
+    });
+});

package/node_modules/@ktx/context/dist/ingest/context-candidates/embedding-text.d.ts

@@ -0,0 +1,6 @@
+interface ContextCandidateEmbeddingTextInput {
+    topic: string;
+    assertion: string;
+}
+export declare function buildContextCandidateEmbeddingText(input: ContextCandidateEmbeddingTextInput): string;
+export {};

package/node_modules/@ktx/context/dist/ingest/context-candidates/embedding-text.js

@@ -0,0 +1,3 @@
+export function buildContextCandidateEmbeddingText(input) {
+    return `${input.topic} - ${input.assertion}`;
+}

package/node_modules/@ktx/context/dist/ingest/context-candidates/embedding-text.test.d.ts

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

package/node_modules/@ktx/context/dist/ingest/context-candidates/embedding-text.test.js

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest';
+import { buildContextCandidateEmbeddingText } from './embedding-text.js';
+describe('buildContextCandidateEmbeddingText', () => {
+    it('matches the existing dedup embedding input format', () => {
+        expect(buildContextCandidateEmbeddingText({
+            topic: 'Revenue Recognition',
+            assertion: 'Booked revenue excludes refunds and test accounts.',
+        })).toBe('Revenue Recognition - Booked revenue excludes refunds and test accounts.');
+    });
+});

package/node_modules/@ktx/context/dist/ingest/context-candidates/index.d.ts

@@ -0,0 +1,9 @@
+export type { CandidateDedupServiceDeps } from './candidate-dedup.service.js';
+export { CandidateDedupService } from './candidate-dedup.service.js';
+export type { ContextCandidateCarryforwardArgs, ContextCandidateCarryforwardResult, ContextCandidateCarryforwardServiceDeps, } from './context-candidate-carryforward.service.js';
+export { ContextCandidateCarryforwardService } from './context-candidate-carryforward.service.js';
+export type { CuratorPaginationInput, CuratorPaginationServiceDeps } from './curator-pagination.service.js';
+export { CuratorPaginationService } from './curator-pagination.service.js';
+export { buildContextCandidateEmbeddingText } from './embedding-text.js';
+export type { ContextCandidateStorePort } from './store.js';
+export type { BudgetExhaustedCandidateForCarryForward, CandidateDedupSettings, ContextCandidateActionHint, ContextCandidateCarryforwardSettings, ContextCandidateEmbeddingPort, ContextCandidateForPrompt, ContextCandidateLane, ContextCandidateRejectionReason, ContextCandidateScoreAggregation, ContextCandidateStatus, ContextCandidateVerdictSummary, CuratorPaginationSettings, CurrentRunEvidenceChunkForCarryForward, InsertContextCandidateInput, MarkContextCandidateClusterInput, } from './types.js';