@kaelio/ktx 0.11.0 → 0.13.0

package/dist/context/connections/resolve-connection.js

@@ -0,0 +1,37 @@
+import { KtxExpectedError } from '../../errors.js';
+function configuredConnectionIds(config) {
+    return Object.keys(config.connections).sort();
+}
+function availableConnectionsHint(config) {
+    const ids = configuredConnectionIds(config);
+    return ids.length === 0
+        ? 'No connections are configured in ktx.yaml.'
+        : `Configured connections: ${ids.join(', ')}.`;
+}
+/**
+ * Look up a connection by id, throwing an expected (caller-driven) error that
+ * names the configured connections so an agent or CLI user can self-correct.
+ */
+export function resolveConfiguredConnection(config, connectionId) {
+    const connection = config.connections[connectionId];
+    if (!connection) {
+        throw new KtxExpectedError(`Connection "${connectionId}" is not configured in ktx.yaml. ${availableConnectionsHint(config)}`);
+    }
+    return connection;
+}
+/**
+ * Resolve the connection id to run against: validate a requested id against the
+ * configured connections, or default to the sole connection when none is given.
+ * Throws an expected error that lists the configured connections otherwise.
+ */
+export function resolveRequiredConnectionId(config, requested) {
+    if (requested !== undefined) {
+        resolveConfiguredConnection(config, requested);
+        return requested;
+    }
+    const ids = configuredConnectionIds(config);
+    if (ids.length === 1) {
+        return ids[0];
+    }
+    throw new KtxExpectedError(`connectionId is required. ${availableConnectionsHint(config)}`);
+}

package/dist/context/core/git-env.d.ts

@@ -6,6 +6,10 @@ import { type SimpleGit } from 'simple-git';
  * directory is an existing repo ktx did not create and the machine has no configured git
  * identity (e.g. a fresh Mac with no ~/.gitconfig), without mutating the user's repo config.
  * Explicit `--author` flags on individual commits still take precedence over GIT_AUTHOR_NAME.
+ *
+ * `commit.gpgsign=false` is injected as a per-invocation `-c` override so ktx's commits never
+ * attempt GPG signing: ktx commits under a synthetic identity that can never own a secret key, so
+ * a user's `commit.gpgsign=true` would otherwise fail every commit with "No secret key".
  */
 export declare function createSimpleGit(baseDir: string, identity?: {
     name: string;

package/dist/context/core/git-env.js

@@ -28,6 +28,10 @@ function sanitizedGitEnv(env = process.env) {
  * directory is an existing repo ktx did not create and the machine has no configured git
  * identity (e.g. a fresh Mac with no ~/.gitconfig), without mutating the user's repo config.
  * Explicit `--author` flags on individual commits still take precedence over GIT_AUTHOR_NAME.
+ *
+ * `commit.gpgsign=false` is injected as a per-invocation `-c` override so ktx's commits never
+ * attempt GPG signing: ktx commits under a synthetic identity that can never own a secret key, so
+ * a user's `commit.gpgsign=true` would otherwise fail every commit with "No secret key".
  */
 export function createSimpleGit(baseDir, identity) {
     const env = sanitizedGitEnv();
@@ -37,5 +41,5 @@ export function createSimpleGit(baseDir, identity) {
         env.GIT_COMMITTER_NAME = identity.name;
         env.GIT_COMMITTER_EMAIL = identity.email;
     }
-    return simpleGit({ baseDir, unsafe: { allowUnsafeAskPass: true } }).env(env);
+    return simpleGit({ baseDir, config: ['commit.gpgsign=false'], unsafe: { allowUnsafeAskPass: true } }).env(env);
 }

package/dist/context/core/git.service.d.ts

@@ -20,6 +20,23 @@ export interface WorktreeEntry {
     branch: string | null;
     head: string | null;
 }
+export type KtxRepoOwnership = 'unowned' | 'ktx-managed' | 'foreign';
+export declare class KtxForeignGitRepositoryError extends Error {
+    constructor(configDir: string);
+}
+/**
+ * Classify whether ktx may own a git repository rooted exactly at `dir`. A root
+ * `ktx.yaml` is the ownership signal; the working tree decides, not git history,
+ * because older ktx versions left `ktx.yaml` uncommitted (it holds secret refs).
+ *
+ * - `unowned`: no repo here (including a missing or non-directory path) → ktx may `git init`.
+ * - `ktx-managed`: `<dir>/.git` is a directory and `ktx.yaml` sits at the root.
+ * - `foreign`: any other repo — no root `ktx.yaml`, or a `.git` *file* (a linked
+ *   worktree). ktx must never adopt or mutate it.
+ *
+ * Reads only `<dir>` itself; never walks up, so a parent repo cannot change the answer.
+ */
+export declare function classifyKtxRepoOwnership(dir: string): Promise<KtxRepoOwnership>;
 export type SquashMergeResult = {
     ok: true;
     squashSha: string;
@@ -102,6 +119,12 @@ export declare class GitService {
         path: string;
     }>>;
     changedPaths(): Promise<string[]>;
+    /**
+     * List all paths matching `pathSpec` as they exist at `commitHash`. Reads from
+     * git object storage, so it's safe against concurrent working-tree mutations
+     * and can recover paths (e.g. a human-renamed file) that no longer exist on disk.
+     */
+    listFilesAtCommit(pathSpec: string, commitHash: string): 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/dist/context/core/git.service.js

@@ -2,6 +2,53 @@ import { promises as fs } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { noopLogger, resolveConfigDir } from './config.js';
 import { createSimpleGit } from './git-env.js';
+export class KtxForeignGitRepositoryError extends Error {
+    constructor(configDir) {
+        super(`${configDir} is already a git repository that ktx did not create. ` +
+            'ktx maintains its context in a repository it owns; run ktx in a dedicated directory or move the existing repository aside.');
+        this.name = 'KtxForeignGitRepositoryError';
+    }
+}
+function isNodeErrnoException(error) {
+    return error instanceof Error && 'code' in error;
+}
+/**
+ * Classify whether ktx may own a git repository rooted exactly at `dir`. A root
+ * `ktx.yaml` is the ownership signal; the working tree decides, not git history,
+ * because older ktx versions left `ktx.yaml` uncommitted (it holds secret refs).
+ *
+ * - `unowned`: no repo here (including a missing or non-directory path) → ktx may `git init`.
+ * - `ktx-managed`: `<dir>/.git` is a directory and `ktx.yaml` sits at the root.
+ * - `foreign`: any other repo — no root `ktx.yaml`, or a `.git` *file* (a linked
+ *   worktree). ktx must never adopt or mutate it.
+ *
+ * Reads only `<dir>` itself; never walks up, so a parent repo cannot change the answer.
+ */
+export async function classifyKtxRepoOwnership(dir) {
+    let dotGitIsDirectory;
+    try {
+        dotGitIsDirectory = (await fs.lstat(join(dir, '.git'))).isDirectory();
+    }
+    catch (error) {
+        // ENOENT: `<dir>/.git` is absent. ENOTDIR: `<dir>` itself is a file, so it
+        // can hold no repo. Either way there is nothing for ktx to avoid here.
+        if (isNodeErrnoException(error) && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) {
+            return 'unowned';
+        }
+        throw error;
+    }
+    if (!dotGitIsDirectory) {
+        return 'foreign';
+    }
+    try {
+        // stat (not lstat): follow symlinks, matching what `loadKtxProject`'s
+        // readFile accepts — a dir that loads as a ktx project classifies as one.
+        return (await fs.stat(join(dir, 'ktx.yaml'))).isFile() ? 'ktx-managed' : 'foreign';
+    }
+    catch {
+        return 'foreign';
+    }
+}
 function mergeErrorMessage(error) {
     if (error instanceof Error) {
         return error.message;
@@ -58,12 +105,15 @@ export class GitService {
     }
     async initialize() {
         try {
-            // Check if already initialized
-            const isRepo = await this.git.checkIsRepo();
-            if (!isRepo) {
+            const ownership = await classifyKtxRepoOwnership(this.configDir);
+            if (ownership === 'foreign') {
+                throw new KtxForeignGitRepositoryError(this.configDir);
+            }
+            if (ownership === 'unowned') {
                 await this.git.init();
-                this.logger.log('Initialized git repository');
+                this.logger.log('Initialized ktx-managed git repository');
             }
+            // ownership === 'ktx-managed' → ktx's own repo; proceed with the normal re-run path.
             // Keep any auto-maintenance triggered by writes in-process. Detached maintenance can
             // keep object-pack directories alive briefly after awaited git commands complete,
             // which makes temp-project cleanup flaky in CI.
@@ -81,6 +131,11 @@ export class GitService {
             }
         }
         catch (error) {
+            // The foreign-repo error is already typed and actionable; surface it verbatim so every
+            // command that loads the project shows the same clear guidance instead of a generic wrapper.
+            if (error instanceof KtxForeignGitRepositoryError) {
+                throw error;
+            }
             this.logger.error('Failed to initialize git repository', error);
             // Preserve the underlying git error: the generic message alone is undiagnosable in
             // telemetry and unactionable for the user. The exception reporter walks `cause` and
@@ -442,12 +497,13 @@ export class GitService {
         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.
+     * List all paths matching `pathSpec` as they exist at `commitHash`. Reads from
+     * git object storage, so it's safe against concurrent working-tree mutations
+     * and can recover paths (e.g. a human-renamed file) that no longer exist on disk.
      */
-    async listFilesAtHead(pathSpec) {
+    async listFilesAtCommit(pathSpec, commitHash) {
         try {
-            const raw = await this.git.raw(['ls-tree', '-r', '-z', '--name-only', 'HEAD', '--', pathSpec]);
+            const raw = await this.git.raw(['ls-tree', '-r', '-z', '--name-only', commitHash, '--', pathSpec]);
             if (!raw) {
                 return [];
             }
@@ -457,6 +513,13 @@ export class GitService {
             return [];
         }
     }
+    /**
+     * 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.
+     */
+    async listFilesAtHead(pathSpec) {
+        return this.listFilesAtCommit(pathSpec, 'HEAD');
+    }
     /**
      * Collapse all commits between `preHead` and current HEAD into a single commit with the given
      * message. Used by the memory agent to squash N per-tool-call commits into one ingest commit.

package/dist/context/ingest/adapters/historic-sql/projection.js

@@ -2,6 +2,7 @@ import { access, mkdir, readdir, readFile, rename, writeFile } from 'node:fs/pro
 import { dirname, join, relative } from 'node:path';
 import YAML from 'yaml';
 import { rawSourcesDirForSync } from '../../raw-sources-paths.js';
+import { isSlYamlPath } from '../../../sl/source-files.js';
 import { mergeUsagePreservingExternal } from '../live-database/manifest.js';
 import { historicSqlEvidenceEnvelopeSchema } from './evidence.js';
 import { stagedManifestSchema } from './types.js';
@@ -197,7 +198,7 @@ export async function projectHistoricSqlEvidence(input) {
     const tableEvidence = evidence.filter((entry) => entry.kind === 'table_usage');
     const patternEvidence = evidence.filter((entry) => entry.kind === 'pattern');
     const schemaRoot = join(input.workdir, 'semantic-layer', input.connectionId, '_schema');
-    for (const file of (await walkFiles(schemaRoot)).filter((candidate) => candidate.endsWith('.yaml') || candidate.endsWith('.yml'))) {
+    for (const file of (await walkFiles(schemaRoot)).filter(isSlYamlPath)) {
         const path = join(schemaRoot, file);
         const before = await readFile(path, 'utf-8');
         const shard = (YAML.parse(before) ?? {});

package/dist/context/ingest/adapters/live-database/manifest.d.ts

@@ -56,11 +56,14 @@ export interface BuildLiveDatabaseManifestShardsInput {
     existingPreservedJoins?: Map<string, LiveDatabaseManifestJoinEntry[]>;
     existingDescriptions?: Map<string, LiveDatabaseManifestExistingDescriptions>;
     existingUsage?: Map<string, TableUsageOutput>;
+    federatedSiblingTargets?: Set<string>;
 }
 export interface BuildLiveDatabaseManifestShardsResult {
     shards: Map<string, LiveDatabaseManifestShard>;
     tablesProcessed: number;
 }
 export declare function mergeUsagePreservingExternal(existing: TableUsageOutput | undefined, incoming: TableUsageOutput | undefined): TableUsageOutput | undefined;
+/** @internal */
+export declare function buildJoinsByTable(tableNames: Set<string>, joins: LiveDatabaseManifestJoinData[], preservedJoins: Map<string, LiveDatabaseManifestJoinEntry[]>, federatedSiblingTargets?: Set<string>): Map<string, LiveDatabaseManifestJoinEntry[]>;
 export declare function buildLiveDatabaseManifestShards(input: BuildLiveDatabaseManifestShardsInput): BuildLiveDatabaseManifestShardsResult;
 export {};

package/dist/context/ingest/adapters/live-database/manifest.js

@@ -106,10 +106,14 @@ function joinCondition(leftTable, leftColumns, rightTable, rightColumns) {
     })
         .join(' AND ');
 }
-function buildJoinsByTable(tableNames, joins, preservedJoins) {
+/** @internal */
+export function buildJoinsByTable(tableNames, joins, preservedJoins, federatedSiblingTargets = new Set()) {
     const joinsByTable = new Map();
     for (const join of joins) {
-        if (!tableNames.has(join.fromTable) || !tableNames.has(join.toTable)) {
+        const fromLocal = tableNames.has(join.fromTable);
+        const toLocal = tableNames.has(join.toTable);
+        const toSibling = federatedSiblingTargets.has(join.toTable);
+        if (!fromLocal || (!toLocal && !toSibling)) {
             continue;
         }
         const relationship = RELATIONSHIP_MAP[join.relationship] ?? join.relationship;
@@ -119,20 +123,24 @@ function buildJoinsByTable(tableNames, joins, preservedJoins) {
             relationship,
             source: join.source,
         });
-        const reverseRelationship = RELATIONSHIP_INVERSE[relationship] ?? 'one_to_many';
-        addJoinOnce(joinsByTable, join.toTable, {
-            to: join.fromTable,
-            on: joinCondition(join.toTable, join.toColumns, join.fromTable, join.fromColumns),
-            relationship: reverseRelationship,
-            source: join.source,
-        });
+        // Reverse direction only when the target is a local table in THIS snapshot;
+        // a federated sibling has no shard here, so it gets no reverse entry.
+        if (toLocal) {
+            const reverseRelationship = RELATIONSHIP_INVERSE[relationship] ?? 'one_to_many';
+            addJoinOnce(joinsByTable, join.toTable, {
+                to: join.fromTable,
+                on: joinCondition(join.toTable, join.toColumns, join.fromTable, join.fromColumns),
+                relationship: reverseRelationship,
+                source: join.source,
+            });
+        }
     }
     for (const [tableName, tableJoins] of preservedJoins) {
         if (!tableNames.has(tableName)) {
             continue;
         }
         for (const join of tableJoins) {
-            if (tableNames.has(join.to)) {
+            if (tableNames.has(join.to) || federatedSiblingTargets.has(join.to)) {
                 addJoinOnce(joinsByTable, tableName, join);
             }
         }
@@ -141,7 +149,7 @@ function buildJoinsByTable(tableNames, joins, preservedJoins) {
 }
 export function buildLiveDatabaseManifestShards(input) {
     const tableNames = new Set(input.tables.map((table) => table.name));
-    const joinsByTable = buildJoinsByTable(tableNames, input.joins, input.existingPreservedJoins ?? new Map());
+    const joinsByTable = buildJoinsByTable(tableNames, input.joins, input.existingPreservedJoins ?? new Map(), input.federatedSiblingTargets ?? new Set());
     const shards = new Map();
     for (const table of input.tables) {
         const shardKey = getShardKey(input.connectionType, table.catalog, table.db);

package/dist/context/ingest/adapters/looker/client.js

@@ -12,13 +12,18 @@ const defaultLogger = {
 class InlineLookerSettings extends NodeSettings {
     params;
     constructor(params) {
-        super('', {
+        // @looker/sdk-rtl boundary: NodeSettings consumes a string-valued config
+        // section (read back via the readConfig override below), but its constructor
+        // is typed to accept a fully-realized IApiSettings. The string record is the
+        // shape the library actually reads, so narrow to IApiSection first.
+        const settings = {
             base_url: normalizeBaseUrl(params.base_url),
             client_id: params.client_id,
             client_secret: params.client_secret, // pragma: allowlist secret
             verify_ssl: 'true',
             timeout: '120',
-        });
+        };
+        super('', settings);
         this.params = params;
     }
     readConfig(_section) {

package/dist/context/ingest/adapters/looker/factory.d.ts

@@ -1,5 +1,5 @@
 import type { FetchContext } from '../../types.js';
-import { type LookerClientDeps, type LookerConnectionParams } from './client.js';
+import { LookerClient, type LookerClientDeps, type LookerConnectionParams } from './client.js';
 import type { LookerClientFactory, LookerRuntimeClient } from './fetch.js';
 import type { LookerPullConfig } from './types.js';
 export interface LookerCredentialResolver {
@@ -14,6 +14,13 @@ export declare class DefaultLookerConnectionClientFactory implements LookerConne
     private readonly deps;
     constructor(resolver: LookerCredentialResolver, deps?: LookerClientDeps);
     createClient(lookerConnectionId: string): Promise<LookerRuntimeClient>;
+    /**
+     * Like {@link createClient} but preserves the concrete {@link LookerClient}
+     * type, so callers that need methods outside the `LookerRuntimeClient`
+     * contract (e.g. `listLookerConnections`, `testConnection`) keep them without
+     * a cast.
+     */
+    createLookerClient(lookerConnectionId: string): Promise<LookerClient>;
 }
 /** @internal */
 export declare class DefaultLookerClientFactory implements LookerClientFactory {

package/dist/context/ingest/adapters/looker/factory.js

@@ -7,6 +7,15 @@ export class DefaultLookerConnectionClientFactory {
         this.deps = deps;
     }
     async createClient(lookerConnectionId) {
+        return this.createLookerClient(lookerConnectionId);
+    }
+    /**
+     * Like {@link createClient} but preserves the concrete {@link LookerClient}
+     * type, so callers that need methods outside the `LookerRuntimeClient`
+     * contract (e.g. `listLookerConnections`, `testConnection`) keep them without
+     * a cast.
+     */
+    async createLookerClient(lookerConnectionId) {
         const credentials = await this.resolver.resolve(lookerConnectionId);
         return new LookerClient(credentials, this.deps);
     }

package/dist/context/ingest/adapters/looker/mapping.js

@@ -120,7 +120,7 @@ export function validateLookerMappings(args) {
         if (!args.knownKtxConnectionIds.has(mapping.ktxConnectionId)) {
             errors.push({
                 key: mapping.lookerConnectionName,
-                reason: `KTX connection ${mapping.ktxConnectionId} does not exist`,
+                reason: `ktx connection ${mapping.ktxConnectionId} does not exist`,
             });
             continue;
         }

package/dist/context/ingest/adapters/looker/types.d.ts

@@ -12,6 +12,7 @@ export declare const lookerPullConfigSchema: z.ZodObject<{
     lookUpdatedSince: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
     connectionMappings: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     connectionTypes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        PLAIN: "PLAIN";
         BIGQUERY: "BIGQUERY";
         SNOWFLAKE: "SNOWFLAKE";
         MYSQL: "MYSQL";
@@ -31,7 +32,6 @@ export declare const lookerPullConfigSchema: z.ZodObject<{
         METABASE: "METABASE";
         LOOKER: "LOOKER";
         NOTION: "NOTION";
-        PLAIN: "PLAIN";
         BETTERSTACK: "BETTERSTACK";
     }>>>;
     parsedTargetTables: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{

package/dist/context/ingest/adapters/metabase/client.d.ts

@@ -18,7 +18,7 @@ export declare const DEFAULT_METABASE_CLIENT_CONFIG: MetabaseClientConfig;
  * Strip Metabase `[[ ... {{ var }} ... ]]` optional-clause blocks from native SQL.
  *
  * The bracketed blocks are emitted only when the embedded `{{ var }}` is supplied at
- * Metabase query time. For KTX semantic-layer ingest there's no such runtime
+ * Metabase query time. For ktx semantic-layer ingest there's no such runtime
  * parameter — chat-time filters are composed by the SL query planner — so the optional
  * block must be removed before the SQL becomes a permanent SL source. Substituting a
  * dummy value (the alternative) bakes a placeholder filter into the source and silently

package/dist/context/ingest/adapters/metabase/client.js

@@ -30,7 +30,7 @@ class MetabaseApiError extends Error {
  * Strip Metabase `[[ ... {{ var }} ... ]]` optional-clause blocks from native SQL.
  *
  * The bracketed blocks are emitted only when the embedded `{{ var }}` is supplied at
- * Metabase query time. For KTX semantic-layer ingest there's no such runtime
+ * Metabase query time. For ktx semantic-layer ingest there's no such runtime
  * parameter — chat-time filters are composed by the SL query planner — so the optional
  * block must be removed before the SQL becomes a permanent SL source. Substituting a
  * dummy value (the alternative) bakes a placeholder filter into the source and silently

package/dist/context/ingest/adapters/metabase/local-metabase.adapter.js

@@ -15,7 +15,7 @@ export function metabaseRuntimeConfigFromLocalConnection(connectionId, connectio
         throw new Error(`Connection "${connectionId}" is not a Metabase connection`);
     }
     if (hasNetworkProxy(connection)) {
-        throw new Error(`Standalone KTX does not support proxy-bearing Metabase connections yet. Use hosted Metabase ingest for "${connectionId}" until the KTX Metabase proxy support spec lands.`);
+        throw new Error(`Standalone ktx does not support proxy-bearing Metabase connections yet. Use hosted Metabase ingest for "${connectionId}" until the ktx Metabase proxy support spec lands.`);
     }
     const apiUrl = stringField(connection.api_url);
     const literalApiKey = stringField(connection.api_key);

package/dist/context/ingest/adapters/metabase/mapping.js

@@ -93,7 +93,7 @@ export function validateMetabaseMappings(args) {
             continue;
         }
         if (!args.knownKtxConnectionIds.has(connectionId)) {
-            errors.push({ key, reason: `KTX connection ${connectionId} does not exist` });
+            errors.push({ key, reason: `ktx connection ${connectionId} does not exist` });
         }
     }
     return errors.length === 0 ? { ok: true } : { ok: false, errors };
@@ -108,13 +108,13 @@ export function validateMappingPhysicalMatch(mapping, target) {
         return null;
     }
     if (target.connection_type !== expectedType) {
-        return `Metabase database engine '${engine}' does not match KTX connection type '${target.connection_type}'`;
+        return `Metabase database engine '${engine}' does not match ktx connection type '${target.connection_type}'`;
     }
     const metabaseDb = normalizeName(mapping.metabaseDbName);
     const targetDb = normalizeName(getTargetDatabase(target));
     if (engine === 'snowflake' || engine === 'bigquery' || engine === 'bigquery-cloud-sdk') {
         if (metabaseDb && targetDb && metabaseDb !== targetDb) {
-            return `Metabase database '${mapping.metabaseDbName}' does not match KTX connection database '${displayValue(getTargetDatabase(target))}'`;
+            return `Metabase database '${mapping.metabaseDbName}' does not match ktx connection database '${displayValue(getTargetDatabase(target))}'`;
         }
         return null;
     }
@@ -122,10 +122,10 @@ export function validateMappingPhysicalMatch(mapping, target) {
         const metabaseHost = normalizeHost(mapping.metabaseHost);
         const targetHost = normalizeHost(target.host);
         if (metabaseHost && targetHost && metabaseHost !== targetHost) {
-            return `Metabase host '${mapping.metabaseHost}' does not match KTX connection host '${displayValue(target.host)}'`;
+            return `Metabase host '${mapping.metabaseHost}' does not match ktx connection host '${displayValue(target.host)}'`;
         }
         if (metabaseDb && targetDb && metabaseDb !== targetDb) {
-            return `Metabase database '${mapping.metabaseDbName}' does not match KTX connection database '${displayValue(getTargetDatabase(target))}'`;
+            return `Metabase database '${mapping.metabaseDbName}' does not match ktx connection database '${displayValue(getTargetDatabase(target))}'`;
         }
         return null;
     }
@@ -157,7 +157,7 @@ export async function refreshMetabaseMapping(args) {
         if (!target) {
             physicalMismatches.push({
                 mappingId: String(mapping.id),
-                reason: `KTX connection ${mapping.ktxConnectionId} does not exist`,
+                reason: `ktx connection ${mapping.ktxConnectionId} does not exist`,
             });
             continue;
         }

package/dist/context/ingest/artifact-gates.d.ts

@@ -1,17 +1,14 @@
 import type { SemanticLayerService } from '../../context/sl/semantic-layer.service.js';
 import type { TouchedSlSource } from '../../context/tools/touched-sl-sources.js';
 import type { KnowledgeWikiService } from '../../context/wiki/knowledge-wiki.service.js';
-interface TouchedValidationResult {
-    invalidSources: string[];
-    validSources: string[];
-}
+import type { WuValidationResult } from './stages/validate-wu-sources.js';
 export interface FinalArtifactGateInput {
     connectionIds: string[];
     changedWikiPageKeys: string[];
     touchedSlSources: TouchedSlSource[];
     wikiService: KnowledgeWikiService;
     semanticLayerService: SemanticLayerService;
-    validateTouchedSources(touched: TouchedSlSource[]): Promise<TouchedValidationResult>;
+    validateTouchedSources(touched: TouchedSlSource[]): Promise<WuValidationResult>;
     tableExists(connectionId: string, tableRef: string): Promise<boolean>;
 }
 export interface ProvenanceRawPathValidationInput {
@@ -23,4 +20,3 @@ export interface ProvenanceRawPathValidationInput {
 }
 export declare function validateFinalIngestArtifacts(input: FinalArtifactGateInput): Promise<void>;
 export declare function validateProvenanceRawPaths(input: ProvenanceRawPathValidationInput): void;
-export {};

package/dist/context/ingest/artifact-gates.js

@@ -13,50 +13,6 @@ function slEntityNames(source) {
         ...(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();
@@ -112,9 +68,11 @@ async function validateWikiRefs(input) {
     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}`);
+    // Join-neighbor expansion happens inside validateTouchedSources so work-unit
+    // validation and this gate check the same set — a source that passes one
+    // passes the other.
+    const validation = await input.validateTouchedSources(input.touchedSlSources);
+    const errors = validation.invalidSources.map((invalid) => `semantic-layer validation failed for ${invalid.source}: ${invalid.errors.join('; ')}`);
     errors.push(...(await validateWikiSlRefs(input)));
     const danglingWikiRefs = await validateWikiRefs(input);
     if (danglingWikiRefs.length > 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>;