@kaelio/ktx 0.1.0-rc.5 → 0.1.0

package/node_modules/@ktx/context/dist/ingest/artifact-gates.js

@@ -0,0 +1,149 @@
+import { findMissingWikiRefs } from '../wiki/wiki-ref-validation.js';
+import { findInvalidWikiBodyRefs } from './wiki-body-refs.js';
+function parseSlRef(ref) {
+    const withoutConnection = ref.includes('/') ? ref.slice(ref.indexOf('/') + 1) : ref;
+    const connectionId = ref.includes('/') ? ref.slice(0, ref.indexOf('/')) : null;
+    const [sourceName = '', entityName = null] = withoutConnection.split('.', 2);
+    return { connectionId, sourceName, entityName };
+}
+function slEntityNames(source) {
+    return new Set([
+        ...(source.measures ?? []).map((measure) => measure.name),
+        ...(source.columns ?? []).map((column) => column.name),
+        ...(source.segments ?? []).map((segment) => segment.name),
+    ]);
+}
+function uniqueTouchedSources(sources) {
+    const seen = new Set();
+    const unique = [];
+    for (const source of sources) {
+        const key = `${source.connectionId}:${source.sourceName}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        unique.push(source);
+    }
+    return unique.sort((left, right) => {
+        const byConnection = left.connectionId.localeCompare(right.connectionId);
+        return byConnection === 0 ? left.sourceName.localeCompare(right.sourceName) : byConnection;
+    });
+}
+async function expandTouchedSlSourcesWithDirectJoinNeighbors(input) {
+    const expanded = [...input.touchedSlSources];
+    const touchedByConnection = new Map();
+    for (const source of input.touchedSlSources) {
+        const bucket = touchedByConnection.get(source.connectionId) ?? new Set();
+        bucket.add(source.sourceName);
+        touchedByConnection.set(source.connectionId, bucket);
+    }
+    for (const connectionId of input.connectionIds) {
+        const touched = touchedByConnection.get(connectionId);
+        if (!touched || touched.size === 0) {
+            continue;
+        }
+        const { sources } = await input.semanticLayerService.loadAllSources(connectionId);
+        for (const source of sources) {
+            const sourceIsTouched = touched.has(source.name);
+            if (sourceIsTouched) {
+                for (const join of source.joins ?? []) {
+                    expanded.push({ connectionId, sourceName: join.to });
+                }
+            }
+            if ((source.joins ?? []).some((join) => touched.has(join.to))) {
+                expanded.push({ connectionId, sourceName: source.name });
+            }
+        }
+    }
+    return uniqueTouchedSources(expanded);
+}
+async function validateWikiSlRefs(input) {
+    const errors = [];
+    const sourcesByConnection = new Map();
+    for (const connectionId of input.connectionIds) {
+        const { sources } = await input.semanticLayerService.loadAllSources(connectionId);
+        sourcesByConnection.set(connectionId, sources);
+    }
+    for (const pageKey of input.changedWikiPageKeys) {
+        const page = await input.wikiService.readPage('GLOBAL', null, pageKey);
+        if (!page) {
+            continue;
+        }
+        for (const ref of page.frontmatter.sl_refs ?? []) {
+            const parsed = parseSlRef(ref);
+            const candidateConnections = parsed.connectionId ? [parsed.connectionId] : input.connectionIds;
+            let source;
+            for (const connectionId of candidateConnections) {
+                source = sourcesByConnection.get(connectionId)?.find((candidate) => candidate.name === parsed.sourceName);
+                if (source) {
+                    break;
+                }
+            }
+            if (!source) {
+                errors.push(`${pageKey}: unknown sl_refs entry ${ref}`);
+                continue;
+            }
+            if (parsed.entityName && !slEntityNames(source).has(parsed.entityName)) {
+                errors.push(`${pageKey}: unknown sl_refs entity ${ref}`);
+            }
+        }
+    }
+    return errors;
+}
+async function validateWikiRefs(input) {
+    const dangling = [];
+    for (const pageKey of input.changedWikiPageKeys) {
+        const page = await input.wikiService.readPage('GLOBAL', null, pageKey);
+        if (!page) {
+            continue;
+        }
+        const missingRefs = await findMissingWikiRefs({
+            wikiService: input.wikiService,
+            scope: 'GLOBAL',
+            scopeId: null,
+            pageKey,
+            refs: page.frontmatter.refs,
+            content: page.content,
+        });
+        for (const missingRef of missingRefs) {
+            dangling.push(`${pageKey} -> ${missingRef}`);
+        }
+    }
+    return dangling;
+}
+export async function validateFinalIngestArtifacts(input) {
+    const touchedWithDependencies = await expandTouchedSlSourcesWithDirectJoinNeighbors(input);
+    const validation = await input.validateTouchedSources(touchedWithDependencies);
+    const errors = validation.invalidSources.map((source) => `semantic-layer validation failed for ${source}`);
+    errors.push(...(await validateWikiSlRefs(input)));
+    const danglingWikiRefs = await validateWikiRefs(input);
+    if (danglingWikiRefs.length > 0) {
+        errors.push(`wiki references target missing page(s): ${danglingWikiRefs.join(', ')}`);
+    }
+    for (const pageKey of input.changedWikiPageKeys) {
+        const page = await input.wikiService.readPage('GLOBAL', null, pageKey);
+        if (!page) {
+            continue;
+        }
+        errors.push(...(await findInvalidWikiBodyRefs({
+            pageKey,
+            body: page.content,
+            visibleConnectionIds: input.connectionIds,
+            loadSources: async (connectionId) => {
+                const { sources } = await input.semanticLayerService.loadAllSources(connectionId);
+                return sources;
+            },
+            tableExists: input.tableExists,
+        })));
+    }
+    if (errors.length > 0) {
+        throw new Error(`final artifact gates failed:\n${errors.join('\n')}`);
+    }
+}
+export function validateProvenanceRawPaths(input) {
+    for (const row of input.rows) {
+        if (!input.currentRawPaths.has(row.rawPath) && !input.deletedRawPaths.has(row.rawPath)) {
+            throw new Error(`provenance row references raw path outside this snapshot: ${row.rawPath}`);
+        }
+    }
+}

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

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

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

@@ -0,0 +1,167 @@
+import { describe, expect, it, vi } from 'vitest';
+import { validateFinalIngestArtifacts, validateProvenanceRawPaths } from './artifact-gates.js';
+function wikiServiceWithPages(pages) {
+    return {
+        listPageKeys: vi.fn().mockResolvedValue(Object.keys(pages)),
+        readPage: vi.fn().mockImplementation((_scope, _scopeId, pageKey) => {
+            const page = pages[pageKey];
+            if (!page) {
+                return Promise.resolve(null);
+            }
+            return Promise.resolve({
+                pageKey,
+                frontmatter: {
+                    summary: pageKey,
+                    usage_mode: 'auto',
+                    refs: page.refs,
+                    sl_refs: page.slRefs,
+                },
+                content: page.content ?? '',
+            });
+        }),
+    };
+}
+describe('artifact gates', () => {
+    it('fails the final tree when wiki body references a stale semantic-layer measure', async () => {
+        const wikiService = wikiServiceWithPages({
+            'account-segments': {
+                slRefs: ['mart_account_segments'],
+                content: 'ARR is `mart_account_segments.total_contract_arr_cents`.',
+            },
+        });
+        const semanticLayerService = {
+            loadAllSources: vi.fn().mockResolvedValue({
+                sources: [
+                    {
+                        name: 'mart_account_segments',
+                        grain: ['account_id'],
+                        columns: [{ name: 'account_id', type: 'string' }],
+                        joins: [],
+                        measures: [{ name: 'total_contract_arr', expr: 'sum(contract_arr)' }],
+                        table: 'analytics.mart_account_segments',
+                    },
+                ],
+                loadErrors: [],
+            }),
+        };
+        await expect(validateFinalIngestArtifacts({
+            connectionIds: ['warehouse'],
+            changedWikiPageKeys: ['account-segments'],
+            touchedSlSources: [{ connectionId: 'warehouse', sourceName: 'mart_account_segments' }],
+            wikiService: wikiService,
+            semanticLayerService: semanticLayerService,
+            validateTouchedSources: async () => ({ invalidSources: [], validSources: ['mart_account_segments'] }),
+            tableExists: async () => true,
+        })).rejects.toThrow(/unknown semantic-layer entity mart_account_segments\.total_contract_arr_cents/);
+    });
+    it('fails before provenance insertion when a raw path cannot be tied to the current snapshot or eviction set', () => {
+        expect(() => validateProvenanceRawPaths({
+            rows: [{ rawPath: 'cards/missing.json' }],
+            currentRawPaths: new Set(['cards/present.json']),
+            deletedRawPaths: new Set(['cards/deleted.json']),
+        })).toThrow(/provenance row references raw path outside this snapshot: cards\/missing\.json/);
+    });
+    it('fails measure-level wiki frontmatter sl_refs that point at missing entities', async () => {
+        const wikiService = wikiServiceWithPages({
+            'account-segments': {
+                slRefs: ['mart_account_segments.total_contract_arr_cents'],
+                content: 'ARR uses a renamed measure.',
+            },
+        });
+        const semanticLayerService = {
+            loadAllSources: vi.fn().mockResolvedValue({
+                sources: [
+                    {
+                        name: 'mart_account_segments',
+                        grain: ['account_id'],
+                        columns: [{ name: 'account_id', type: 'string' }],
+                        joins: [],
+                        measures: [{ name: 'total_contract_arr', expr: 'sum(contract_arr)' }],
+                        table: 'analytics.mart_account_segments',
+                    },
+                ],
+                loadErrors: [],
+            }),
+        };
+        await expect(validateFinalIngestArtifacts({
+            connectionIds: ['warehouse'],
+            changedWikiPageKeys: ['account-segments'],
+            touchedSlSources: [{ connectionId: 'warehouse', sourceName: 'mart_account_segments' }],
+            wikiService: wikiService,
+            semanticLayerService: semanticLayerService,
+            validateTouchedSources: async () => ({ invalidSources: [], validSources: ['warehouse:mart_account_segments'] }),
+            tableExists: async () => true,
+        })).rejects.toThrow(/unknown sl_refs entity mart_account_segments\.total_contract_arr_cents/);
+    });
+    it('validates direct declared-join neighbors of touched semantic-layer sources', async () => {
+        const semanticLayerService = {
+            loadAllSources: vi.fn().mockResolvedValue({
+                sources: [
+                    {
+                        name: 'orders',
+                        grain: ['order_id'],
+                        columns: [
+                            { name: 'order_id', type: 'string' },
+                            { name: 'account_id', type: 'string' },
+                        ],
+                        joins: [{ to: 'accounts', on: 'orders.account_id = accounts.account_id', relationship: 'many_to_one' }],
+                        measures: [{ name: 'order_count', expr: 'count(*)' }],
+                    },
+                    {
+                        name: 'accounts',
+                        grain: ['account_id'],
+                        columns: [{ name: 'account_id', type: 'string' }],
+                        joins: [],
+                        measures: [{ name: 'account_count', expr: 'count(*)' }],
+                    },
+                    {
+                        name: 'segments',
+                        grain: ['segment_id'],
+                        columns: [
+                            { name: 'segment_id', type: 'string' },
+                            { name: 'account_id', type: 'string' },
+                        ],
+                        joins: [{ to: 'accounts', on: 'segments.account_id = accounts.account_id', relationship: 'many_to_one' }],
+                        measures: [],
+                    },
+                ],
+                loadErrors: [],
+            }),
+        };
+        const validateTouchedSources = vi.fn().mockResolvedValue({ invalidSources: [], validSources: [] });
+        await validateFinalIngestArtifacts({
+            connectionIds: ['warehouse'],
+            changedWikiPageKeys: [],
+            touchedSlSources: [{ connectionId: 'warehouse', sourceName: 'accounts' }],
+            wikiService: { readPage: vi.fn() },
+            semanticLayerService: semanticLayerService,
+            validateTouchedSources,
+            tableExists: async () => true,
+        });
+        expect(validateTouchedSources).toHaveBeenCalledWith([
+            { connectionId: 'warehouse', sourceName: 'accounts' },
+            { connectionId: 'warehouse', sourceName: 'orders' },
+            { connectionId: 'warehouse', sourceName: 'segments' },
+        ]);
+    });
+    it('fails final gates when a changed wiki page references a missing wiki page', async () => {
+        const wikiService = wikiServiceWithPages({
+            'account-segments': {
+                refs: ['missing-frontmatter-page'],
+                content: 'See [[missing-inline-page]] for the related process.',
+            },
+        });
+        const semanticLayerService = {
+            loadAllSources: vi.fn().mockResolvedValue({ sources: [], loadErrors: [] }),
+        };
+        await expect(validateFinalIngestArtifacts({
+            connectionIds: ['warehouse'],
+            changedWikiPageKeys: ['account-segments'],
+            touchedSlSources: [],
+            wikiService: wikiService,
+            semanticLayerService: semanticLayerService,
+            validateTouchedSources: async () => ({ invalidSources: [], validSources: [] }),
+            tableExists: async () => true,
+        })).rejects.toThrow(/wiki references target missing page\(s\): account-segments -> missing-frontmatter-page, account-segments -> missing-inline-page/);
+    });
+});

package/node_modules/@ktx/context/dist/ingest/final-gate-repair.d.ts

@@ -0,0 +1,29 @@
+import type { AgentRunnerPort } from '../llm/index.js';
+import type { TouchedSlSource } from '../tools/index.js';
+import type { IngestTraceWriter } from './ingest-trace.js';
+type FinalGateRepairKind = 'patch_semantic_gate' | 'final_artifact_gate';
+export type FinalGateRepairResult = {
+    status: 'repaired';
+    attempts: number;
+    changedPaths: string[];
+} | {
+    status: 'failed';
+    attempts: number;
+    reason: string;
+};
+export interface RepairFinalGateFailureInput {
+    agentRunner: AgentRunnerPort;
+    workdir: string;
+    gateError: string;
+    allowedPaths: string[];
+    trace: IngestTraceWriter;
+    repairKind: FinalGateRepairKind;
+    maxAttempts?: number;
+    stepBudget?: number;
+}
+export declare function finalGateRepairPaths(input: {
+    changedWikiPageKeys: string[];
+    touchedSlSources: TouchedSlSource[];
+}): string[];
+export declare function repairFinalGateFailure(input: RepairFinalGateFailureInput): Promise<FinalGateRepairResult>;
+export {};

package/node_modules/@ktx/context/dist/ingest/final-gate-repair.js

@@ -0,0 +1,178 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { traceTimed } from './ingest-trace.js';
+const readRepairFileSchema = z.object({
+    path: z.string().min(1),
+});
+const writeRepairFileSchema = z.object({
+    path: z.string().min(1),
+    content: z.string(),
+});
+function normalizeRepoPath(path) {
+    const normalized = path.replace(/\\/g, '/').replace(/^\/+/, '');
+    const parts = normalized.split('/').filter((part) => part.length > 0);
+    if (parts.length === 0 || parts.some((part) => part === '.' || part === '..')) {
+        throw new Error(`gate repair path must be a repository-relative path: ${path}`);
+    }
+    return parts.join('/');
+}
+function assertAllowedPath(path, allowedPaths) {
+    const normalized = normalizeRepoPath(path);
+    if (!allowedPaths.has(normalized)) {
+        throw new Error(`gate repair path not allowed: ${normalized}`);
+    }
+    return normalized;
+}
+async function readOptionalFile(path) {
+    try {
+        return { exists: true, content: await readFile(path, 'utf-8') };
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return { exists: false, content: '' };
+        }
+        throw error;
+    }
+}
+function buildGateRepairSystemPrompt() {
+    return `<role>
+You repair one KTX isolated-diff artifact gate failure inside the integration worktree.
+</role>
+
+<rules>
+- Use read_gate_error first.
+- Read only files exposed by read_repair_file.
+- Edit only paths exposed by write_repair_file.
+- Prefer the smallest text edit that makes the gate pass.
+- Preserve accepted work-unit, reconciliation, and deterministic projection content.
+- Do not invent warehouse facts, business definitions, or semantic-layer entities.
+- If the gate error requires choosing between conflicting facts without evidence, stop without editing.
+</rules>`;
+}
+function buildGateRepairUserPrompt(input) {
+    return `Repair isolated-diff artifact gates.
+
+Repair kind: ${input.repairKind}
+Attempt: ${input.attempt} of ${input.maxAttempts}
+
+Allowed files:
+${input.allowedPaths.map((path) => `- ${path}`).join('\n')}
+
+Gate error:
+${input.gateError}
+
+Use read_gate_error first. Then inspect only the allowed files, write the
+minimal repaired content, and stop.`;
+}
+function buildToolSet(input) {
+    return {
+        read_gate_error: {
+            name: 'read_gate_error',
+            description: 'Read the artifact gate failure that must be repaired.',
+            inputSchema: z.object({}),
+            execute: async () => ({
+                markdown: input.gateError,
+                structured: { gateError: input.gateError },
+            }),
+        },
+        read_repair_file: {
+            name: 'read_repair_file',
+            description: 'Read one allowed file from the integration worktree.',
+            inputSchema: readRepairFileSchema,
+            execute: async ({ path }) => {
+                const normalized = assertAllowedPath(path, input.allowedPaths);
+                const file = await readOptionalFile(join(input.workdir, normalized));
+                return {
+                    markdown: file.exists ? file.content : `(missing file: ${normalized})`,
+                    structured: { path: normalized, exists: file.exists },
+                };
+            },
+        },
+        write_repair_file: {
+            name: 'write_repair_file',
+            description: 'Replace one allowed integration worktree file with repaired text content.',
+            inputSchema: writeRepairFileSchema,
+            execute: async ({ path, content }) => {
+                const normalized = assertAllowedPath(path, input.allowedPaths);
+                const fullPath = join(input.workdir, normalized);
+                await mkdir(dirname(fullPath), { recursive: true });
+                await writeFile(fullPath, content, 'utf-8');
+                input.editedPaths.add(normalized);
+                return {
+                    markdown: `Wrote ${normalized}`,
+                    structured: { path: normalized, bytes: Buffer.byteLength(content) },
+                };
+            },
+        },
+    };
+}
+export function finalGateRepairPaths(input) {
+    return [
+        ...new Set([
+            ...input.touchedSlSources.map((source) => `semantic-layer/${source.connectionId}/${source.sourceName}.yaml`),
+            ...input.changedWikiPageKeys.map((pageKey) => `wiki/global/${pageKey}.md`),
+        ]),
+    ].sort();
+}
+export async function repairFinalGateFailure(input) {
+    const allowedPaths = new Set(input.allowedPaths.map(normalizeRepoPath));
+    const maxAttempts = input.maxAttempts ?? 1;
+    const stepBudget = input.stepBudget ?? 16;
+    let lastFailure = 'gate repair did not run';
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const editedPaths = new Set();
+        const sortedAllowedPaths = [...allowedPaths].sort();
+        const traceData = {
+            repairKind: input.repairKind,
+            attempt,
+            maxAttempts,
+            allowedPaths: sortedAllowedPaths,
+            gateError: input.gateError,
+        };
+        const result = await traceTimed(input.trace, 'gate_repair', 'gate_repair', traceData, async () => input.agentRunner.runLoop({
+            modelRole: 'repair',
+            systemPrompt: buildGateRepairSystemPrompt(),
+            userPrompt: buildGateRepairUserPrompt({
+                gateError: input.gateError,
+                allowedPaths: sortedAllowedPaths,
+                repairKind: input.repairKind,
+                attempt,
+                maxAttempts,
+            }),
+            toolSet: buildToolSet({
+                workdir: input.workdir,
+                gateError: input.gateError,
+                allowedPaths,
+                editedPaths,
+            }),
+            stepBudget,
+            telemetryTags: {
+                operationName: 'ingest-isolated-diff-gate-repair',
+                source: input.trace.context.sourceKey,
+                jobId: input.trace.context.jobId,
+                repairKind: input.repairKind,
+            },
+        }));
+        if (result.stopReason === 'error') {
+            lastFailure = result.error?.message ?? 'gate repair agent loop errored';
+            await input.trace.event('error', 'gate_repair', 'gate_repair_failed', traceData, result.error);
+            continue;
+        }
+        const changedPaths = [...editedPaths].sort();
+        if (changedPaths.length === 0) {
+            lastFailure = 'gate repair completed without editing an allowed path';
+            await input.trace.event('error', 'gate_repair', 'gate_repair_failed', {
+                ...traceData,
+                reason: lastFailure,
+            });
+            continue;
+        }
+        await input.trace.event('debug', 'gate_repair', 'gate_repair_repaired', {
+            ...traceData,
+            changedPaths,
+        });
+        return { status: 'repaired', attempts: attempt, changedPaths };
+    }
+    return { status: 'failed', attempts: maxAttempts, reason: lastFailure };
+}

package/node_modules/@ktx/context/dist/ingest/final-gate-repair.test.d.ts

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

package/node_modules/@ktx/context/dist/ingest/final-gate-repair.test.js

@@ -0,0 +1,109 @@
+import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+import { finalGateRepairPaths, repairFinalGateFailure } from './final-gate-repair.js';
+import { FileIngestTraceWriter } from './ingest-trace.js';
+async function makeHarness() {
+    const root = await mkdtemp(join(tmpdir(), 'ktx-final-gate-repair-'));
+    const workdir = join(root, 'workdir');
+    await mkdir(join(workdir, 'wiki/global'), { recursive: true });
+    await mkdir(join(workdir, 'semantic-layer/warehouse'), { recursive: true });
+    await writeFile(join(workdir, 'wiki/global/account-segments.md'), '---\nsummary: Account segments\nusage_mode: auto\n---\n\nARR uses `mart_account_segments.total_contract_arr_cents`.\n', 'utf-8');
+    await writeFile(join(workdir, 'semantic-layer/warehouse/mart_account_segments.yaml'), 'name: mart_account_segments\ncolumns: [{name: account_id, type: string}]\njoins: []\nmeasures:\n  - name: total_contract_arr\n    expr: sum(contract_arr)\n', 'utf-8');
+    const trace = new FileIngestTraceWriter({
+        tracePath: join(root, 'trace.jsonl'),
+        jobId: 'job-1',
+        connectionId: 'warehouse',
+        sourceKey: 'metabase',
+        runId: 'run-1',
+        syncId: 'sync-1',
+        level: 'trace',
+    });
+    return { root, workdir, trace };
+}
+describe('finalGateRepairPaths', () => {
+    it('derives sorted wiki and semantic-layer file paths', () => {
+        expect(finalGateRepairPaths({
+            changedWikiPageKeys: ['account-segments', 'overview', 'account-segments'],
+            touchedSlSources: [
+                { connectionId: 'warehouse', sourceName: 'mart_account_segments' },
+                { connectionId: 'warehouse', sourceName: 'orders' },
+                { connectionId: 'warehouse', sourceName: 'orders' },
+            ],
+        })).toEqual([
+            'semantic-layer/warehouse/mart_account_segments.yaml',
+            'semantic-layer/warehouse/orders.yaml',
+            'wiki/global/account-segments.md',
+            'wiki/global/overview.md',
+        ]);
+    });
+});
+describe('repairFinalGateFailure', () => {
+    it('lets the repair agent read gate errors and edit only allowed files', async () => {
+        const { workdir, trace } = await makeHarness();
+        const agentRunner = {
+            runLoop: vi.fn(async (params) => {
+                const error = await params.toolSet.read_gate_error.execute({});
+                expect(error.markdown).toContain('total_contract_arr_cents');
+                const page = await params.toolSet.read_repair_file.execute({
+                    path: 'wiki/global/account-segments.md',
+                });
+                expect(page.markdown).toContain('total_contract_arr_cents');
+                await expect(params.toolSet.write_repair_file.execute({
+                    path: 'wiki/global/other.md',
+                    content: 'not allowed',
+                })).rejects.toThrow(/gate repair path not allowed/);
+                await params.toolSet.write_repair_file.execute({
+                    path: 'wiki/global/account-segments.md',
+                    content: page.markdown.replace('total_contract_arr_cents', 'total_contract_arr'),
+                });
+                return { stopReason: 'natural' };
+            }),
+        };
+        const result = await repairFinalGateFailure({
+            agentRunner,
+            workdir,
+            gateError: 'final artifact gates failed:\naccount-segments: unknown semantic-layer entity mart_account_segments.total_contract_arr_cents',
+            allowedPaths: ['wiki/global/account-segments.md'],
+            trace,
+            repairKind: 'final_artifact_gate',
+            maxAttempts: 1,
+            stepBudget: 8,
+        });
+        expect(result).toEqual({
+            status: 'repaired',
+            attempts: 1,
+            changedPaths: ['wiki/global/account-segments.md'],
+        });
+        await expect(readFile(join(workdir, 'wiki/global/account-segments.md'), 'utf-8')).resolves.toContain('total_contract_arr');
+        await expect(readFile(trace.tracePath, 'utf-8')).resolves.toContain('gate_repair_repaired');
+        expect(agentRunner.runLoop).toHaveBeenCalledWith(expect.objectContaining({
+            modelRole: 'repair',
+            stepBudget: 8,
+            telemetryTags: expect.objectContaining({
+                operationName: 'ingest-isolated-diff-gate-repair',
+                repairKind: 'final_artifact_gate',
+            }),
+        }));
+    });
+    it('returns failed when the repair agent edits no allowed file', async () => {
+        const { workdir, trace } = await makeHarness();
+        const result = await repairFinalGateFailure({
+            agentRunner: { runLoop: vi.fn(async () => ({ stopReason: 'natural' })) },
+            workdir,
+            gateError: 'final artifact gates failed:\naccount-segments: unknown semantic-layer entity',
+            allowedPaths: ['wiki/global/account-segments.md'],
+            trace,
+            repairKind: 'final_artifact_gate',
+            maxAttempts: 1,
+            stepBudget: 8,
+        });
+        expect(result).toEqual({
+            status: 'failed',
+            attempts: 1,
+            reason: 'gate repair completed without editing an allowed path',
+        });
+        await expect(readFile(trace.tracePath, 'utf-8')).resolves.toContain('gate_repair_failed');
+    });
+});

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

@@ -4,6 +4,7 @@ export type { DaemonLiveDatabaseIntrospectionOptions, KtxDaemonDatabaseHttpJsonR
 export { createDaemonLiveDatabaseIntrospection } from './adapters/live-database/daemon-introspection.js';
 export type { LiveDatabaseExtractedColumn, LiveDatabaseExtractedForeignKey, LiveDatabaseExtractedSchema, LiveDatabaseExtractedTable, } from './adapters/live-database/extracted-schema.js';
 export { buildLiveDatabaseTableNaturalKey, ktxSchemaSnapshotToExtractedSchema, } from './adapters/live-database/extracted-schema.js';
+export { assertSemanticLayerTargetPathsAllowed, findDisallowedSemanticLayerTargetPaths, semanticLayerConnectionIdFromPath, } from './semantic-layer-target-policy.js';
 export { LiveDatabaseSourceAdapter } from './adapters/live-database/live-database.adapter.js';
 export type { BuildLiveDatabaseManifestShardsInput, BuildLiveDatabaseManifestShardsResult, LiveDatabaseManifestColumn, LiveDatabaseManifestExistingDescriptions, LiveDatabaseManifestJoinData, LiveDatabaseManifestJoinEntry, LiveDatabaseManifestShard, LiveDatabaseManifestTableData, LiveDatabaseManifestTableEntry, } from './adapters/live-database/manifest.js';
 export { buildLiveDatabaseManifestShards } from './adapters/live-database/manifest.js';
@@ -134,6 +135,11 @@ export type { CandidateDedupPort, CandidateDedupResult, ContextCandidateCarryfor
 export { buildSyncId, provenanceMarker, rawSourcesDirForSync, rawSourcesRoot, } from './raw-sources-paths.js';
 export { ingestReportSnapshotSchema, parseIngestReportSnapshot } from './report-snapshot.js';
 export type { IngestReportBody, IngestReportSnapshot } from './reports.js';
+export * from './artifact-gates.js';
+export * from './ingest-trace.js';
+export * from './isolated-diff/git-patch.js';
+export * from './isolated-diff/patch-integrator.js';
+export * from './isolated-diff/work-unit-executor.js';
 export * from './reports.js';
 export { SourceAdapterRegistry } from './source-adapter-registry.js';
 export type { SqliteBundleIngestStoreOptions } from './sqlite-bundle-ingest-store.js';
@@ -145,4 +151,5 @@ export { buildReconcileSystemPrompt, buildReconcileToolSet, buildReconcileUserPr
 export type { ReconciliationOutcome } from './stages/stage-4-reconciliation.js';
 export { runReconciliationStage4 } from './stages/stage-4-reconciliation.js';
 export type { StageIndex } from './stages/stage-index.types.js';
-export type { ChunkResult, DiffSet, EvictionUnit, FetchContext, IngestBundleJob, IngestBundleRef, IngestBundleResult, IngestDiffSummary, IngestJobContext, IngestJobPhase, IngestTrigger, ScopeDescriptor, SourceAdapter, SourceFetchIssue, SourceFetchReport, TriageLane, TriageSignals, UnresolvedCardInfo, WorkUnit, } from './types.js';
+export type { ChunkResult, DiffSet, EvictionUnit, FetchContext, IngestBundleJob, IngestBundleRef, IngestBundleResult, IngestDiffSummary, IngestJobContext, IngestJobPhase, IngestTrigger, ScopeDescriptor, SourceAdapter, SourceFetchIssue, SourceFetchReport, TriageLane, TriageSignals, UnresolvedCardInfo, WorkUnit, DeterministicProjectionContext, ProjectionResult, } from './types.js';
+export * from './wiki-body-refs.js';