@kaelio/ktx 0.1.0-rc.5 → 0.1.0

package/node_modules/@ktx/context/dist/ingest/ingest-bundle.runner.test.js

@@ -1,8 +1,7 @@
-import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { GitService } from '../core/index.js';
 import { addTouchedSlSource } from '../tools/index.js';
 import { IngestBundleRunner } from './ingest-bundle.runner.js';
 import { createMemoryFlowLiveBuffer } from './memory-flow/live-buffer.js';
@@ -113,9 +112,15 @@ const makeDeps = () => {
     };
     const scopedGit = {
         revParseHead: vi.fn().mockResolvedValue('h'),
-        commitFiles: vi.fn(),
+        commitFiles: vi.fn().mockResolvedValue({ created: true, commitHash: 'h' }),
+        commitStaged: vi.fn().mockResolvedValue({ created: false, commitHash: 'h' }),
         resetHardTo: vi.fn(),
         assertWorktreeClean: vi.fn().mockResolvedValue(undefined),
+        writeBinaryNoRenamePatch: vi.fn(async (_base, _head, patchPath) => {
+            await writeFile(patchPath, '', 'utf-8');
+        }),
+        applyPatchFile3WayIndex: vi.fn(),
+        diffNameStatus: vi.fn().mockResolvedValue([]),
     };
     const sessionWorktreeService = {
         create: vi.fn().mockResolvedValue({
@@ -157,10 +162,12 @@ const makeDeps = () => {
         loadPrompt: vi.fn().mockResolvedValue('base-framing'),
     };
     const wikiService = {
-        forWorktree: vi.fn().mockReturnValue({}),
+        forWorktree: vi.fn(),
+        listPageKeys: vi.fn().mockResolvedValue([]),
         readPage: vi.fn().mockResolvedValue(null),
         syncFromCommit: vi.fn().mockResolvedValue(undefined),
     };
+    wikiService.forWorktree.mockReturnValue(wikiService);
     const knowledgeSlRefs = {
         syncFromWiki: vi.fn().mockResolvedValue({ inserted: 1, deleted: 0 }),
     };
@@ -168,7 +175,7 @@ const makeDeps = () => {
         listPagesForUser: vi.fn().mockResolvedValue([]),
     };
     const semanticLayerService = {
-        forWorktree: vi.fn().mockReturnValue({}),
+        forWorktree: vi.fn(),
         listFilesForConnection: vi
             .fn()
             .mockImplementation((connectionId) => Promise.resolve(connectionId === 'warehouse-2' ? ['looker__orders.yaml'] : [])),
@@ -179,6 +186,7 @@ const makeDeps = () => {
             loadErrors: [],
         })),
     };
+    semanticLayerService.forWorktree.mockReturnValue(semanticLayerService);
     const slSearchService = {
         indexSources: vi.fn().mockResolvedValue(undefined),
     };
@@ -239,8 +247,12 @@ const buildRunner = (deps = makeDeps(), overrides = {}) => new IngestBundleRunne
         resolveUploadDir: (uploadId) => `/tmp/ktx-test/ingest-uploads/${uploadId}`,
         resolvePullDir: (jobId) => `/tmp/ktx-test/ingest-pulls/${jobId}`,
         resolveTranscriptDir: (jobId) => `/tmp/ktx-test/run/wu-transcripts/${jobId}`,
+        resolveTracePath: (jobId) => `/tmp/ktx-test/ingest-traces/${jobId}/trace.jsonl`,
+    },
+    settings: {
+        probeRowCount: 1,
+        memoryIngestionModel: 'test-model',
     },
-    settings: { probeRowCount: 1, memoryIngestionModel: 'test-model' },
     skillsRegistry: deps.skillsRegistry,
     promptService: deps.promptService,
     wikiService: deps.wikiService,
@@ -377,6 +389,114 @@ describe('IngestBundleRunner — Stages 1 → 7', () => {
         // Single touched path → path-scoped diff for the LLM commit-message note.
         expect(deps.configService.enqueueCommitMessageJobForExternalCommit).toHaveBeenCalledWith({ commitHash: 'sq' }, expect.stringContaining('ingest(fake): j1'), 'raw-sources/c1/fake/s/a.yml');
     });
+    it('fails before squash when reconciliation leaves a touched wiki page with dangling refs', async () => {
+        const deps = makeDeps();
+        let currentToolSession = null;
+        const scopedWiki = {
+            listPageKeys: vi.fn().mockResolvedValue(['page-a']),
+            readPage: vi.fn().mockImplementation((_scope, _scopeId, key) => {
+                if (key === 'page-a') {
+                    return Promise.resolve({
+                        pageKey: 'page-a',
+                        frontmatter: { summary: 'Page A', usage_mode: 'auto', refs: ['missing-page'] },
+                        content: 'See [[missing-page]].',
+                    });
+                }
+                return Promise.resolve(null);
+            }),
+        };
+        deps.wikiService.forWorktree.mockReturnValue(scopedWiki);
+        deps.toolsetFactory.createIngestWuToolset.mockImplementation((toolSession) => {
+            currentToolSession = toolSession;
+            return {
+                toRuntimeTools: vi.fn().mockReturnValue({}),
+                getAllTools: vi.fn().mockReturnValue([]),
+                getToolNames: vi.fn().mockReturnValue([]),
+            };
+        });
+        deps.agentRunner.runLoop.mockImplementation(async (params) => {
+            if (params.telemetryTags.operationName === 'ingest-bundle-wu') {
+                currentToolSession.actions.push({ target: 'sl', type: 'updated', key: 'orders', detail: 'Orders source' });
+            }
+            if (params.telemetryTags.operationName === 'ingest-bundle-reconcile') {
+                currentToolSession.actions.push({ target: 'wiki', type: 'created', key: 'page-a', detail: 'Page A' });
+            }
+            return { stopReason: 'natural' };
+        });
+        const runner = buildRunner(deps);
+        runner.stageRawFilesStage1 = vi.fn().mockResolvedValue({
+            currentHashes: new Map([['a.yml', 'h1']]),
+            rawDirInWorktree: 'raw-sources/c1/fake/s',
+        });
+        runner.resolveStagedDir = vi.fn().mockResolvedValue('/tmp/stage/upload-x');
+        await expect(runner.run({
+            jobId: 'j1',
+            connectionId: 'c1',
+            sourceKey: 'fake',
+            trigger: 'upload',
+            bundleRef: { kind: 'upload', uploadId: 'upload-x' },
+        })).rejects.toThrow(/wiki references target missing page\(s\): page-a -> missing-page/);
+        expect(deps.runsRepo.markFailed).toHaveBeenCalledWith('run-1');
+        expect(deps.gitService.squashMergeIntoMain).not.toHaveBeenCalled();
+    });
+    it('allows reconciliation to save circular wiki refs once both pages exist', async () => {
+        const deps = makeDeps();
+        let currentToolSession = null;
+        const scopedWiki = {
+            listPageKeys: vi.fn().mockResolvedValue(['page-a', 'page-b']),
+            readPage: vi.fn().mockImplementation((_scope, _scopeId, key) => {
+                if (key === 'page-a') {
+                    return Promise.resolve({
+                        pageKey: 'page-a',
+                        frontmatter: { summary: 'Page A', usage_mode: 'auto', refs: ['page-b'] },
+                        content: 'See [[page-b]].',
+                    });
+                }
+                if (key === 'page-b') {
+                    return Promise.resolve({
+                        pageKey: 'page-b',
+                        frontmatter: { summary: 'Page B', usage_mode: 'auto', refs: ['page-a'] },
+                        content: 'See [[page-a]].',
+                    });
+                }
+                return Promise.resolve(null);
+            }),
+        };
+        deps.wikiService.forWorktree.mockReturnValue(scopedWiki);
+        deps.toolsetFactory.createIngestWuToolset.mockImplementation((toolSession) => {
+            currentToolSession = toolSession;
+            return {
+                toRuntimeTools: vi.fn().mockReturnValue({}),
+                getAllTools: vi.fn().mockReturnValue([]),
+                getToolNames: vi.fn().mockReturnValue([]),
+            };
+        });
+        deps.agentRunner.runLoop.mockImplementation(async (params) => {
+            if (params.telemetryTags.operationName === 'ingest-bundle-wu') {
+                currentToolSession.actions.push({ target: 'sl', type: 'updated', key: 'orders', detail: 'Orders source' });
+            }
+            if (params.telemetryTags.operationName === 'ingest-bundle-reconcile') {
+                currentToolSession.actions.push({ target: 'wiki', type: 'created', key: 'page-a', detail: 'Page A' }, { target: 'wiki', type: 'created', key: 'page-b', detail: 'Page B' });
+            }
+            return { stopReason: 'natural' };
+        });
+        const runner = buildRunner(deps);
+        runner.stageRawFilesStage1 = vi.fn().mockResolvedValue({
+            currentHashes: new Map([['a.yml', 'h1']]),
+            rawDirInWorktree: 'raw-sources/c1/fake/s',
+        });
+        runner.resolveStagedDir = vi.fn().mockResolvedValue('/tmp/stage/upload-x');
+        const result = await runner.run({
+            jobId: 'j1',
+            connectionId: 'c1',
+            sourceKey: 'fake',
+            trigger: 'upload',
+            bundleRef: { kind: 'upload', uploadId: 'upload-x' },
+        });
+        expect(result.failedWorkUnits).toEqual([]);
+        expect(deps.gitService.squashMergeIntoMain).toHaveBeenCalled();
+        expect(deps.runsRepo.markFailed).not.toHaveBeenCalled();
+    });
     it('threads target warehouse connection names into WorkUnit and reconcile tool sessions', async () => {
         const deps = makeDeps();
         const sessions = [];
@@ -1174,7 +1294,7 @@ describe('IngestBundleRunner — Stages 1 → 7', () => {
         });
         const runner = buildRunner(deps);
         runner.stageRawFilesStage1 = vi.fn().mockResolvedValue({
-            currentHashes: new Map([['explores/b2b/sales_pipeline.json', 'h1']]),
+            currentHashes: new Map([['a.yml', 'h1']]),
             rawDirInWorktree: 'raw-sources/looker-run/fake/s',
         });
         runner.resolveStagedDir = vi.fn().mockResolvedValue('/tmp/stage/upload-x');
@@ -1232,6 +1352,7 @@ describe('IngestBundleRunner — Stages 1 → 7', () => {
             workUnits: [{ unitKey: 'u1', rawFiles: ['semantic_models.yml'], peerFileIndex: [], dependencyPaths: [] }],
             parseArtifacts: { semanticModels: [{ name: 'orders' }] },
         });
+        deps.adapter.listTargetConnectionIds = vi.fn().mockResolvedValue(['warehouse-2']);
         deps.semanticLayerService.loadAllSources.mockImplementation((connectionId) => Promise.resolve({ sources: [{ name: `${connectionId}_source` }], loadErrors: [] }));
         const postProcessor = {
             run: vi.fn().mockResolvedValue({
@@ -1567,9 +1688,15 @@ describe('IngestBundleRunner — Stages 1 → 7', () => {
         const assertError = new Error('Worktree has in-progress git operation (sequencer ...); refusing to proceed');
         const sessionGit = {
             revParseHead: vi.fn().mockResolvedValue('h'),
-            commitFiles: vi.fn(),
+            commitFiles: vi.fn().mockResolvedValue({ created: true, commitHash: 'h' }),
+            commitStaged: vi.fn().mockResolvedValue({ created: false, commitHash: 'h' }),
             resetHardTo: vi.fn(),
             assertWorktreeClean: vi.fn().mockRejectedValue(assertError),
+            writeBinaryNoRenamePatch: vi.fn(async (_base, _head, patchPath) => {
+                await writeFile(patchPath, '', 'utf-8');
+            }),
+            applyPatchFile3WayIndex: vi.fn(),
+            diffNameStatus: vi.fn().mockResolvedValue([]),
         };
         deps.sessionWorktreeService.create.mockResolvedValue({
             chatId: 'j1',
@@ -1596,116 +1723,6 @@ describe('IngestBundleRunner — Stages 1 → 7', () => {
         expect(deps.runsRepo.markFailed).toHaveBeenCalledWith('run-1');
         expect(deps.gitService.squashMergeIntoMain).not.toHaveBeenCalled();
     });
-    it('squash-merges only successful WUs into main when one WU fails sl_validate', async () => {
-        const homeDir = await mkdtemp(join(tmpdir(), 'ingest-rollback-'));
-        try {
-            const configDir = join(homeDir, 'config');
-            const mainGit = new GitService({
-                storage: { configDir, homeDir },
-                git: {
-                    userName: 'System User',
-                    userEmail: 'system@example.com',
-                    bootstrapMessage: 'Initialize test config repo',
-                    bootstrapAuthor: 'test-system',
-                    bootstrapAuthorEmail: 'system@example.com',
-                },
-            });
-            await mainGit.onModuleInit();
-            const baseSha = await mainGit.revParseHead();
-            if (!baseSha) {
-                throw new Error('no base sha');
-            }
-            const deps = makeDeps();
-            const sessionDir = join(homeDir, '.worktrees', 'session-j1');
-            const sessionBranch = 'session/j1';
-            let currentToolSession = null;
-            deps.gitService = mainGit;
-            deps.sessionWorktreeService.create.mockImplementation(async (_jobId, startSha) => {
-                await mkdir(join(homeDir, '.worktrees'), { recursive: true });
-                await mainGit.addWorktree(sessionDir, sessionBranch, startSha);
-                return {
-                    chatId: 'j1',
-                    workdir: sessionDir,
-                    branch: sessionBranch,
-                    baseSha: startSha,
-                    createdAt: new Date(),
-                    git: mainGit.forWorktree(sessionDir),
-                    config: {},
-                };
-            });
-            deps.sessionWorktreeService.cleanup.mockResolvedValue(undefined);
-            deps.adapter.chunk.mockResolvedValue({
-                workUnits: [
-                    { unitKey: 'wu-good', rawFiles: ['good.raw'], peerFileIndex: [], dependencyPaths: [] },
-                    { unitKey: 'wu-bad', rawFiles: ['bad.raw'], peerFileIndex: [], dependencyPaths: [] },
-                ],
-            });
-            deps.toolsetFactory.createIngestWuToolset.mockImplementation((toolSession) => {
-                currentToolSession = toolSession;
-                return {
-                    toRuntimeTools: vi.fn().mockReturnValue({}),
-                    getAllTools: vi.fn().mockReturnValue([]),
-                    getToolNames: vi.fn().mockReturnValue([]),
-                };
-            });
-            deps.slValidator.validateSingleSource.mockImplementation((_validationDeps, _connectionId, sourceName) => ({
-                errors: sourceName === 'bad' ? [{ message: 'bad source rejected' }] : [],
-                warnings: [],
-            }));
-            deps.agentRunner.runLoop.mockImplementation(async (params) => {
-                const unitKey = params.telemetryTags?.unitKey;
-                if (unitKey === 'wu-good') {
-                    await mkdir(join(sessionDir, 'semantic-layer', 'c1'), { recursive: true });
-                    await writeFile(join(sessionDir, 'semantic-layer', 'c1', 'good.yaml'), 'name: good\n');
-                    addTouchedSlSource(currentToolSession.touchedSlSources, 'c1', 'good');
-                    currentToolSession.actions.push({ target: 'sl', type: 'created', key: 'good', detail: '' });
-                    await currentToolSession.gitService.commitFiles(['semantic-layer/c1/good.yaml'], 'test: add good source', 'KTX Test', 'system@ktx.local');
-                }
-                if (unitKey === 'wu-bad') {
-                    await mkdir(join(sessionDir, 'semantic-layer', 'c1'), { recursive: true });
-                    await writeFile(join(sessionDir, 'semantic-layer', 'c1', 'bad.yaml'), 'name: bad\n');
-                    addTouchedSlSource(currentToolSession.touchedSlSources, 'c1', 'bad');
-                    currentToolSession.actions.push({ target: 'sl', type: 'created', key: 'bad', detail: '' });
-                    await currentToolSession.gitService.commitFiles(['semantic-layer/c1/bad.yaml'], 'test: add bad source', 'KTX Test', 'system@ktx.local');
-                }
-                return { stopReason: 'natural' };
-            });
-            const runner = buildRunner(deps);
-            runner.stageRawFilesStage1 = vi.fn().mockImplementation(async ({ worktreeRoot }) => {
-                const rawDir = join(worktreeRoot, 'raw-sources', 'c1', 'fake', 's');
-                await mkdir(rawDir, { recursive: true });
-                await writeFile(join(rawDir, 'good.raw'), 'good raw');
-                await writeFile(join(rawDir, 'bad.raw'), 'bad raw');
-                return {
-                    currentHashes: new Map([
-                        ['good.raw', 'good-hash'],
-                        ['bad.raw', 'bad-hash'],
-                    ]),
-                    rawDirInWorktree: 'raw-sources/c1/fake/s',
-                };
-            });
-            runner.resolveStagedDir = vi.fn().mockResolvedValue('/tmp/stage/upload-x');
-            const result = await runner.run({
-                jobId: 'j1',
-                connectionId: 'c1',
-                sourceKey: 'fake',
-                trigger: 'upload',
-                bundleRef: { kind: 'upload', uploadId: 'upload-x' },
-            });
-            expect(result.failedWorkUnits).toEqual(['wu-bad']);
-            expect(await readFile(join(configDir, 'semantic-layer', 'c1', 'good.yaml'), 'utf-8')).toContain('good');
-            expect(await readFile(join(configDir, 'semantic-layer', 'c1', 'bad.yaml'), 'utf-8').catch(() => null)).toBeNull();
-            expect(deps.reportsRepo.create).toHaveBeenCalledWith(expect.objectContaining({
-                body: expect.objectContaining({
-                    failedWorkUnits: ['wu-bad'],
-                }),
-            }));
-            await expect(stat(join(configDir, '.git', 'sequencer'))).rejects.toThrow();
-        }
-        finally {
-            await rm(homeDir, { recursive: true, force: true });
-        }
-    });
     it('fails the run and rethrows when the adapter cannot detect the bundle', async () => {
         const deps = makeDeps();
         deps.adapter.detect.mockResolvedValue(false);

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

@@ -0,0 +1,50 @@
+export type IngestTraceLevel = 'info' | 'debug' | 'trace' | 'error';
+export interface IngestTraceContext {
+    tracePath: string;
+    jobId: string;
+    connectionId: string;
+    sourceKey: string;
+    runId?: string;
+    syncId?: string;
+    level?: IngestTraceLevel;
+}
+export interface IngestTraceEvent {
+    schemaVersion: 1;
+    at: string;
+    level: IngestTraceLevel;
+    jobId: string;
+    connectionId: string;
+    sourceKey: string;
+    runId?: string;
+    syncId?: string;
+    phase: string;
+    event: string;
+    durationMs?: number;
+    data?: Record<string, unknown>;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+export interface IngestTraceWriter {
+    readonly tracePath: string;
+    readonly context: IngestTraceContext;
+    withContext(context: Partial<Pick<IngestTraceContext, 'runId' | 'syncId'>>): IngestTraceWriter;
+    event(level: IngestTraceLevel, phase: string, event: string, data?: Record<string, unknown>, error?: unknown, durationMs?: number): Promise<void>;
+}
+export declare function ingestTracePathForJob(homeDir: string, jobId: string): string;
+export declare class FileIngestTraceWriter implements IngestTraceWriter {
+    readonly tracePath: string;
+    readonly context: IngestTraceContext;
+    constructor(context: IngestTraceContext);
+    withContext(context: Partial<Pick<IngestTraceContext, 'runId' | 'syncId'>>): IngestTraceWriter;
+    event(level: IngestTraceLevel, phase: string, event: string, data?: Record<string, unknown>, error?: unknown, durationMs?: number): Promise<void>;
+}
+export declare class NoopIngestTraceWriter implements IngestTraceWriter {
+    readonly tracePath = "";
+    readonly context: IngestTraceContext;
+    withContext(): IngestTraceWriter;
+    event(): Promise<void>;
+}
+export declare function traceTimed<T>(trace: IngestTraceWriter, phase: string, event: string, data: Record<string, unknown>, fn: () => Promise<T>): Promise<T>;

package/node_modules/@ktx/context/dist/ingest/ingest-trace.js

@@ -0,0 +1,88 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+const TRACE_LEVEL_RANK = {
+    error: 0,
+    info: 1,
+    debug: 2,
+    trace: 3,
+};
+export function ingestTracePathForJob(homeDir, jobId) {
+    return join(homeDir, 'ingest-traces', jobId, 'trace.jsonl');
+}
+function serializeError(error) {
+    if (error === undefined || error === null) {
+        return undefined;
+    }
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            ...(error.stack ? { stack: error.stack } : {}),
+        };
+    }
+    return { name: 'Error', message: String(error) };
+}
+function shouldWrite(configured, incoming) {
+    return TRACE_LEVEL_RANK[incoming] <= TRACE_LEVEL_RANK[configured];
+}
+export class FileIngestTraceWriter {
+    tracePath;
+    context;
+    constructor(context) {
+        this.context = { ...context, level: context.level ?? 'debug' };
+        this.tracePath = context.tracePath;
+    }
+    withContext(context) {
+        return new FileIngestTraceWriter({ ...this.context, ...context, tracePath: this.tracePath });
+    }
+    async event(level, phase, event, data, error, durationMs) {
+        if (!shouldWrite(this.context.level ?? 'debug', level)) {
+            return;
+        }
+        const serializedError = serializeError(error);
+        const payload = {
+            schemaVersion: 1,
+            at: new Date().toISOString(),
+            level,
+            jobId: this.context.jobId,
+            connectionId: this.context.connectionId,
+            sourceKey: this.context.sourceKey,
+            ...(this.context.runId ? { runId: this.context.runId } : {}),
+            ...(this.context.syncId ? { syncId: this.context.syncId } : {}),
+            phase,
+            event,
+            ...(durationMs !== undefined ? { durationMs } : {}),
+            ...(data ? { data } : {}),
+            ...(serializedError ? { error: serializedError } : {}),
+        };
+        await mkdir(dirname(this.tracePath), { recursive: true });
+        await appendFile(this.tracePath, `${JSON.stringify(payload)}\n`, 'utf-8');
+    }
+}
+export class NoopIngestTraceWriter {
+    tracePath = '';
+    context = {
+        tracePath: '',
+        jobId: '',
+        connectionId: '',
+        sourceKey: '',
+        level: 'error',
+    };
+    withContext() {
+        return this;
+    }
+    async event() { }
+}
+export async function traceTimed(trace, phase, event, data, fn) {
+    await trace.event('debug', phase, `${event}_started`, data);
+    const started = Date.now();
+    try {
+        const result = await fn();
+        await trace.event('debug', phase, `${event}_finished`, data, undefined, Date.now() - started);
+        return result;
+    }
+    catch (error) {
+        await trace.event('error', phase, `${event}_failed`, data, error, Date.now() - started);
+        throw error;
+    }
+}

package/node_modules/@ktx/context/dist/ingest/ingest-trace.test.d.ts

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

package/node_modules/@ktx/context/dist/ingest/ingest-trace.test.js

@@ -0,0 +1,76 @@
+import { mkdtemp, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+import { FileIngestTraceWriter, ingestTracePathForJob, traceTimed } from './ingest-trace.js';
+describe('FileIngestTraceWriter', () => {
+    it('persists structured trace events as JSONL', async () => {
+        const root = await mkdtemp(join(tmpdir(), 'ktx-trace-'));
+        const tracePath = ingestTracePathForJob(root, 'job-1');
+        const trace = new FileIngestTraceWriter({
+            tracePath,
+            jobId: 'job-1',
+            connectionId: 'metabase-main',
+            sourceKey: 'metabase',
+            level: 'debug',
+        });
+        await trace.event('debug', 'snapshot', 'input_snapshot', {
+            baseSha: 'abc123',
+            rawFileCount: 2,
+            diffSummary: { added: 1, modified: 1, deleted: 0, unchanged: 3 },
+        });
+        const lines = (await readFile(tracePath, 'utf-8'))
+            .trim()
+            .split('\n')
+            .map((line) => JSON.parse(line));
+        expect(lines).toHaveLength(1);
+        expect(lines[0]).toMatchObject({
+            schemaVersion: 1,
+            jobId: 'job-1',
+            connectionId: 'metabase-main',
+            sourceKey: 'metabase',
+            level: 'debug',
+            phase: 'snapshot',
+            event: 'input_snapshot',
+            data: {
+                baseSha: 'abc123',
+                rawFileCount: 2,
+                diffSummary: { added: 1, modified: 1, deleted: 0, unchanged: 3 },
+            },
+        });
+        expect(typeof lines[0].at).toBe('string');
+    });
+    it('records timing and error context for postmortem inspection', async () => {
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date('2026-05-17T12:00:00.000Z'));
+        const root = await mkdtemp(join(tmpdir(), 'ktx-trace-'));
+        const tracePath = ingestTracePathForJob(root, 'job-2');
+        const trace = new FileIngestTraceWriter({
+            tracePath,
+            jobId: 'job-2',
+            connectionId: 'c1',
+            sourceKey: 'fake',
+            level: 'trace',
+        });
+        await expect(traceTimed(trace, 'integration', 'apply_patch', { unitKey: 'wu-1' }, async () => {
+            vi.advanceTimersByTime(17);
+            throw new Error('patch conflict');
+        })).rejects.toThrow('patch conflict');
+        const lines = (await readFile(tracePath, 'utf-8'))
+            .trim()
+            .split('\n')
+            .map((line) => JSON.parse(line));
+        expect(lines.map((line) => line.event)).toEqual(['apply_patch_started', 'apply_patch_failed']);
+        expect(lines[1]).toMatchObject({
+            level: 'error',
+            phase: 'integration',
+            data: { unitKey: 'wu-1' },
+            error: { name: 'Error', message: 'patch conflict' },
+        });
+        expect(lines[1].durationMs).toBe(17);
+        vi.useRealTimers();
+    });
+    it('uses the documented trace path layout', () => {
+        expect(ingestTracePathForJob('/project/.ktx', 'job-3')).toBe('/project/.ktx/ingest-traces/job-3/trace.jsonl');
+    });
+});

package/node_modules/@ktx/context/dist/ingest/isolated-diff/git-patch.d.ts

@@ -0,0 +1,16 @@
+export declare const textArtifactRoots: readonly ["wiki/", "semantic-layer/"];
+export interface PatchTouchedPath {
+    path: string;
+    oldPath: string;
+    newPath: string;
+    mode: string | null;
+    binary: boolean;
+}
+export interface PatchPolicyInput {
+    unitKey: string;
+    patch: string;
+    slDisallowed: boolean;
+    allowedTargetConnectionIds?: ReadonlySet<string>;
+}
+export declare function parsePatchTouchedPaths(patch: string): PatchTouchedPath[];
+export declare function assertPatchAllowedForWorkUnit(input: PatchPolicyInput): PatchTouchedPath[];

package/node_modules/@ktx/context/dist/ingest/isolated-diff/git-patch.js

@@ -0,0 +1,78 @@
+import { assertSemanticLayerTargetPathsAllowed } from '../semantic-layer-target-policy.js';
+export const textArtifactRoots = ['wiki/', 'semantic-layer/'];
+function stripPrefix(path) {
+    return path.replace(/^[ab]\//, '');
+}
+function isTextArtifactPath(path) {
+    return textArtifactRoots.some((root) => path.startsWith(root));
+}
+export function parsePatchTouchedPaths(patch) {
+    const lines = patch.split('\n');
+    const entries = [];
+    let current = null;
+    const pushCurrent = () => {
+        if (current) {
+            entries.push(current);
+        }
+    };
+    for (const line of lines) {
+        const diffMatch = /^diff --git (.+) (.+)$/.exec(line);
+        if (diffMatch) {
+            pushCurrent();
+            const oldPath = stripPrefix(diffMatch[1] ?? '');
+            const newPath = stripPrefix(diffMatch[2] ?? '');
+            current = {
+                path: newPath === '/dev/null' ? oldPath : newPath,
+                oldPath,
+                newPath,
+                mode: null,
+                binary: false,
+            };
+            continue;
+        }
+        if (!current) {
+            continue;
+        }
+        const indexMode = /^index [0-9a-f]+\.\.[0-9a-f]+(?: ([0-7]{6}))?$/.exec(line);
+        if (indexMode?.[1]) {
+            current.mode = indexMode[1];
+        }
+        const newMode = /^new mode ([0-7]{6})$/.exec(line);
+        if (newMode) {
+            current.mode = newMode[1] ?? current.mode;
+        }
+        const newFileMode = /^new file mode ([0-7]{6})$/.exec(line);
+        if (newFileMode) {
+            current.mode = newFileMode[1] ?? current.mode;
+        }
+        if (line === 'GIT binary patch' || line.startsWith('Binary files ')) {
+            current.binary = true;
+        }
+    }
+    pushCurrent();
+    return entries;
+}
+export function assertPatchAllowedForWorkUnit(input) {
+    const touched = parsePatchTouchedPaths(input.patch);
+    if (input.allowedTargetConnectionIds) {
+        assertSemanticLayerTargetPathsAllowed({
+            paths: touched.map((entry) => entry.path),
+            allowedConnectionIds: input.allowedTargetConnectionIds,
+        });
+    }
+    for (const entry of touched) {
+        if (input.slDisallowed && entry.path.startsWith('semantic-layer/')) {
+            throw new Error(`slDisallowed WorkUnit ${input.unitKey} touched ${entry.path}`);
+        }
+        if (!isTextArtifactPath(entry.path)) {
+            continue;
+        }
+        if (entry.binary) {
+            throw new Error(`unexpected binary patch under ${entry.path}`);
+        }
+        if (entry.mode && entry.mode !== '100644') {
+            throw new Error(`unexpected executable mode under ${entry.path}: ${entry.mode}`);
+        }
+    }
+    return touched;
+}

package/node_modules/@ktx/context/dist/ingest/isolated-diff/git-patch.test.d.ts

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