@kaelio/ktx 0.10.0 → 0.12.0

package/dist/context/ingest/constrained-repair.d.ts

@@ -0,0 +1,55 @@
+import type { AgentRunnerPort, KtxRuntimeToolSet } from '../../context/llm/runtime-port.js';
+import type { IngestTraceWriter } from './ingest-trace.js';
+/**
+ * Shared loop for the two integration-time repair agents (semantic gate
+ * repair, textual conflict resolution). Success is decided by re-running the
+ * failed check — `verify` — never by whether the agent edited files: an
+ * ineffective edit fails, and an explicit no-change declaration that verifies
+ * succeeds.
+ */
+export type RepairVerification = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export type ConstrainedRepairResult = {
+    status: 'repaired';
+    attempts: number;
+    changedPaths: string[];
+} | {
+    status: 'failed';
+    attempts: number;
+    reason: string;
+};
+export interface ConstrainedRepairToolContext {
+    workdir: string;
+    allowedPaths: ReadonlySet<string>;
+    editedPaths: Set<string>;
+    declareNoChange(reason: string): void;
+}
+export interface ConstrainedRepairLoopInput {
+    agentRunner: AgentRunnerPort;
+    workdir: string;
+    allowedPaths: string[];
+    trace: IngestTraceWriter;
+    tracePhase: string;
+    traceEventName: string;
+    traceData: Record<string, unknown>;
+    systemPrompt: string;
+    buildUserPrompt(input: {
+        attempt: number;
+        maxAttempts: number;
+        previousFailure: string | null;
+    }): string;
+    buildExtraTools?(context: ConstrainedRepairToolContext): KtxRuntimeToolSet;
+    verify(changedPaths: string[]): Promise<RepairVerification>;
+    /** Failure reason when an attempt neither edits nor declares no-change. */
+    noChangeFailureReason: string;
+    telemetryTags: Record<string, string>;
+    maxAttempts?: number;
+    stepBudget?: number;
+    abortSignal?: AbortSignal;
+}
+export declare function buildDeleteRepairFileTool(context: ConstrainedRepairToolContext): KtxRuntimeToolSet;
+export declare function runConstrainedRepairLoop(input: ConstrainedRepairLoopInput): Promise<ConstrainedRepairResult>;

package/dist/context/ingest/constrained-repair.js

@@ -0,0 +1,167 @@
+import { mkdir, readFile, rm, 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(`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(`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 buildRepairFileTools(context) {
+    return {
+        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, context.allowedPaths);
+                const file = await readOptionalFile(join(context.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, context.allowedPaths);
+                const fullPath = join(context.workdir, normalized);
+                await mkdir(dirname(fullPath), { recursive: true });
+                await writeFile(fullPath, content, 'utf-8');
+                context.editedPaths.add(normalized);
+                return {
+                    markdown: `Wrote ${normalized}`,
+                    structured: { path: normalized, bytes: Buffer.byteLength(content) },
+                };
+            },
+        },
+    };
+}
+export function buildDeleteRepairFileTool(context) {
+    const deleteRepairFileSchema = z.object({
+        path: z.string().min(1),
+    });
+    return {
+        delete_repair_file: {
+            name: 'delete_repair_file',
+            description: 'Delete one allowed integration worktree file when the failed patch proves the deletion is correct.',
+            inputSchema: deleteRepairFileSchema,
+            execute: async ({ path }) => {
+                const normalized = assertAllowedPath(path, context.allowedPaths);
+                await rm(join(context.workdir, normalized), { force: true });
+                context.editedPaths.add(normalized);
+                return {
+                    markdown: `Deleted ${normalized}`,
+                    structured: { path: normalized },
+                };
+            },
+        },
+    };
+}
+export async function runConstrainedRepairLoop(input) {
+    const allowedPaths = new Set(input.allowedPaths.map(normalizeRepoPath));
+    const sortedAllowedPaths = [...allowedPaths].sort();
+    const maxAttempts = input.maxAttempts ?? 2;
+    const stepBudget = input.stepBudget ?? 16;
+    // Edits persist in the worktree across attempts, so the verified set and the
+    // reported changedPaths accumulate over the whole loop.
+    const editedPaths = new Set();
+    let lastFailure = 'repair did not run';
+    let previousFailure = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        let noChangeDeclaration = null;
+        const toolContext = {
+            workdir: input.workdir,
+            allowedPaths,
+            editedPaths,
+            declareNoChange: (reason) => {
+                noChangeDeclaration = reason;
+            },
+        };
+        const traceData = {
+            ...input.traceData,
+            attempt,
+            maxAttempts,
+            allowedPaths: sortedAllowedPaths,
+        };
+        const result = await traceTimed(input.trace, input.tracePhase, input.traceEventName, traceData, async () => input.agentRunner.runLoop({
+            modelRole: 'repair',
+            systemPrompt: input.systemPrompt,
+            userPrompt: input.buildUserPrompt({ attempt, maxAttempts, previousFailure }),
+            toolSet: {
+                ...buildRepairFileTools(toolContext),
+                ...(input.buildExtraTools?.(toolContext) ?? {}),
+            },
+            stepBudget,
+            telemetryTags: input.telemetryTags,
+            abortSignal: input.abortSignal,
+        }));
+        if (result.stopReason === 'error') {
+            lastFailure = result.error?.message ?? 'repair agent loop errored';
+            previousFailure = lastFailure;
+            await input.trace.event('error', input.tracePhase, `${input.traceEventName}_failed`, traceData, result.error);
+            continue;
+        }
+        const changedPaths = [...editedPaths].sort();
+        if (changedPaths.length === 0 && noChangeDeclaration === null) {
+            // Nothing changed and nothing was claimed: the failed check would fail
+            // identically, so skip verification and retry.
+            lastFailure = input.noChangeFailureReason;
+            previousFailure = lastFailure;
+            await input.trace.event('error', input.tracePhase, `${input.traceEventName}_failed`, {
+                ...traceData,
+                reason: lastFailure,
+            });
+            continue;
+        }
+        const verification = await input.verify(changedPaths);
+        if (!verification.ok) {
+            lastFailure = verification.reason;
+            previousFailure = lastFailure;
+            await input.trace.event('error', input.tracePhase, `${input.traceEventName}_failed`, {
+                ...traceData,
+                changedPaths,
+                reason: lastFailure,
+            });
+            continue;
+        }
+        await input.trace.event('debug', input.tracePhase, `${input.traceEventName}_repaired`, {
+            ...traceData,
+            changedPaths,
+            ...(noChangeDeclaration !== null ? { noChangeDeclaration } : {}),
+        });
+        return { status: 'repaired', attempts: attempt, changedPaths };
+    }
+    return { status: 'failed', attempts: maxAttempts, reason: lastFailure };
+}

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

@@ -1,16 +1,8 @@
 import type { AgentRunnerPort } from '../../context/llm/runtime-port.js';
-import type { TouchedSlSource } from '../../context/tools/touched-sl-sources.js';
+import type { ConstrainedRepairResult, RepairVerification } from './constrained-repair.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 type FinalGateRepairResult = ConstrainedRepairResult;
 export interface RepairFinalGateFailureInput {
     agentRunner: AgentRunnerPort;
     workdir: string;
@@ -18,13 +10,19 @@ export interface RepairFinalGateFailureInput {
     allowedPaths: string[];
     trace: IngestTraceWriter;
     repairKind: FinalGateRepairKind;
+    /**
+     * Re-runs the failed gate against the current worktree. The repair counts
+     * as successful only when this passes — editing files is not the success
+     * signal.
+     */
+    verify(changedPaths: string[]): Promise<RepairVerification>;
     maxAttempts?: number;
     stepBudget?: number;
     abortSignal?: AbortSignal;
 }
 export declare function finalGateRepairPaths(input: {
     changedWikiPageKeys: string[];
-    touchedSlSources: TouchedSlSource[];
+    touchedSlSourcePaths: string[];
 }): string[];
 export declare function repairFinalGateFailure(input: RepairFinalGateFailureInput): Promise<FinalGateRepairResult>;
 export {};

package/dist/context/ingest/final-gate-repair.js

@@ -1,43 +1,8 @@
-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;
-    }
-}
+import { runConstrainedRepairLoop } from './constrained-repair.js';
 function buildGateRepairSystemPrompt() {
     return `<role>
-You repair one KTX isolated-diff artifact gate failure inside the integration worktree.
+You repair one ktx isolated-diff artifact gate failure inside the integration worktree.
 </role>
 
 <rules>
@@ -51,6 +16,9 @@ You repair one KTX isolated-diff artifact gate failure inside the integration wo
 </rules>`;
 }
 function buildGateRepairUserPrompt(input) {
+    const previousFailureBlock = input.previousFailure
+        ? `\nPrevious attempt did not pass the gate:\n${input.previousFailure}\n`
+        : '';
     return `Repair isolated-diff artifact gates.
 
 Repair kind: ${input.repairKind}
@@ -61,119 +29,63 @@ ${input.allowedPaths.map((path) => `- ${path}`).join('\n')}
 
 Gate error:
 ${input.gateError}
-
+${previousFailureBlock}
 Use read_gate_error first. Then inspect only the allowed files, write the
 minimal repaired content, and stop.`;
 }
-function buildToolSet(input) {
+function buildReadGateErrorTool(gateError) {
     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 },
+                markdown: gateError,
+                structured: { 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.touchedSlSourcePaths,
             ...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 = {
+    return runConstrainedRepairLoop({
+        agentRunner: input.agentRunner,
+        workdir: input.workdir,
+        allowedPaths: input.allowedPaths,
+        trace: input.trace,
+        tracePhase: 'gate_repair',
+        traceEventName: 'gate_repair',
+        traceData: {
+            repairKind: input.repairKind,
+            gateError: input.gateError,
+        },
+        systemPrompt: buildGateRepairSystemPrompt(),
+        buildUserPrompt: ({ attempt, maxAttempts, previousFailure }) => buildGateRepairUserPrompt({
+            gateError: input.gateError,
+            allowedPaths: [...input.allowedPaths].sort(),
             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,
-            },
-            abortSignal: input.abortSignal,
-        }));
-        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 };
+            previousFailure,
+        }),
+        buildExtraTools: () => buildReadGateErrorTool(input.gateError),
+        verify: input.verify,
+        noChangeFailureReason: 'gate repair completed without editing an allowed path',
+        telemetryTags: {
+            operationName: 'ingest-isolated-diff-gate-repair',
+            source: input.trace.context.sourceKey,
+            jobId: input.trace.context.jobId,
+            repairKind: input.repairKind,
+        },
+        maxAttempts: input.maxAttempts,
+        stepBudget: input.stepBudget ?? 16,
+        abortSignal: input.abortSignal,
+    });
 }

package/dist/context/ingest/finalization-scope.d.ts

@@ -17,6 +17,6 @@ interface CompareFinalizationDeclarationsInput {
     derivedChangedWikiPageKeys: string[];
 }
 export declare function deriveFinalizationWikiPageKeys(paths: string[]): string[];
-export declare function deriveFinalizationTouchedSources(input: DeriveTouchedSourcesInput): Promise<DeriveTouchedSourcesResult>;
+export declare function deriveFinalizationTouchedSources(input: DeriveTouchedSourcesInput): DeriveTouchedSourcesResult;
 export declare function compareFinalizationDeclarations(input: CompareFinalizationDeclarationsInput): IngestReportFinalizationMismatch[];
 export {};

package/dist/context/ingest/finalization-scope.js

@@ -1,3 +1,4 @@
+import { isSlYamlPath } from '../../context/sl/source-files.js';
 function uniqueSorted(values) {
     return [...new Set(values.filter((value) => value.length > 0))].sort();
 }
@@ -28,32 +29,31 @@ export function deriveFinalizationWikiPageKeys(paths) {
         .filter((path) => !path.slice('wiki/global/'.length, -'.md'.length).includes('/'))
         .map((path) => path.slice('wiki/global/'.length, -'.md'.length)));
 }
-export async function deriveFinalizationTouchedSources(input) {
+// Source identity is the in-file `name:`; filenames are derived labels (see
+// source-files.ts), so a changed path — manifest shard or standalone file —
+// cannot be mapped to a source by parsing its filename. Instead, every changed
+// semantic-layer file is attributed through the before/after diff of its
+// connection's composed sources. A changed file whose connection diff is empty
+// cannot be attributed to any source and is surfaced as unresolved.
+export function deriveFinalizationTouchedSources(input) {
     const touched = new Map();
     const unresolvedPaths = [];
+    const pathsByConnection = new Map();
     for (const path of input.changedPaths) {
-        if (!path.startsWith('semantic-layer/') || !(path.endsWith('.yaml') || path.endsWith('.yml'))) {
+        if (!path.startsWith('semantic-layer/') || !isSlYamlPath(path)) {
             continue;
         }
-        const parts = path.split('/');
-        const connectionId = parts[1] ?? '';
+        const connectionId = path.split('/')[1] ?? '';
         if (!connectionId) {
             unresolvedPaths.push(path);
             continue;
         }
-        if (parts[2] !== '_schema') {
-            const fileName = parts.at(-1) ?? '';
-            const sourceName = fileName.replace(/\.ya?ml$/, '');
-            if (!sourceName) {
-                unresolvedPaths.push(path);
-                continue;
-            }
-            touched.set(`${connectionId}:${sourceName}`, { connectionId, sourceName });
-            continue;
-        }
+        pathsByConnection.set(connectionId, [...(pathsByConnection.get(connectionId) ?? []), path]);
+    }
+    for (const [connectionId, paths] of pathsByConnection) {
         const changedNames = changedSourceNames(input.beforeSourcesByConnection.get(connectionId) ?? [], input.afterSourcesByConnection.get(connectionId) ?? []);
         if (changedNames.length === 0) {
-            unresolvedPaths.push(path);
+            unresolvedPaths.push(...paths);
             continue;
         }
         for (const sourceName of changedNames) {

package/dist/context/ingest/ingest-bundle.runner.d.ts

@@ -55,6 +55,7 @@ export declare class IngestBundleRunner {
     private provenanceValidationTraceData;
     private wikiPageKeysFromPaths;
     private touchedSlSourcesFromPaths;
+    private touchedSlSourcePaths;
     private touchedSlSourcesFromActions;
     private wikiPageKeysFromActions;
     private uniqueWikiPageKeys;