@kaelio/ktx 0.13.1 → 0.15.0

package/dist/context/ingest/adapters/sigma/project.js

@@ -0,0 +1,186 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { sigmaProjectionConfigSchema, stagedDataModelFileSchema, STAGED_FILES } from './types.js';
+async function readProjectionConfig(stagedDir) {
+    try {
+        const body = await readFile(join(stagedDir, STAGED_FILES.projectionConfig), 'utf-8');
+        return sigmaProjectionConfigSchema.parse(JSON.parse(body)).connectionMappings;
+    }
+    catch {
+        return {};
+    }
+}
+const SIGMA_AUTHOR = { name: 'Sigma', email: 'system@kaelio.dev' };
+// Best-effort schema for the raw spec blob stored in staged data model files.
+const warehouseTableSourceSchema = z.object({
+    kind: z.literal('warehouse-table'),
+    connectionId: z.string(),
+    path: z.array(z.string()),
+});
+const specColumnSchema = z
+    .object({
+    id: z.string(),
+    formula: z.string().optional(),
+    name: z.string().optional(),
+    hidden: z.boolean().optional(),
+    description: z.string().optional(),
+    format: z.object({ kind: z.string() }).passthrough().optional(),
+})
+    .passthrough();
+const specElementSchema = z
+    .object({
+    id: z.string(),
+    kind: z.string().optional(),
+    name: z.string().optional(),
+    hidden: z.boolean().optional(),
+    source: z.object({ kind: z.string() }).passthrough().optional(),
+    columns: z.array(specColumnSchema).optional(),
+})
+    .passthrough();
+const specPageSchema = z
+    .object({
+    id: z.string(),
+    name: z.string().optional(),
+    elements: z.array(specElementSchema).optional(),
+})
+    .passthrough();
+const sigmaSpecSchema = z
+    .object({
+    name: z.string().optional(),
+    pages: z.array(specPageSchema).optional(),
+})
+    .passthrough();
+/** Extract the column name from a bracket formula like `[TABLE/Column Name]` or `[Column]`. */
+function extractColumnName(formula) {
+    const match = /\[(?:[^\]/]+\/)?([^\]]+)\]/.exec(formula.trim());
+    return match?.[1] ?? null;
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function inferColumnType(col) {
+    const kind = col.format?.kind;
+    if (kind === 'datetime' || kind === 'date')
+        return 'time';
+    if (kind === 'number' || kind === 'currency' || kind === 'percent')
+        return 'number';
+    return 'string';
+}
+function buildSourceFromElement(dataModelName, elementName, elementId, warehousePath, columns) {
+    const table = warehousePath.join('.');
+    if (!table)
+        return null;
+    const modelSlug = slugify(dataModelName || elementId);
+    const elemSlug = elementName ? slugify(elementName) : '';
+    const sourceName = elemSlug && elemSlug !== modelSlug ? `${modelSlug}_${elemSlug}` : modelSlug;
+    if (!sourceName)
+        return null;
+    const slColumns = [];
+    for (const col of columns) {
+        if (col.hidden)
+            continue;
+        if (!col.formula)
+            continue;
+        // Aggregation formulas (Sum, Count, etc.) are Sigma-specific expressions that don't map to
+        // warehouse columns — skip them silently. The sigma_ingest skill surfaces them as wiki candidates.
+        if (/^[A-Za-z]+\(/.test(col.formula.trim()))
+            continue;
+        const displayName = col.name ?? extractColumnName(col.formula);
+        if (!displayName)
+            continue;
+        const colSlug = slugify(displayName);
+        if (!colSlug)
+            continue;
+        slColumns.push({
+            name: colSlug,
+            type: inferColumnType(col),
+            ...(col.description ? { descriptions: { user: col.description } } : {}),
+        });
+    }
+    const source = {
+        name: sourceName,
+        table,
+        grain: [],
+        columns: slColumns,
+        joins: [],
+        measures: [],
+    };
+    if (dataModelName) {
+        source.descriptions = { user: dataModelName };
+    }
+    return source;
+}
+/** @internal */
+export async function projectSigmaDataModels(ctx, slService) {
+    const svc = ctx.workdir ? slService.forWorktree(ctx.workdir) : slService;
+    const warnings = [];
+    const errors = [];
+    const touchedSources = [];
+    const connectionMappings = await readProjectionConfig(ctx.stagedDir);
+    const dmDir = join(ctx.stagedDir, STAGED_FILES.dataModelsDir);
+    let entries;
+    try {
+        entries = await readdir(dmDir);
+    }
+    catch {
+        return { warnings, errors, touchedSources, changedWikiPageKeys: [] };
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        let stagedFile;
+        try {
+            const body = await readFile(join(dmDir, entry), 'utf-8');
+            stagedFile = stagedDataModelFileSchema.parse(JSON.parse(body));
+        }
+        catch {
+            warnings.push(`Skipping malformed staged file: ${entry}`);
+            continue;
+        }
+        if (!stagedFile.spec)
+            continue;
+        let spec;
+        try {
+            spec = sigmaSpecSchema.parse(stagedFile.spec);
+        }
+        catch {
+            warnings.push(`Skipping unparseable spec for data model "${stagedFile.name}"`);
+            continue;
+        }
+        for (const page of spec.pages ?? []) {
+            for (const element of page.elements ?? []) {
+                if (element.hidden)
+                    continue;
+                const warehouseSource = warehouseTableSourceSchema.safeParse(element.source);
+                if (!warehouseSource.success)
+                    continue;
+                const source = buildSourceFromElement(stagedFile.name, element.name, element.id, warehouseSource.data.path, element.columns ?? []);
+                if (!source)
+                    continue;
+                // Only write SL sources for elements whose Sigma connection is mapped to a warehouse connection.
+                // Writing under an unmapped connection produces gate failures because the Sigma connection
+                // is not a warehouse connection and cannot be validated.
+                const targetConnectionId = connectionMappings[warehouseSource.data.connectionId];
+                if (!targetConnectionId) {
+                    warnings.push(`Skipping SL source for "${stagedFile.name}" / "${element.name ?? element.id}": ` +
+                        `no connectionMappings entry for Sigma connection ${warehouseSource.data.connectionId}. ` +
+                        `Add a connectionMappings entry in ktx.yaml to enable SL projection for this element.`);
+                    continue;
+                }
+                try {
+                    const result = await svc.writeSource(targetConnectionId, source, SIGMA_AUTHOR.name, SIGMA_AUTHOR.email, `Sigma: import data model "${stagedFile.name}"`);
+                    touchedSources.push({ connectionId: targetConnectionId, sourceName: source.name });
+                    warnings.push(...result.warnings);
+                }
+                catch (err) {
+                    errors.push(`Failed to write source "${source.name}": ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    return { warnings, errors, touchedSources, changedWikiPageKeys: [] };
+}

package/dist/context/ingest/adapters/sigma/sigma.adapter.d.ts

@@ -0,0 +1,18 @@
+import type { ChunkResult, DeterministicProjectionContext, DiffSet, FetchContext, ProjectionResult, SourceAdapter } from '../../types.js';
+import type { SigmaClientFactory } from './client-port.js';
+import { type SigmaFetchLogger } from './fetch.js';
+export interface SigmaSourceAdapterDeps {
+    clientFactory: SigmaClientFactory;
+    logger?: SigmaFetchLogger;
+}
+export declare class SigmaSourceAdapter implements SourceAdapter {
+    private readonly deps;
+    readonly source = "sigma";
+    readonly skillNames: string[];
+    constructor(deps: SigmaSourceAdapterDeps);
+    detect(stagedDir: string): Promise<boolean>;
+    fetch(pullConfig: unknown, stagedDir: string, ctx: FetchContext): Promise<void>;
+    chunk(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
+    listTargetConnectionIds(stagedDir: string): Promise<string[]>;
+    project(ctx: DeterministicProjectionContext): Promise<ProjectionResult>;
+}

package/dist/context/ingest/adapters/sigma/sigma.adapter.js

@@ -0,0 +1,43 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { chunkSigmaStagedDir } from './chunk.js';
+import { detectSigmaStagedDir } from './detect.js';
+import { fetchSigmaBundle } from './fetch.js';
+import { projectSigmaDataModels } from './project.js';
+import { sigmaProjectionConfigSchema, STAGED_FILES } from './types.js';
+export class SigmaSourceAdapter {
+    deps;
+    source = 'sigma';
+    skillNames = ['sigma_ingest'];
+    constructor(deps) {
+        this.deps = deps;
+    }
+    detect(stagedDir) {
+        return detectSigmaStagedDir(stagedDir);
+    }
+    async fetch(pullConfig, stagedDir, ctx) {
+        await fetchSigmaBundle({
+            pullConfig,
+            stagedDir,
+            ctx,
+            clientFactory: this.deps.clientFactory,
+            ...(this.deps.logger ? { logger: this.deps.logger } : {}),
+        });
+    }
+    chunk(stagedDir, diffSet) {
+        return chunkSigmaStagedDir(stagedDir, { diffSet });
+    }
+    async listTargetConnectionIds(stagedDir) {
+        try {
+            const body = await readFile(join(stagedDir, STAGED_FILES.projectionConfig), 'utf-8');
+            const config = sigmaProjectionConfigSchema.parse(JSON.parse(body));
+            return [...new Set(Object.values(config.connectionMappings))].sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    project(ctx) {
+        return projectSigmaDataModels(ctx, ctx.semanticLayerService);
+    }
+}

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

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+/** Filters applied when listing workbooks. Shared with ListWorkbooksOptions in client-port.ts. */
+declare const workbookFilterSchema: z.ZodObject<{
+    includeArchived: z.ZodDefault<z.ZodBoolean>;
+    includeExplorations: z.ZodDefault<z.ZodBoolean>;
+    updatedSince: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Input shape for listWorkbooks — all fields optional since the client applies its own defaults. */
+export type WorkbookFilterInput = z.input<typeof workbookFilterSchema>;
+/** The lean config the adapter needs at `fetch()` time, stored in the ingest job's `bundleRef.config`. */
+declare const sigmaPullConfigSchema: z.ZodObject<{
+    sigmaConnectionId: z.ZodString;
+    connectionMappings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    workbookFilter: z.ZodDefault<z.ZodObject<{
+        includeArchived: z.ZodDefault<z.ZodBoolean>;
+        includeExplorations: z.ZodDefault<z.ZodBoolean>;
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    dataModelFilter: z.ZodOptional<z.ZodObject<{
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SigmaPullConfig = z.infer<typeof sigmaPullConfigSchema>;
+export declare function parseSigmaPullConfig(raw: unknown): SigmaPullConfig;
+/** Written to stagedDir during fetch() and read back by project(), listTargetConnectionIds(), and the sigma_ingest skill. */
+export declare const sigmaProjectionConfigSchema: z.ZodObject<{
+    connectionMappings: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    workbookFilter: z.ZodDefault<z.ZodObject<{
+        includeArchived: z.ZodDefault<z.ZodBoolean>;
+        includeExplorations: z.ZodDefault<z.ZodBoolean>;
+        updatedSince: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SigmaProjectionConfig = z.infer<typeof sigmaProjectionConfigSchema>;
+/**
+ * A staged data model file, one per `data-models/<id>.json`.
+ * Stores the summary metadata plus the raw spec blob from GET /v2/dataModels/{id}/spec.
+ */
+export declare const stagedDataModelFileSchema: z.ZodObject<{
+    sigmaId: z.ZodString;
+    name: z.ZodString;
+    path: z.ZodString;
+    latestVersion: z.ZodNumber;
+    updatedAt: z.ZodString;
+    isArchived: z.ZodDefault<z.ZodBoolean>;
+    dataModelUrlId: z.ZodOptional<z.ZodString>;
+    spec: z.ZodUnknown;
+}, z.core.$strip>;
+export type StagedDataModelFile = z.infer<typeof stagedDataModelFileSchema>;
+/** The manifest written once per `fetch()`. Presence acts as the detect() sentinel. */
+export declare const sigmaManifestSchema: z.ZodObject<{
+    sigmaConnectionId: z.ZodString;
+    fetchedAt: z.ZodString;
+    dataModelCount: z.ZodNumber;
+    workbookCount: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type SigmaManifest = z.infer<typeof sigmaManifestSchema>;
+/**
+ * A staged workbook file, one per `workbooks/<id>.json`.
+ * Stores the summary metadata from GET /v2/workbooks (no separate spec endpoint).
+ */
+export declare const stagedWorkbookFileSchema: z.ZodObject<{
+    sigmaId: z.ZodString;
+    name: z.ZodString;
+    path: z.ZodString;
+    latestVersion: z.ZodNumber;
+    updatedAt: z.ZodString;
+    isArchived: z.ZodDefault<z.ZodBoolean>;
+    workbookUrlId: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type StagedWorkbookFile = z.infer<typeof stagedWorkbookFileSchema>;
+/** Filenames inside stagedDir. Centralized so chunk() + fetch() + detect() all agree. */
+export declare const STAGED_FILES: {
+    readonly manifest: "sigma-manifest.json";
+    readonly projectionConfig: "sigma-projection-config.json";
+    readonly dataModelsDir: "data-models";
+    readonly workbooksDir: "workbooks";
+};
+export {};

package/dist/context/ingest/adapters/sigma/types.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+const sigmaLocalConnectionIdSchema = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/);
+/** Filters applied when listing workbooks. Shared with ListWorkbooksOptions in client-port.ts. */
+const workbookFilterSchema = z.object({
+    includeArchived: z.boolean().default(false),
+    includeExplorations: z.boolean().default(false),
+    /** ISO 8601 date string. Only workbooks updated on or after this date are included. */
+    updatedSince: z.string().optional(),
+});
+const dataModelFilterSchema = z.object({
+    /** ISO 8601 date string. Only data models updated on or after this date are fetched. */
+    updatedSince: z.string().optional(),
+});
+/** The lean config the adapter needs at `fetch()` time, stored in the ingest job's `bundleRef.config`. */
+const sigmaPullConfigSchema = z.object({
+    /** The ktx connection ID for the Sigma instance being swept. */
+    sigmaConnectionId: sigmaLocalConnectionIdSchema,
+    /**
+     * Maps Sigma internal connection UUIDs (source.connectionId in data model specs)
+     * to ktx warehouse connection IDs. When present, projected semantic-layer sources
+     * are written under the mapped warehouse connection rather than the Sigma connection.
+     */
+    connectionMappings: z.record(z.string(), z.string()).optional(),
+    /** Filters applied when listing workbooks. Defaults exclude archived and exploration workbooks. */
+    workbookFilter: workbookFilterSchema.default({ includeArchived: false, includeExplorations: false }),
+    /** Filters applied when listing data models. */
+    dataModelFilter: dataModelFilterSchema.optional(),
+});
+export function parseSigmaPullConfig(raw) {
+    return sigmaPullConfigSchema.parse(raw);
+}
+/** Written to stagedDir during fetch() and read back by project(), listTargetConnectionIds(), and the sigma_ingest skill. */
+export const sigmaProjectionConfigSchema = z.object({
+    connectionMappings: z.record(z.string(), z.string()).default({}),
+    /** Filters that were active when workbooks were last fetched. Tells the skill what the staged set covers. */
+    workbookFilter: workbookFilterSchema.default({ includeArchived: false, includeExplorations: false }),
+});
+/**
+ * A staged data model file, one per `data-models/<id>.json`.
+ * Stores the summary metadata plus the raw spec blob from GET /v2/dataModels/{id}/spec.
+ */
+export const stagedDataModelFileSchema = z.object({
+    sigmaId: z.string(),
+    name: z.string(),
+    /** Full path in Sigma, e.g. "Finance/Revenue Model". */
+    path: z.string(),
+    latestVersion: z.number(),
+    updatedAt: z.string(),
+    isArchived: z.boolean().default(false),
+    /** URL-safe slug Sigma uses in the web UI (dataModelUrlId from the API). */
+    dataModelUrlId: z.string().optional(),
+    /** Raw spec from GET /v2/dataModels/{id}/spec (JSON format). */
+    spec: z.unknown(),
+});
+/** The manifest written once per `fetch()`. Presence acts as the detect() sentinel. */
+export const sigmaManifestSchema = z.object({
+    sigmaConnectionId: sigmaLocalConnectionIdSchema,
+    fetchedAt: z.string(),
+    dataModelCount: z.number().int(),
+    workbookCount: z.number().int().default(0),
+});
+/**
+ * A staged workbook file, one per `workbooks/<id>.json`.
+ * Stores the summary metadata from GET /v2/workbooks (no separate spec endpoint).
+ */
+export const stagedWorkbookFileSchema = z.object({
+    sigmaId: z.string(),
+    name: z.string(),
+    path: z.string(),
+    latestVersion: z.number(),
+    updatedAt: z.string(),
+    isArchived: z.boolean().default(false),
+    workbookUrlId: z.string().optional(),
+    description: z.string().optional(),
+});
+/** Filenames inside stagedDir. Centralized so chunk() + fetch() + detect() all agree. */
+export const STAGED_FILES = {
+    manifest: 'sigma-manifest.json',
+    projectionConfig: 'sigma-projection-config.json',
+    dataModelsDir: 'data-models',
+    workbooksDir: 'workbooks',
+};

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

@@ -2,6 +2,7 @@ import type { SemanticLayerService } from '../../context/sl/semantic-layer.servi
 import type { TouchedSlSource } from '../../context/tools/touched-sl-sources.js';
 import type { KnowledgeWikiService } from '../../context/wiki/knowledge-wiki.service.js';
 import type { WuValidationResult } from './stages/validate-wu-sources.js';
+import { type WikiBodyRefIssue } from './wiki-body-refs.js';
 export interface FinalArtifactGateInput {
     connectionIds: string[];
     changedWikiPageKeys: string[];
@@ -18,5 +19,35 @@ export interface ProvenanceRawPathValidationInput {
     currentRawPaths: Set<string>;
     deletedRawPaths: Set<string>;
 }
-export declare function validateFinalIngestArtifacts(input: FinalArtifactGateInput): Promise<void>;
+export type FinalArtifactGateFinding = {
+    kind: 'invalid_source';
+    connectionId: string;
+    sourceName: string;
+    errors: string[];
+} | {
+    kind: 'missing_join_target';
+    ownerConnectionId: string;
+    ownerSourceName: string;
+    targetSourceName: string;
+    message: string;
+} | {
+    kind: 'missing_wiki_ref';
+    pageKey: string;
+    targetPageKey: string;
+    message: string;
+} | {
+    kind: 'missing_wiki_sl_ref';
+    pageKey: string;
+    ref: string;
+    sourceName: string;
+    entityName: string | null;
+    message: string;
+} | WikiBodyRefIssue;
+export interface FinalArtifactGateResult {
+    ok: boolean;
+    findings: FinalArtifactGateFinding[];
+}
+export declare function formatFinalArtifactGateFindings(findings: FinalArtifactGateFinding[]): string;
+export declare function isFinalArtifactGateFindingPruneable(finding: FinalArtifactGateFinding): boolean;
+export declare function validateFinalIngestArtifacts(input: FinalArtifactGateInput): Promise<FinalArtifactGateResult>;
 export declare function validateProvenanceRawPaths(input: ProvenanceRawPathValidationInput): void;

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

@@ -1,5 +1,8 @@
 import { findMissingWikiRefs } from '../wiki/wiki-ref-validation.js';
-import { findInvalidWikiBodyRefs } from './wiki-body-refs.js';
+import { findInvalidWikiBodyRefIssues } from './wiki-body-refs.js';
+function normalizeRawPath(path) {
+    return path.replace(/\\/g, '/').replace(/^\/+/, '');
+}
 function parseSlRef(ref) {
     const withoutConnection = ref.includes('/') ? ref.slice(ref.indexOf('/') + 1) : ref;
     const connectionId = ref.includes('/') ? ref.slice(0, ref.indexOf('/')) : null;
@@ -14,7 +17,7 @@ function slEntityNames(source) {
     ]);
 }
 async function validateWikiSlRefs(input) {
-    const errors = [];
+    const findings = [];
     const sourcesByConnection = new Map();
     for (const connectionId of input.connectionIds) {
         const { sources } = await input.semanticLayerService.loadAllSources(connectionId);
@@ -36,18 +39,32 @@ async function validateWikiSlRefs(input) {
                 }
             }
             if (!source) {
-                errors.push(`${pageKey}: unknown sl_refs entry ${ref}`);
+                findings.push({
+                    kind: 'missing_wiki_sl_ref',
+                    pageKey,
+                    ref,
+                    sourceName: parsed.sourceName,
+                    entityName: parsed.entityName,
+                    message: `${pageKey}: unknown sl_refs entry ${ref}`,
+                });
                 continue;
             }
             if (parsed.entityName && !slEntityNames(source).has(parsed.entityName)) {
-                errors.push(`${pageKey}: unknown sl_refs entity ${ref}`);
+                findings.push({
+                    kind: 'missing_wiki_sl_ref',
+                    pageKey,
+                    ref,
+                    sourceName: parsed.sourceName,
+                    entityName: parsed.entityName,
+                    message: `${pageKey}: unknown sl_refs entity ${ref}`,
+                });
             }
         }
     }
-    return errors;
+    return findings;
 }
 async function validateWikiRefs(input) {
-    const dangling = [];
+    const findings = [];
     for (const pageKey of input.changedWikiPageKeys) {
         const page = await input.wikiService.readPage('GLOBAL', null, pageKey);
         if (!page) {
@@ -62,28 +79,77 @@ async function validateWikiRefs(input) {
             content: page.content,
         });
         for (const missingRef of missingRefs) {
-            dangling.push(`${pageKey} -> ${missingRef}`);
+            findings.push({
+                kind: 'missing_wiki_ref',
+                pageKey,
+                targetPageKey: missingRef,
+                message: `${pageKey} -> ${missingRef}`,
+            });
+        }
+    }
+    return findings;
+}
+export function formatFinalArtifactGateFindings(findings) {
+    const errors = findings.map((finding) => {
+        if (finding.kind === 'invalid_source') {
+            return `semantic-layer validation failed for ${finding.connectionId}:${finding.sourceName}: ${finding.errors.join('; ')}`;
+        }
+        if (finding.kind === 'missing_wiki_ref') {
+            return `wiki reference targets missing page: ${finding.message}`;
+        }
+        return finding.message;
+    });
+    return `final artifact gates failed:\n${errors.join('\n')}`;
+}
+export function isFinalArtifactGateFindingPruneable(finding) {
+    switch (finding.kind) {
+        case 'invalid_source':
+        case 'missing_join_target':
+        case 'missing_wiki_ref':
+        case 'missing_wiki_sl_ref':
+        case 'missing_wiki_body_sl_entity':
+        case 'missing_wiki_body_sl_source':
+        case 'missing_wiki_body_table':
+            return true;
+        default: {
+            const exhaustive = finding;
+            return exhaustive;
         }
     }
-    return dangling;
 }
 export async function validateFinalIngestArtifacts(input) {
     // 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) {
-        errors.push(`wiki references target missing page(s): ${danglingWikiRefs.join(', ')}`);
+    const findings = [];
+    for (const invalid of validation.invalidSources) {
+        const [connectionId = '', sourceName = ''] = invalid.source.split(':', 2);
+        const issues = invalid.issues ?? invalid.errors.map((message) => ({ kind: 'source_validation', message }));
+        const sourceErrors = issues.filter((issue) => issue.kind === 'source_validation').map((issue) => issue.message);
+        if (sourceErrors.length > 0) {
+            findings.push({ kind: 'invalid_source', connectionId, sourceName, errors: sourceErrors });
+        }
+        for (const issue of issues) {
+            if (issue.kind === 'missing_join_target') {
+                findings.push({
+                    kind: 'missing_join_target',
+                    ownerConnectionId: connectionId,
+                    ownerSourceName: sourceName,
+                    targetSourceName: issue.targetSourceName,
+                    message: issue.message,
+                });
+            }
+        }
     }
+    findings.push(...(await validateWikiSlRefs(input)));
+    findings.push(...(await validateWikiRefs(input)));
     for (const pageKey of input.changedWikiPageKeys) {
         const page = await input.wikiService.readPage('GLOBAL', null, pageKey);
         if (!page) {
             continue;
         }
-        errors.push(...(await findInvalidWikiBodyRefs({
+        findings.push(...(await findInvalidWikiBodyRefIssues({
             pageKey,
             body: page.content,
             visibleConnectionIds: input.connectionIds,
@@ -94,13 +160,14 @@ export async function validateFinalIngestArtifacts(input) {
             tableExists: input.tableExists,
         })));
     }
-    if (errors.length > 0) {
-        throw new Error(`final artifact gates failed:\n${errors.join('\n')}`);
-    }
+    return { ok: findings.length === 0, findings };
 }
 export function validateProvenanceRawPaths(input) {
+    const currentRawPaths = new Set([...input.currentRawPaths].map(normalizeRawPath));
+    const deletedRawPaths = new Set([...input.deletedRawPaths].map(normalizeRawPath));
     for (const row of input.rows) {
-        if (!input.currentRawPaths.has(row.rawPath) && !input.deletedRawPaths.has(row.rawPath)) {
+        const rawPath = normalizeRawPath(row.rawPath);
+        if (!currentRawPaths.has(rawPath) && !deletedRawPaths.has(rawPath)) {
             throw new Error(`provenance row references raw path outside this snapshot: ${row.rawPath}`);
         }
     }

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

@@ -0,0 +1,35 @@
+import type { KtxFileStorePort } from '../core/file-store.js';
+import type { KnowledgeWikiService } from '../wiki/knowledge-wiki.service.js';
+import type { FinalArtifactGateFinding } from './artifact-gates.js';
+import type { IngestTraceWriter } from './ingest-trace.js';
+type FinalGatePrunedReferenceKind = 'join' | 'wiki_ref' | 'wiki_sl_ref' | 'wiki_body_ref';
+type SemanticLayerFileStore = Pick<KtxFileStorePort, 'readFile' | 'writeFile' | 'deleteFile' | 'listFiles'>;
+export interface FinalGatePrunedReference {
+    kind: FinalGatePrunedReferenceKind;
+    artifact: string;
+    removedRef: string;
+    absentTarget: string;
+}
+export interface FinalGateDroppedSource {
+    connectionId: string;
+    sourceName: string;
+    reason: string;
+}
+export interface FinalGatePruneResult {
+    prunedReferences: FinalGatePrunedReference[];
+    droppedSources: FinalGateDroppedSource[];
+}
+interface PruneInput {
+    workdir: string;
+    semanticLayerFiles: SemanticLayerFileStore;
+    findings: FinalArtifactGateFinding[];
+    droppedSources: FinalGateDroppedSource[];
+    trace: IngestTraceWriter;
+    author: {
+        name: string;
+        email: string;
+    };
+    wikiService?: KnowledgeWikiService;
+}
+export declare function pruneFinalGateFindings(input: PruneInput): Promise<FinalGatePruneResult>;
+export {};