@kaelio/ktx 0.1.0-rc.6 → 0.1.0

package/dist/setup-runtime.test.js

@@ -36,27 +36,22 @@ describe('runKtxSetupRuntimeStep', () => {
     afterEach(async () => {
         await rm(tempDir, { recursive: true, force: true });
     });
-    it('ensures core runtime for agent setup and records the runtime step', async () => {
+    it('skips runtime setup when the project has no direct runtime requirements', async () => {
         const io = makeIo();
-        const ensureRuntime = vi.fn(async () => ({}));
+        const ensureRuntime = vi.fn();
         await expect(runKtxSetupRuntimeStep({
             projectDir: tempDir,
             inputMode: 'auto',
             cliVersion: '0.2.0',
             runtimeInstallPolicy: 'prompt',
-            agents: true,
         }, io.io, {
             loadProject: projectConfig(buildDefaultKtxProjectConfig()),
             ensureRuntime,
             env: {},
-        })).resolves.toMatchObject({ status: 'ready' });
-        expect(ensureRuntime).toHaveBeenCalledWith(expect.objectContaining({
-            cliVersion: '0.2.0',
-            installPolicy: 'prompt',
-            feature: 'core',
-        }));
-        expect((await readKtxSetupState(tempDir)).completed_steps).toContain('runtime');
-        expect(io.stdout()).toContain('Runtime ready: yes (core)');
+        })).resolves.toMatchObject({ status: 'skipped' });
+        expect(ensureRuntime).not.toHaveBeenCalled();
+        expect((await readKtxSetupState(tempDir)).completed_steps).not.toContain('runtime');
+        expect(io.stdout()).toContain('Runtime setup skipped.');
     });
     it('fails fast when required runtime features cannot be installed in no-input mode', async () => {
         const io = makeIo();
@@ -68,7 +63,7 @@ describe('runKtxSetupRuntimeStep', () => {
             inputMode: 'disabled',
             cliVersion: '0.2.0',
             runtimeInstallPolicy: 'never',
-            agents: true,
+            databaseIntrospectionFallback: true,
         }, io.io, {
             loadProject: projectConfig(buildDefaultKtxProjectConfig()),
             ensureRuntime,
@@ -101,7 +96,6 @@ describe('runKtxSetupRuntimeStep', () => {
             inputMode: 'auto',
             cliVersion: '0.2.0',
             runtimeInstallPolicy: 'auto',
-            agents: false,
         }, io.io, {
             loadProject: projectConfig(config),
             ensureLocalEmbeddings,

package/dist/setup.d.ts

@@ -143,4 +143,7 @@ export interface ReadKtxSetupStatusOptions {
 }
 export declare function readKtxSetupStatus(projectDir: string, options?: ReadKtxSetupStatusOptions): Promise<KtxSetupStatus>;
 export declare function formatKtxSetupStatus(status: KtxSetupStatus): string;
+export declare function formatKtxSetupCompletionSummary(status: KtxSetupStatus, options?: {
+    agentNextActions?: string;
+}): string;
 export declare function runKtxSetup(args: KtxSetupArgs, io: KtxCliIo, deps?: KtxSetupDeps): Promise<number>;

package/dist/setup.js

@@ -7,7 +7,7 @@ import { runtimeInstallPolicyFromFlags } from './managed-python-command.js';
 import { readManagedPythonRuntimeStatus } from './managed-python-runtime.js';
 import { resolveProjectRuntimeRequirements } from './runtime-requirements.js';
 import { isKtxSetupExitError } from './setup-interrupt.js';
-import { readKtxAgentInstallManifest, runKtxSetupAgentsStep, } from './setup-agents.js';
+import { readKtxAgentInstallManifest, runKtxSetupAgentsStep, targetDisplayName, } from './setup-agents.js';
 import { runKtxSetupDatabasesStep, } from './setup-databases.js';
 import { runKtxSetupEmbeddingsStep } from './setup-embeddings.js';
 import { isKtxSetupLlmConfigReady, runKtxSetupAnthropicModelStep, } from './setup-models.js';
@@ -136,7 +136,6 @@ export async function readKtxSetupStatus(projectDir, options = {}) {
     }
     const agents = [...agentMap.values()];
     const runtimeRequirements = resolveProjectRuntimeRequirements(project.config, {
-        agents: agents.length > 0,
         env: options.env ?? process.env,
     });
     let runtimeReady = runtimeRequirements.features.length === 0 || completedSteps.includes('runtime');
@@ -219,6 +218,26 @@ export function formatKtxSetupStatus(status) {
     }
     return `${lines.join('\n')}\n`;
 }
+export function formatKtxSetupCompletionSummary(status, options = {}) {
+    const readyAgents = status.agents.filter((agent) => agent.ready).map((agent) => targetDisplayName(agent.target));
+    const lines = [
+        'Project',
+        `  ${status.project.path}`,
+        '',
+        'Context',
+        `  ${status.context.ready ? 'built' : formatContextBuilt(status.context)}`,
+        '',
+        'Agents configured',
+        `  ${readyAgents.length > 0 ? readyAgents.join(', ') : 'not installed'}`,
+    ];
+    const agentNextActions = options.agentNextActions?.trim();
+    if (agentNextActions) {
+        lines.push('', 'REQUIRED BEFORE USING AGENTS', '', ...agentNextActions.split('\n').map((line) => (line ? `  ${line}` : '')));
+    }
+    lines.push('', agentNextActions ? 'After that, try' : 'Try it');
+    lines.push('  Ask your agent: "Use KTX to show me the available tables."');
+    return lines.join('\n');
+}
 function setupStatusReady(status) {
     if (!status.project.ready) {
         return false;
@@ -238,10 +257,8 @@ function setupHasContextTargets(status) {
 function setupContextReady(status) {
     return status.context.ready;
 }
-function writeContextNotReadyForAgents(projectDir, io) {
-    io.stderr.write('KTX context is not ready for agents.\n\n');
-    io.stderr.write(`Build context first:\n  ktx setup --project-dir ${resolve(projectDir)}\n\n`);
-    io.stderr.write(`Then install agent integration:\n  ktx setup --agents --project-dir ${resolve(projectDir)}\n`);
+function shouldPrintConciseReadySummary(status) {
+    return setupStatusReady(status) && setupContextReady(status) && status.agents.some((agent) => agent.ready);
 }
 function setupRuntimeInstallPolicy(args) {
     if (args.yes) {
@@ -269,6 +286,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
     setupUi.intro('KTX setup', io);
     let entryAction;
     let projectResult;
+    let agentNextActions;
     const canShowEntryMenu = args.showEntryMenu === true &&
         args.inputMode !== 'disabled' &&
         !args.agents &&
@@ -318,16 +336,17 @@ async function runKtxSetupInner(args, io, deps = {}) {
             }
         }
         const runOnly = readyAction;
+        const agentOnlySetup = agentsRequested || runOnly === 'agents';
         const shouldRunModels = !runOnly || runOnly === 'models';
         const shouldRunEmbeddings = !runOnly || runOnly === 'embeddings';
         const shouldRunDatabases = !runOnly || runOnly === 'databases';
         const shouldRunSources = !runOnly || runOnly === 'sources';
-        const shouldRunRuntime = agentsRequested || !runOnly || runOnly === 'runtime' || runOnly === 'context' || runOnly === 'agents';
-        const shouldRunContext = agentsRequested || !runOnly || runOnly === 'context';
+        const shouldRunRuntime = !agentOnlySetup && (!runOnly || runOnly === 'runtime' || runOnly === 'context');
+        const shouldRunContext = !agentOnlySetup && (!runOnly || runOnly === 'context');
         const shouldRunAgents = agentsRequested || !runOnly || runOnly === 'agents';
         const showPromptInstructions = projectResult.confirmedCreation !== true;
-        const setupSteps = agentsRequested
-            ? ['runtime', 'context']
+        const setupSteps = agentOnlySetup
+            ? []
             : ['models', 'embeddings', 'databases', 'sources', 'runtime', 'context'];
         if (shouldRunAgents && args.skipAgents !== true) {
             setupSteps.push('agents');
@@ -456,7 +475,6 @@ async function runKtxSetupInner(args, io, deps = {}) {
                     inputMode: args.inputMode,
                     cliVersion: args.cliVersion,
                     runtimeInstallPolicy: setupRuntimeInstallPolicy(args),
-                    agents: shouldRunAgents && args.skipAgents !== true,
                 }, io);
             }
             else if (step === 'context') {
@@ -473,7 +491,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
             }
             else {
                 const agentsRunner = deps.agents ?? ((agentArgs, agentIo) => runKtxSetupAgentsStep(agentArgs, agentIo, deps.agentsDeps));
-                stepResult = await agentsRunner({
+                const agentResult = await agentsRunner({
                     projectDir: projectResult.projectDir,
                     inputMode: args.inputMode,
                     yes: args.yes,
@@ -482,7 +500,12 @@ async function runKtxSetupInner(args, io, deps = {}) {
                     scope: args.agentScope ?? 'project',
                     mode: 'mcp',
                     skipAgents: false,
+                    showNextActions: agentsRequested,
                 }, io);
+                stepResult = agentResult;
+                if (agentResult.status === 'ready') {
+                    agentNextActions = agentResult.nextActions;
+                }
             }
             if (stepResult.status === 'failed' || stepResult.status === 'missing-input') {
                 return 1;
@@ -504,10 +527,6 @@ async function runKtxSetupInner(args, io, deps = {}) {
             }
             if (step === 'context' && stepResult.status !== 'ready') {
                 if (shouldRunAgents && args.skipAgents !== true) {
-                    if (agentsRequested) {
-                        writeContextNotReadyForAgents(projectResult.projectDir, io);
-                        return args.inputMode === 'disabled' ? 1 : 0;
-                    }
                     return 0;
                 }
             }
@@ -520,15 +539,22 @@ async function runKtxSetupInner(args, io, deps = {}) {
     const status = await readKtxSetupStatus(projectResult.projectDir, { cliVersion: args.cliVersion });
     const focusedOnAgents = args.agents || entryAction === 'agents';
     if (!focusedOnAgents) {
-        setupUi.note(formatKtxSetupStatus(status).trimEnd(), 'Project status', io, {
-            format: (line) => line,
-        });
-        setupUi.note(formatSetupNextStepLines({
-            setupReady: setupStatusReady(status),
-            hasContextTargets: setupHasContextTargets(status),
-            contextReady: setupContextReady(status),
-            agentIntegrationReady: status.agents.some((agent) => agent.ready),
-        }).join('\n'), 'What you can do next', io);
+        if (shouldPrintConciseReadySummary(status)) {
+            setupUi.note(formatKtxSetupCompletionSummary(status, { agentNextActions }), agentNextActions ? 'Finish KTX agent setup' : 'KTX project ready', io, {
+                format: (line) => line,
+            });
+        }
+        else {
+            setupUi.note(formatKtxSetupStatus(status).trimEnd(), 'Project status', io, {
+                format: (line) => line,
+            });
+            setupUi.note(formatSetupNextStepLines({
+                setupReady: setupStatusReady(status),
+                hasContextTargets: setupHasContextTargets(status),
+                contextReady: setupContextReady(status),
+                agentIntegrationReady: status.agents.some((agent) => agent.ready),
+            }).join('\n'), 'What you can do next', io);
+        }
     }
     return 0;
 }

package/dist/setup.test.js

@@ -8,7 +8,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { localFakeBundleReport, persistLocalBundleReport } from './ingest.test-utils.js';
 import { contextBuildCommands, writeKtxSetupContextState } from './setup-context.js';
 import { runDemoTour } from './setup-demo-tour.js';
-import { formatKtxSetupStatus, readKtxSetupStatus, runKtxSetup } from './setup.js';
+import { formatKtxSetupCompletionSummary, formatKtxSetupStatus, readKtxSetupStatus, runKtxSetup } from './setup.js';
 vi.mock('./setup-demo-tour.js', () => ({
     runDemoTour: vi.fn(async () => 0),
 }));
@@ -337,6 +337,98 @@ describe('setup status', () => {
         expect(rendered).toContain('KTX context built: no');
         expect(rendered).not.toContain('No KTX project found.');
     });
+    it('formats a concise ready summary for completed agent setup', () => {
+        const rendered = formatKtxSetupCompletionSummary({
+            project: { path: tempDir, ready: true },
+            llm: { ready: true, model: 'sonnet' },
+            embeddings: { ready: true, model: 'text-embedding-3-small' },
+            databases: [{ connectionId: 'postgres-warehouse', ready: true }],
+            sources: [{ connectionId: 'dbt-main', type: 'dbt', ready: true }],
+            runtime: { required: true, ready: true, features: ['core'] },
+            context: { ready: true, status: 'completed' },
+            agents: [
+                { target: 'claude-code', scope: 'project', ready: true },
+                { target: 'claude-desktop', scope: 'global', ready: true },
+            ],
+        }, {
+            agentNextActions: [
+                '1. Start MCP',
+                '  Run this command before using Claude Code:',
+                '',
+                '  RUN:',
+                `  ktx mcp start --project-dir ${tempDir}`,
+                '',
+                '  If you need to stop MCP later:',
+                `  ktx mcp stop --project-dir ${tempDir}`,
+                '',
+                '2. Open Claude Code',
+                '  Open Claude Code from the KTX project directory:',
+                '',
+                '  RUN:',
+                `  cd '${tempDir}'`,
+                '  claude',
+            ].join('\n'),
+        });
+        expect(rendered).toContain(`Project\n  ${tempDir}`);
+        expect(rendered).toContain('Context\n  built');
+        expect(rendered).toContain('Agents configured\n  Claude Code, Claude Desktop');
+        expect(rendered).toContain('REQUIRED BEFORE USING AGENTS\n\n  1. Start MCP');
+        expect(rendered).toContain('    Run this command before using Claude Code:');
+        expect(rendered).toContain('    RUN:');
+        expect(rendered).toContain('    If you need to stop MCP later:');
+        expect(rendered).toContain(`ktx mcp stop --project-dir ${tempDir}`);
+        expect(rendered).toContain('After that, try\n  Ask your agent: "Use KTX to show me the available tables."');
+        expect(rendered).not.toContain('Verify');
+        expect(rendered).not.toContain('Project ready: yes');
+        expect(rendered).not.toContain('What you can do next');
+    });
+    it('prints agent next actions inside the final ready summary during full setup', async () => {
+        const testIo = makeIo();
+        await expect(runKtxSetup({
+            command: 'run',
+            projectDir: tempDir,
+            mode: 'new',
+            agents: false,
+            target: 'claude-code',
+            skipAgents: false,
+            inputMode: 'disabled',
+            yes: true,
+            cliVersion: '0.2.0',
+            skipLlm: true,
+            skipEmbeddings: true,
+            skipDatabases: true,
+            skipSources: true,
+            databaseSchemas: [],
+        }, testIo.io, {
+            runtime: async () => runtimeReady(tempDir),
+            context: async () => {
+                await writeKtxSetupContextState(tempDir, {
+                    runId: 'setup-context-local-test',
+                    status: 'completed',
+                    primarySourceConnectionIds: [],
+                    contextSourceConnectionIds: [],
+                    reportIds: [],
+                    artifactPaths: [],
+                    retryableFailedTargets: [],
+                    commands: contextBuildCommands(tempDir, 'setup-context-local-test'),
+                });
+                await writeKtxSetupState(tempDir, { completed_steps: ['project', 'context'] });
+                return { status: 'ready', projectDir: tempDir, runId: 'setup-context-local-test' };
+            },
+        })).resolves.toBe(0);
+        const output = testIo.stdout();
+        expect(output).toContain('Claude Code · Project scope');
+        expect(output).toContain(join(tempDir, '.mcp.json'));
+        expect(output).toContain('Requires MCP to be started.');
+        expect(output).toContain('Analytics skill installed.');
+        expect(output).not.toContain('Agent integration complete');
+        expect(output).toContain('Finish KTX agent setup');
+        expect(output).not.toContain('KTX project ready');
+        expect(output).toContain('REQUIRED BEFORE USING AGENTS');
+        expect(output).toContain('Run this command before using Claude Code:');
+        expect(output).toContain(`ktx mcp start --project-dir ${tempDir}`);
+        expect(output).not.toContain('Finish agent setup');
+    });
     it('prints the setup shell intro for auto-created run mode', async () => {
         const testIo = makeIo();
         await expect(runKtxSetup({
@@ -1257,7 +1349,7 @@ describe('setup status', () => {
         const committedConfig = await execFileAsync('git', ['-C', tempDir, 'show', 'HEAD:ktx.yaml']);
         expect(committedConfig.stdout).toContain('warehouse:');
     });
-    it('runs agent setup after context succeeds in --agents mode', async () => {
+    it('runs agent setup without runtime or context in --agents mode', async () => {
         const calls = [];
         const io = makeIo();
         await writeFile(join(tempDir, 'ktx.yaml'), ['connections: {}', ''].join('\n'), 'utf-8');
@@ -1284,11 +1376,11 @@ describe('setup status', () => {
             sources: async () => ({ status: 'skipped', projectDir: tempDir }),
             runtime: async () => {
                 calls.push('runtime');
-                return runtimeReady(tempDir);
+                throw new Error('runtime should not run');
             },
             context: async () => {
                 calls.push('context');
-                return { status: 'ready', projectDir: tempDir, runId: 'setup-context-local-test' };
+                throw new Error('context should not run');
             },
             agents: async () => {
                 calls.push('agents');
@@ -1299,10 +1391,12 @@ describe('setup status', () => {
                 };
             },
         })).resolves.toBe(0);
-        expect(calls).toEqual(['runtime', 'context', 'agents']);
+        expect(calls).toEqual(['agents']);
     });
-    it('does not install agents when non-interactive --agents finds context incomplete', async () => {
+    it('installs agents when non-interactive --agents finds context incomplete', async () => {
         const io = makeIo();
+        const runtime = vi.fn(async () => runtimeReady(tempDir));
+        const context = vi.fn(async () => ({ status: 'skipped', projectDir: tempDir }));
         const agents = vi.fn(async () => ({
             status: 'ready',
             projectDir: tempDir,
@@ -1326,12 +1420,14 @@ describe('setup status', () => {
             skipAgents: false,
             databaseSchemas: [],
         }, io.io, {
-            runtime: async () => runtimeReady(tempDir),
-            context: async () => ({ status: 'skipped', projectDir: tempDir }),
+            runtime,
+            context,
             agents,
-        })).resolves.toBe(1);
-        expect(agents).not.toHaveBeenCalled();
-        expect(io.stderr()).toContain('KTX context is not ready for agents.');
+        })).resolves.toBe(0);
+        expect(runtime).not.toHaveBeenCalled();
+        expect(context).not.toHaveBeenCalled();
+        expect(agents).toHaveBeenCalledTimes(1);
+        expect(io.stderr()).not.toContain('KTX context is not ready for agents.');
     });
     it('routes a ready project menu selection to agent setup', async () => {
         const calls = [];
@@ -1433,7 +1529,7 @@ describe('setup status', () => {
                 process.env.KTX_RUNTIME_ROOT = previousRuntimeRoot;
             }
         }
-        expect(calls).toEqual(['runtime', 'agents']);
+        expect(calls).toEqual(['agents']);
     });
     it('skips to agent setup when context is ready but agents are not configured', async () => {
         const calls = [];
@@ -1517,9 +1613,9 @@ describe('setup status', () => {
             },
         })).resolves.toBe(0);
         expect(readyMenuSelect).not.toHaveBeenCalled();
-        expect(calls).toEqual(['runtime', 'agents']);
+        expect(calls).toEqual(['agents']);
     });
-    it('runs only project resolution, runtime, context gate, and agent setup in --agents mode', async () => {
+    it('runs only project resolution and agent setup in --agents mode', async () => {
         const io = makeIo();
         const runtime = vi.fn(async () => runtimeReady(tempDir));
         const context = vi.fn(async () => ({ status: 'ready', projectDir: tempDir, runId: 'setup-context-local-test' }));
@@ -1552,8 +1648,8 @@ describe('setup status', () => {
             context,
             agents,
         })).resolves.toBe(0);
-        expect(runtime).toHaveBeenCalledTimes(1);
-        expect(context).toHaveBeenCalledTimes(1);
+        expect(runtime).not.toHaveBeenCalled();
+        expect(context).not.toHaveBeenCalled();
         expect(agents).toHaveBeenCalledTimes(1);
     });
     it('does not run embedding setup when the model step fails', async () => {

package/node_modules/@ktx/connector-clickhouse/dist/package-exports.test.js

@@ -6,5 +6,5 @@ describe('@ktx/connector-clickhouse package exports', () => {
         expect(connector.KtxClickHouseScanConnector).toBeTypeOf('function');
         expect(connector.clickHouseClientConfigFromConfig).toBeTypeOf('function');
         expect(connector.createClickHouseLiveDatabaseIntrospection).toBeTypeOf('function');
-    });
+    }, 20_000);
 });

package/node_modules/@ktx/context/dist/core/git.service.d.ts

@@ -101,7 +101,6 @@ export declare class GitService {
         status: 'A' | 'M' | 'D';
         path: string;
     }>>;
-    changedPaths(): Promise<string[]>;
     /**
      * List all paths under the working tree that match `pathSpec`, scoped to HEAD.
      * Used for the reconciler's first-ever run when there's no watermark to diff from.

package/node_modules/@ktx/context/dist/core/git.service.js

@@ -424,18 +424,6 @@ export class GitService {
         }
         return out;
     }
-    async changedPaths() {
-        const raw = await this.git.raw(['status', '--porcelain=v1', '-z']);
-        const fields = raw.split('\0').filter(Boolean);
-        const paths = [];
-        for (const field of fields) {
-            const path = field.slice(3);
-            if (path.length > 0) {
-                paths.push(path);
-            }
-        }
-        return [...new Set(paths)].sort();
-    }
     /**
      * List all paths under the working tree that match `pathSpec`, scoped to HEAD.
      * Used for the reconciler's first-ever run when there's no watermark to diff from.

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/historic-sql.adapter.d.ts

@@ -1,4 +1,4 @@
-import type { ChunkResult, DeterministicFinalizationContext, DiffSet, FetchContext, FinalizationResult, ScopeDescriptor, SourceAdapter } from '../../types.js';
+import type { ChunkResult, DiffSet, FetchContext, ScopeDescriptor, SourceAdapter } from '../../types.js';
 import { type HistoricSqlSourceAdapterDeps } from './types.js';
 export declare class HistoricSqlSourceAdapter implements SourceAdapter {
     private readonly deps;
@@ -11,5 +11,4 @@ export declare class HistoricSqlSourceAdapter implements SourceAdapter {
     fetch(pullConfig: unknown, stagedDir: string, ctx: FetchContext): Promise<void>;
     chunk(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
     describeScope(stagedDir: string): Promise<ScopeDescriptor>;
-    finalize(ctx: DeterministicFinalizationContext): Promise<FinalizationResult>;
 }

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/historic-sql.adapter.js

@@ -1,6 +1,5 @@
 import { chunkHistoricSqlUnifiedStagedDir, describeHistoricSqlUnifiedScope } from './chunk-unified.js';
 import { detectHistoricSqlStagedDir } from './detect.js';
-import { projectHistoricSqlEvidence } from './projection.js';
 import { stageHistoricSqlAggregatedSnapshot } from './stage-unified.js';
 export class HistoricSqlSourceAdapter {
     deps;
@@ -31,21 +30,4 @@ export class HistoricSqlSourceAdapter {
     describeScope(stagedDir) {
         return describeHistoricSqlUnifiedScope(stagedDir);
     }
-    async finalize(ctx) {
-        const projection = await projectHistoricSqlEvidence({
-            workdir: ctx.workdir,
-            connectionId: ctx.connectionId,
-            syncId: ctx.syncId,
-            runId: ctx.runId,
-            overrideReplay: ctx.overrideReplay,
-        });
-        return {
-            result: projection,
-            warnings: projection.warnings,
-            errors: [],
-            touchedSources: projection.touchedSources,
-            changedWikiPageKeys: projection.changedWikiPageKeys,
-            actions: projection.actions,
-        };
-    }
 }

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/local-ingest-acceptance.test.js

@@ -194,12 +194,12 @@ describe('historic-SQL local ingest retrieval acceptance', () => {
         expect(result.result.failedWorkUnits).toEqual([]);
         expect(result.result.workUnitCount).toBe(3);
         expect(agentRunner.runLoop).toHaveBeenCalledTimes(3);
-        const finalization = result.report.body.finalization;
-        expect(finalization).toBeDefined();
-        if (!finalization) {
-            throw new Error('Expected historic-SQL finalization result');
+        const postProcessor = result.report.body.postProcessor;
+        expect(postProcessor).toBeDefined();
+        if (!postProcessor) {
+            throw new Error('Expected historic-SQL post-processor result');
         }
-        expect(finalization).toMatchObject({
+        expect(postProcessor).toMatchObject({
             sourceKey: 'historic-sql',
             status: 'success',
             result: {
@@ -207,7 +207,7 @@ describe('historic-SQL local ingest retrieval acceptance', () => {
                 patternPagesWritten: 1,
             },
         });
-        expect(finalization.declaredTouchedSources).toEqual(expect.arrayContaining([
+        expect(postProcessor.touchedSources).toEqual(expect.arrayContaining([
             { connectionId: 'warehouse', sourceName: 'customers' },
             { connectionId: 'warehouse', sourceName: 'orders' },
         ]));

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/post-processor.d.ts

@@ -0,0 +1,4 @@
+import type { IngestBundlePostProcessorInput, IngestBundlePostProcessorPort, IngestBundlePostProcessorResult } from '../../ports.js';
+export declare class HistoricSqlProjectionPostProcessor implements IngestBundlePostProcessorPort {
+    run(input: IngestBundlePostProcessorInput): Promise<IngestBundlePostProcessorResult>;
+}

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/post-processor.js

@@ -0,0 +1,38 @@
+import { createSimpleGit } from '../../../core/git-env.js';
+import { projectHistoricSqlEvidence } from './projection.js';
+async function commitProjectionChanges(workdir) {
+    const git = createSimpleGit(workdir);
+    if (!(await git.checkIsRepo().catch(() => false))) {
+        return;
+    }
+    const status = await git.status();
+    const paths = status.files
+        .map((file) => file.path)
+        .filter((path) => path.startsWith('semantic-layer/') || path.startsWith('wiki/global/historic-sql'));
+    if (paths.length === 0) {
+        return;
+    }
+    await git.add(paths);
+    const staged = await git.diff(['--cached', '--name-only']);
+    if (!staged.trim()) {
+        return;
+    }
+    await git.commit('Project historic SQL evidence', { '--author': 'System User <system@example.com>' });
+}
+export class HistoricSqlProjectionPostProcessor {
+    async run(input) {
+        const projection = await projectHistoricSqlEvidence({
+            workdir: input.workdir,
+            connectionId: input.connectionId,
+            syncId: input.syncId,
+            runId: input.runId,
+        });
+        await commitProjectionChanges(input.workdir);
+        return {
+            result: projection,
+            warnings: projection.warnings,
+            errors: [],
+            touchedSources: projection.touchedSources,
+        };
+    }
+}

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/post-processor.test.js

@@ -0,0 +1,63 @@
+import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import YAML from 'yaml';
+import { describe, expect, it } from 'vitest';
+import { HistoricSqlProjectionPostProcessor } from './post-processor.js';
+async function tempWorkdir() {
+    return mkdtemp(join(tmpdir(), 'historic-sql-post-processor-'));
+}
+async function writeJson(root, relPath, value) {
+    const target = join(root, relPath);
+    await mkdir(join(target, '..'), { recursive: true });
+    await writeFile(target, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+describe('HistoricSqlProjectionPostProcessor', () => {
+    it('projects current run evidence before the ingest squash commit', async () => {
+        const workdir = await tempWorkdir();
+        await mkdir(join(workdir, 'semantic-layer/warehouse/_schema'), { recursive: true });
+        await writeFile(join(workdir, 'semantic-layer/warehouse/_schema/public.yaml'), YAML.stringify({ tables: { orders: { table: 'public.orders', columns: [{ name: 'id', type: 'string' }] } } }), 'utf-8');
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/manifest.json', {
+            source: 'historic-sql',
+            connectionId: 'warehouse',
+            dialect: 'postgres',
+            fetchedAt: '2026-05-11T00:00:00.000Z',
+            windowStart: '2026-02-10T00:00:00.000Z',
+            windowEnd: '2026-05-11T00:00:00.000Z',
+            snapshotRowCount: 1,
+            touchedTableCount: 1,
+            parseFailures: 0,
+            warnings: [],
+            probeWarnings: [],
+            staleArchiveAfterDays: 90,
+        });
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/tables/public.orders.json', { table: 'public.orders' });
+        await writeJson(workdir, '.ktx/ingest-evidence/historic-sql/run-1/orders.json', {
+            kind: 'table_usage',
+            connectionId: 'warehouse',
+            table: 'public.orders',
+            rawPath: 'tables/public.orders.json',
+            usage: {
+                narrative: 'Orders are repeatedly queried by lifecycle status.',
+                frequencyTier: 'high',
+                commonFilters: ['status'],
+                commonJoins: [],
+                staleSince: null,
+            },
+        });
+        const result = await new HistoricSqlProjectionPostProcessor().run({
+            connectionId: 'warehouse',
+            sourceKey: 'historic-sql',
+            syncId: 'sync-1',
+            jobId: 'job-1',
+            runId: 'run-1',
+            workdir,
+            parseArtifacts: null,
+        });
+        expect(result.errors).toEqual([]);
+        expect(result.warnings).toEqual([]);
+        expect(result.touchedSources).toEqual([{ connectionId: 'warehouse', sourceName: 'orders' }]);
+        expect(result.result).toMatchObject({ tableUsageMerged: 1 });
+        await expect(readFile(join(workdir, 'semantic-layer/warehouse/_schema/public.yaml'), 'utf-8')).resolves.toContain('Orders are repeatedly queried by lifecycle status.');
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/projection.d.ts

@@ -1,11 +1,8 @@
-import type { MemoryAction } from '../../../memory/index.js';
-import type { FinalizationOverrideReplay } from '../../types.js';
 export interface HistoricSqlProjectionInput {
     workdir: string;
     connectionId: string;
     syncId: string;
     runId: string;
-    overrideReplay?: FinalizationOverrideReplay;
 }
 export interface HistoricSqlProjectionResult {
     tableUsageMerged: number;
@@ -17,8 +14,6 @@ export interface HistoricSqlProjectionResult {
         connectionId: string;
         sourceName: string;
     }>;
-    changedWikiPageKeys: string[];
-    actions: MemoryAction[];
     warnings: string[];
 }
 export declare function projectHistoricSqlEvidence(input: HistoricSqlProjectionInput): Promise<HistoricSqlProjectionResult>;