@kaelio/ktx 0.1.0-rc.5 → 0.1.0

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

@@ -9,6 +9,7 @@ import type { SemanticLayerService, SlConnectionCatalogPort, SlSearchService, Sl
 import type { ToolContext, ToolSession, TouchedSlSource } from '../tools/index.js';
 import type { KnowledgeIndexPort, KnowledgeWikiService } from '../wiki/index.js';
 import type { CanonicalPin } from './canonical-pins.js';
+import type { IngestTraceLevel } from './ingest-trace.js';
 import type { IngestReportSnapshot } from './reports.js';
 import type { ReconcileCandidateForPrompt, ReconcileCandidateSummary, ReconcilePromptRunState } from './stages/build-reconcile-context.js';
 import type { ReconciliationOutcome } from './stages/stage-4-reconciliation.js';
@@ -101,6 +102,7 @@ export interface IngestSettingsPort {
     workUnitMaxConcurrency?: number;
     workUnitStepBudget?: number;
     workUnitFailureMode?: 'abort' | 'continue';
+    ingestTraceLevel?: IngestTraceLevel;
 }
 export interface IngestGitAuthor {
     name: string;
@@ -112,6 +114,7 @@ export interface IngestStoragePort {
     resolveUploadDir(uploadId: string): string;
     resolvePullDir(jobId: string): string;
     resolveTranscriptDir(jobId: string): string;
+    resolveTracePath(jobId: string): string;
 }
 export interface IngestCommitMessagePort {
     enqueueForExternalCommit(args: {

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

@@ -8,6 +8,10 @@ export declare const ingestReportSnapshotSchema: z.ZodObject<{
     sourceKey: z.ZodString;
     createdAt: z.ZodString;
     body: z.ZodObject<{
+        status: z.ZodOptional<z.ZodEnum<{
+            failed: "failed";
+            completed: "completed";
+        }>>;
         syncId: z.ZodString;
         diffSummary: z.ZodObject<{
             added: z.ZodNumber;
@@ -34,10 +38,10 @@ export declare const ingestReportSnapshotSchema: z.ZodObject<{
                 retryRecommended: z.ZodBoolean;
                 kind: z.ZodOptional<z.ZodEnum<{
                     lookml_connection_mismatch: "lookml_connection_mismatch";
-                    unmapped_looker_connection: "unmapped_looker_connection";
-                    unparseable_sql_table_name: "unparseable_sql_table_name";
                     looker_template_unresolved: "looker_template_unresolved";
                     derived_table_not_supported: "derived_table_not_supported";
+                    unmapped_looker_connection: "unmapped_looker_connection";
+                    unparseable_sql_table_name: "unparseable_sql_table_name";
                 }>>;
                 details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             }, z.core.$strip>>>;
@@ -54,15 +58,36 @@ export declare const ingestReportSnapshotSchema: z.ZodObject<{
                 retryRecommended: z.ZodBoolean;
                 kind: z.ZodOptional<z.ZodEnum<{
                     lookml_connection_mismatch: "lookml_connection_mismatch";
-                    unmapped_looker_connection: "unmapped_looker_connection";
-                    unparseable_sql_table_name: "unparseable_sql_table_name";
                     looker_template_unresolved: "looker_template_unresolved";
                     derived_table_not_supported: "derived_table_not_supported";
+                    unmapped_looker_connection: "unmapped_looker_connection";
+                    unparseable_sql_table_name: "unparseable_sql_table_name";
                 }>>;
                 details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             }, z.core.$strip>>>;
         }, z.core.$strip>>;
         commitSha: z.ZodNullable<z.ZodString>;
+        tracePath: z.ZodOptional<z.ZodString>;
+        failure: z.ZodOptional<z.ZodObject<{
+            phase: z.ZodString;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>;
+        isolatedDiff: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            integrationWorktreePath: z.ZodOptional<z.ZodString>;
+            ingestionBaseSha: z.ZodOptional<z.ZodString>;
+            projectionSha: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            acceptedPatches: z.ZodNumber;
+            textualConflicts: z.ZodNumber;
+            semanticConflicts: z.ZodNumber;
+            resolverAttempts: z.ZodDefault<z.ZodNumber>;
+            resolverRepairs: z.ZodDefault<z.ZodNumber>;
+            resolverFailures: z.ZodDefault<z.ZodNumber>;
+            gateRepairAttempts: z.ZodDefault<z.ZodNumber>;
+            gateRepairs: z.ZodDefault<z.ZodNumber>;
+            gateRepairFailures: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
         workUnits: z.ZodArray<z.ZodObject<{
             unitKey: z.ZodString;
             rawFiles: z.ZodArray<z.ZodString>;
@@ -78,8 +103,8 @@ export declare const ingestReportSnapshotSchema: z.ZodObject<{
                 }>;
                 type: z.ZodEnum<{
                     created: "created";
-                    updated: "updated";
                     removed: "removed";
+                    updated: "updated";
                 }>;
                 key: z.ZodString;
                 detail: z.ZodString;
@@ -104,8 +129,8 @@ export declare const ingestReportSnapshotSchema: z.ZodObject<{
             }>;
             type: z.ZodEnum<{
                 created: "created";
-                updated: "updated";
                 removed: "removed";
+                updated: "updated";
             }>;
             key: z.ZodString;
             detail: z.ZodString;
@@ -138,9 +163,9 @@ export declare const ingestReportSnapshotSchema: z.ZodObject<{
         unmappedFallbacks: z.ZodDefault<z.ZodArray<z.ZodObject<{
             rawPath: z.ZodString;
             reason: z.ZodEnum<{
+                no_connection_mapping: "no_connection_mapping";
                 looker_template_unresolved: "looker_template_unresolved";
                 derived_table_not_supported: "derived_table_not_supported";
-                no_connection_mapping: "no_connection_mapping";
                 no_physical_table: "no_physical_table";
                 multiple_table_references: "multiple_table_references";
                 unsupported_dialect: "unsupported_dialect";

package/node_modules/@ktx/context/dist/ingest/report-snapshot.js

@@ -109,6 +109,11 @@ const sourceFetchReportSchema = z.object({
     skipped: z.array(sourceFetchIssueSchema).default([]),
     warnings: z.array(sourceFetchIssueSchema).default([]),
 });
+const ingestReportFailureSchema = z.object({
+    phase: z.string().min(1),
+    message: z.string().min(1),
+    details: z.record(z.string(), z.unknown()).optional(),
+});
 export const ingestReportSnapshotSchema = z
     .object({
     id: z.string().min(1),
@@ -119,10 +124,30 @@ export const ingestReportSnapshotSchema = z
     createdAt: z.string().min(1),
     body: z
         .object({
+        status: z.enum(['completed', 'failed']).optional(),
         syncId: z.string().min(1),
         diffSummary: ingestDiffSummarySchema,
         fetch: sourceFetchReportSchema.optional(),
         commitSha: z.string().nullable(),
+        tracePath: z.string().optional(),
+        failure: ingestReportFailureSchema.optional(),
+        isolatedDiff: z
+            .object({
+            enabled: z.boolean(),
+            integrationWorktreePath: z.string().optional(),
+            ingestionBaseSha: z.string().optional(),
+            projectionSha: z.string().nullable().optional(),
+            acceptedPatches: z.number().int().min(0),
+            textualConflicts: z.number().int().min(0),
+            semanticConflicts: z.number().int().min(0),
+            resolverAttempts: z.number().int().min(0).default(0),
+            resolverRepairs: z.number().int().min(0).default(0),
+            resolverFailures: z.number().int().min(0).default(0),
+            gateRepairAttempts: z.number().int().min(0).default(0),
+            gateRepairs: z.number().int().min(0).default(0),
+            gateRepairFailures: z.number().int().min(0).default(0),
+        })
+            .optional(),
         workUnits: z.array(z.object({
             unitKey: z.string().min(1),
             rawFiles: z.array(z.string()),

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

@@ -194,6 +194,45 @@ describe('parseIngestReportSnapshot', () => {
         expect(snapshot.body.provenanceRows).toEqual([]);
         expect(snapshot.body.toolTranscripts).toEqual([]);
     });
+    it('parses failed ingest reports with trace and failure details', () => {
+        const snapshot = parseIngestReportSnapshot({
+            id: 'report-failed',
+            runId: 'run-failed',
+            jobId: 'job-failed',
+            connectionId: 'warehouse',
+            sourceKey: 'metabase',
+            createdAt: '2026-05-17T12:00:00.000Z',
+            body: {
+                status: 'failed',
+                syncId: 'sync-failed',
+                diffSummary: { added: 1, modified: 0, deleted: 0, unchanged: 0 },
+                commitSha: null,
+                tracePath: '/project/.ktx/ingest-traces/job-failed/trace.jsonl',
+                failure: {
+                    phase: 'final_gates',
+                    message: 'final artifact gates failed',
+                },
+                workUnits: [],
+                failedWorkUnits: [],
+                reconciliationSkipped: true,
+                conflictsResolved: [],
+                evictionsApplied: [],
+                unmappedFallbacks: [],
+                evictionInputs: [],
+                unresolvedCards: [],
+                supersededBy: null,
+                overrideOf: null,
+                provenanceRows: [],
+                toolTranscripts: [],
+            },
+        });
+        expect(snapshot.body.status).toBe('failed');
+        expect(snapshot.body.failure).toEqual({
+            phase: 'final_gates',
+            message: 'final artifact gates failed',
+        });
+        expect(snapshot.body.tracePath).toContain('trace.jsonl');
+    });
     it('rejects malformed report snapshots with a concise message', () => {
         const report = validReportSnapshot();
         report.body.workUnits[0] = {
@@ -202,4 +241,89 @@ describe('parseIngestReportSnapshot', () => {
         };
         expect(() => parseIngestReportSnapshot(report)).toThrow('Invalid ingest report snapshot');
     });
+    it('parses isolated-diff textual resolver counters', () => {
+        const snapshot = parseIngestReportSnapshot({
+            id: 'report-1',
+            runId: 'run-1',
+            jobId: 'job-1',
+            connectionId: 'warehouse',
+            sourceKey: 'metabase',
+            createdAt: '2026-05-18T00:00:00.000Z',
+            body: {
+                status: 'completed',
+                syncId: 'sync-1',
+                diffSummary: { added: 0, modified: 1, deleted: 0, unchanged: 0 },
+                commitSha: 'abc123',
+                isolatedDiff: {
+                    enabled: true,
+                    acceptedPatches: 2,
+                    textualConflicts: 1,
+                    semanticConflicts: 0,
+                    resolverAttempts: 1,
+                    resolverRepairs: 1,
+                    resolverFailures: 0,
+                },
+                workUnits: [],
+                failedWorkUnits: [],
+                reconciliationSkipped: true,
+                conflictsResolved: [],
+                evictionsApplied: [],
+                unmappedFallbacks: [],
+                artifactResolutions: [],
+                evictionInputs: [],
+                unresolvedCards: [],
+                supersededBy: null,
+                overrideOf: null,
+                provenanceRows: [],
+                toolTranscripts: [],
+            },
+        });
+        expect(snapshot.body.isolatedDiff).toMatchObject({
+            resolverAttempts: 1,
+            resolverRepairs: 1,
+            resolverFailures: 0,
+        });
+    });
+    it('parses isolated-diff gate repair counters', () => {
+        const snapshot = parseIngestReportSnapshot({
+            id: 'report-1',
+            runId: 'run-1',
+            jobId: 'job-1',
+            connectionId: 'warehouse',
+            sourceKey: 'metabase',
+            createdAt: '2026-05-18T00:00:00.000Z',
+            body: {
+                status: 'completed',
+                syncId: 'sync-1',
+                diffSummary: { added: 1, modified: 0, deleted: 0, unchanged: 0 },
+                commitSha: 'abc123',
+                isolatedDiff: {
+                    enabled: true,
+                    acceptedPatches: 1,
+                    textualConflicts: 0,
+                    semanticConflicts: 1,
+                    gateRepairAttempts: 1,
+                    gateRepairs: 1,
+                    gateRepairFailures: 0,
+                },
+                workUnits: [],
+                failedWorkUnits: [],
+                reconciliationSkipped: true,
+                conflictsResolved: [],
+                evictionsApplied: [],
+                unmappedFallbacks: [],
+                evictionInputs: [],
+                unresolvedCards: [],
+                supersededBy: null,
+                overrideOf: null,
+                provenanceRows: [],
+                toolTranscripts: [],
+            },
+        });
+        expect(snapshot.body.isolatedDiff).toMatchObject({
+            gateRepairAttempts: 1,
+            gateRepairs: 1,
+            gateRepairFailures: 0,
+        });
+    });
 });

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

@@ -37,11 +37,34 @@ export interface IngestReportPostProcessorOutcome {
     warnings: string[];
     touchedSources: TouchedSlSource[];
 }
+export interface IngestReportFailure {
+    phase: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
 export interface IngestReportBody {
+    status?: 'completed' | 'failed';
     syncId: string;
     diffSummary: IngestDiffSummary;
     fetch?: SourceFetchReport;
     commitSha: string | null;
+    tracePath?: string;
+    failure?: IngestReportFailure;
+    isolatedDiff?: {
+        enabled: boolean;
+        integrationWorktreePath?: string;
+        ingestionBaseSha?: string;
+        projectionSha?: string | null;
+        acceptedPatches: number;
+        textualConflicts: number;
+        semanticConflicts: number;
+        resolverAttempts?: number;
+        resolverRepairs?: number;
+        resolverFailures?: number;
+        gateRepairAttempts?: number;
+        gateRepairs?: number;
+        gateRepairFailures?: number;
+    };
     workUnits: IngestReportWorkUnit[];
     failedWorkUnits: string[];
     reconciliationSkipped: boolean;

package/node_modules/@ktx/context/dist/ingest/semantic-layer-target-policy.d.ts

@@ -0,0 +1,11 @@
+export interface SemanticLayerTargetPolicyInput {
+    paths: readonly string[];
+    allowedConnectionIds: ReadonlySet<string>;
+}
+export interface SemanticLayerTargetPolicyViolation {
+    path: string;
+    connectionId: string;
+}
+export declare function semanticLayerConnectionIdFromPath(path: string): string | null;
+export declare function findDisallowedSemanticLayerTargetPaths(input: SemanticLayerTargetPolicyInput): SemanticLayerTargetPolicyViolation[];
+export declare function assertSemanticLayerTargetPathsAllowed(input: SemanticLayerTargetPolicyInput): void;

package/node_modules/@ktx/context/dist/ingest/semantic-layer-target-policy.js

@@ -0,0 +1,26 @@
+export function semanticLayerConnectionIdFromPath(path) {
+    const normalized = path.replace(/^[ab]\//, '');
+    const match = /^semantic-layer\/([^/]+)\//.exec(normalized);
+    return match?.[1] ?? null;
+}
+export function findDisallowedSemanticLayerTargetPaths(input) {
+    return input.paths
+        .map((path) => ({ path, connectionId: semanticLayerConnectionIdFromPath(path) }))
+        .filter((entry) => {
+        return entry.connectionId !== null && !input.allowedConnectionIds.has(entry.connectionId);
+    })
+        .sort((left, right) => {
+        const byConnection = left.connectionId.localeCompare(right.connectionId);
+        return byConnection === 0 ? left.path.localeCompare(right.path) : byConnection;
+    });
+}
+export function assertSemanticLayerTargetPathsAllowed(input) {
+    const violations = findDisallowedSemanticLayerTargetPaths(input);
+    if (violations.length === 0) {
+        return;
+    }
+    const allowed = [...input.allowedConnectionIds].sort();
+    throw new Error(`semantic-layer target connection not allowed: ${violations
+        .map((violation) => `${violation.path} (${violation.connectionId})`)
+        .join(', ')}; allowed: ${allowed.length > 0 ? allowed.join(', ') : '(none)'}`);
+}

package/node_modules/@ktx/context/dist/ingest/semantic-layer-target-policy.test.d.ts

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

package/node_modules/@ktx/context/dist/ingest/semantic-layer-target-policy.test.js

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { assertSemanticLayerTargetPathsAllowed, findDisallowedSemanticLayerTargetPaths, semanticLayerConnectionIdFromPath, } from './semantic-layer-target-policy.js';
+describe('semantic-layer target policy', () => {
+    it('extracts connection ids from semantic-layer paths', () => {
+        expect(semanticLayerConnectionIdFromPath('semantic-layer/warehouse/orders.yaml')).toBe('warehouse');
+        expect(semanticLayerConnectionIdFromPath('a/semantic-layer/finance/orders.yaml')).toBe('finance');
+        expect(semanticLayerConnectionIdFromPath('wiki/global/orders.md')).toBeNull();
+    });
+    it('finds semantic-layer paths outside the allowed target connections', () => {
+        expect(findDisallowedSemanticLayerTargetPaths({
+            paths: [
+                'semantic-layer/warehouse/orders.yaml',
+                'semantic-layer/finance/orders.yaml',
+                'wiki/global/orders.md',
+            ],
+            allowedConnectionIds: new Set(['warehouse']),
+        })).toEqual([{ path: 'semantic-layer/finance/orders.yaml', connectionId: 'finance' }]);
+    });
+    it('throws a deterministic error for unauthorized semantic-layer targets', () => {
+        expect(() => assertSemanticLayerTargetPathsAllowed({
+            paths: ['semantic-layer/finance/orders.yaml', 'semantic-layer/marketing/accounts.yaml'],
+            allowedConnectionIds: new Set(['warehouse']),
+        })).toThrow(/semantic-layer target connection not allowed: semantic-layer\/finance\/orders\.yaml \(finance\), semantic-layer\/marketing\/accounts\.yaml \(marketing\); allowed: warehouse/);
+    });
+});

package/node_modules/@ktx/context/dist/ingest/stages/stage-3-work-units.d.ts

@@ -12,6 +12,7 @@ export interface WorkUnitExecutionDeps {
         revParseHead(): Promise<string | null>;
     };
     agentRunner: AgentRunnerPort;
+    validateWikiRefs?: (actions: MemoryAction[]) => Promise<string[]>;
     validateTouchedSources: (touched: TouchedSlSource[]) => Promise<TouchedValidationResult>;
     resetHardTo: (targetSha: string) => Promise<void>;
     buildSystemPrompt: (wu: WorkUnit) => string;
@@ -40,5 +41,8 @@ export interface WorkUnitOutcome {
     touchedSlSources: TouchedSlSource[];
     slDisallowed?: boolean;
     slDisallowedReason?: 'lookml_connection_mismatch';
+    patchPath?: string;
+    patchTouchedPaths?: string[];
+    childWorktreePath?: string;
 }
 export declare function executeWorkUnit(deps: WorkUnitExecutionDeps, wu: WorkUnit): Promise<WorkUnitOutcome>;

package/node_modules/@ktx/context/dist/ingest/stages/stage-3-work-units.js

@@ -81,6 +81,10 @@ export async function executeWorkUnit(deps, wu) {
     if (toolFailureCount > 0) {
         return failWithReset(`${toolFailureCount} tool call(s) failed during WorkUnit ${wu.unitKey}`);
     }
+    const danglingWikiRefs = (await deps.validateWikiRefs?.(deps.sessionActions)) ?? [];
+    if (danglingWikiRefs.length > 0) {
+        return failWithReset(`wiki references target missing page(s): ${danglingWikiRefs.join(', ')}`);
+    }
     const touched = listTouchedSlSources(deps.captureSession.touchedSlSources);
     if (touched.length > 0) {
         const validation = await deps.validateTouchedSources(touched);

package/node_modules/@ktx/context/dist/ingest/stages/stage-3-work-units.test.js

@@ -108,6 +108,35 @@ describe('Stage 3 — executeWorkUnit', () => {
         expect(outcome.touchedSlSources).toEqual([]);
         expect(deps.resetHardTo).toHaveBeenCalledWith('pre');
     });
+    it('dangling wiki refs reset to the pre-WU SHA and mark WU failed after the agent loop', async () => {
+        const deps = makeDeps();
+        deps.sessionWorktreeGit.revParseHead = vi.fn().mockResolvedValueOnce('pre').mockResolvedValueOnce('post');
+        deps.agentRunner.runLoop = vi.fn().mockImplementation(() => {
+            deps.sessionActions.push({ target: 'wiki', type: 'created', key: 'page-a', detail: 'Page A' });
+            return Promise.resolve({ stopReason: 'natural' });
+        });
+        deps.validateWikiRefs = vi.fn().mockResolvedValue(['page-a -> page-b']);
+        const outcome = await executeWorkUnit(deps, makeWu());
+        expect(outcome.status).toBe('failed');
+        expect(outcome.reason).toContain('wiki references target missing page(s): page-a -> page-b');
+        expect(outcome.actions).toEqual([]);
+        expect(outcome.touchedSlSources).toEqual([]);
+        expect(deps.resetHardTo).toHaveBeenCalledWith('pre');
+    });
+    it('resolved wiki refs pass post-WU validation and preserve actions', async () => {
+        const deps = makeDeps();
+        deps.sessionWorktreeGit.revParseHead = vi.fn().mockResolvedValueOnce('pre').mockResolvedValueOnce('post');
+        deps.agentRunner.runLoop = vi.fn().mockImplementation(() => {
+            deps.sessionActions.push({ target: 'wiki', type: 'created', key: 'page-a', detail: 'Page A' });
+            deps.sessionActions.push({ target: 'wiki', type: 'created', key: 'page-b', detail: 'Page B' });
+            return Promise.resolve({ stopReason: 'natural' });
+        });
+        deps.validateWikiRefs = vi.fn().mockResolvedValue([]);
+        const outcome = await executeWorkUnit(deps, makeWu());
+        expect(outcome.status).toBe('success');
+        expect(outcome.actions.map((action) => action.key)).toEqual(['page-a', 'page-b']);
+        expect(deps.resetHardTo).not.toHaveBeenCalled();
+    });
     it('runner loop thrown exception resets to the pre-WU SHA and marks WU failed', async () => {
         const deps = makeDeps();
         deps.sessionWorktreeGit.revParseHead = vi.fn().mockResolvedValueOnce('pre').mockResolvedValueOnce('post');

package/node_modules/@ktx/context/dist/ingest/tools/emit-unmapped-fallback.tool.d.ts

@@ -6,7 +6,7 @@ interface EmitUnmappedFallbackDeps {
 }
 export declare function createEmitUnmappedFallbackTool(deps: EmitUnmappedFallbackDeps): import("ai").Tool<{
     rawPath: string;
-    reason: "looker_template_unresolved" | "derived_table_not_supported" | "no_connection_mapping" | "no_physical_table" | "multiple_table_references" | "unsupported_dialect" | "parse_error" | "missing_target_table" | "cumulative_metric_unsupported" | "conversion_metric_unsupported";
+    reason: "no_connection_mapping" | "looker_template_unresolved" | "derived_table_not_supported" | "no_physical_table" | "multiple_table_references" | "unsupported_dialect" | "parse_error" | "missing_target_table" | "cumulative_metric_unsupported" | "conversion_metric_unsupported";
     fallback: "sql_standalone" | "wiki_only" | "flagged";
     tableRef?: string | undefined;
     clarification?: string | undefined;

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

@@ -1,4 +1,5 @@
 import type { KtxEmbeddingPort } from '../core/embedding.js';
+import type { SemanticLayerService } from '../sl/index.js';
 import type { MemoryFlowEventSink } from './memory-flow/types.js';
 export type IngestTrigger = 'upload' | 'scheduled_pull' | 'manual_resync' | 'manual_override';
 export interface DiffSet {
@@ -40,6 +41,7 @@ export interface ChunkResult {
 export interface FetchContext {
     connectionId: string;
     sourceKey: string;
+    memoryFlow?: MemoryFlowEventSink;
 }
 type SourceFetchIssueKind = 'unmapped_looker_connection' | 'unparseable_sql_table_name' | 'looker_template_unresolved' | 'derived_table_not_supported' | 'lookml_connection_mismatch';
 export interface SourceFetchIssue {
@@ -76,6 +78,27 @@ export interface ClusterWorkUnitsContext {
     stagedDir: string;
     embedding: KtxEmbeddingPort;
 }
+export interface DeterministicProjectionContext {
+    connectionId: string;
+    sourceKey: string;
+    syncId: string;
+    jobId: string;
+    runId: string;
+    stagedDir: string;
+    workdir: string;
+    parseArtifacts?: unknown;
+    semanticLayerService: SemanticLayerService;
+}
+export interface ProjectionResult {
+    warnings: string[];
+    errors: string[];
+    touchedSources: Array<{
+        connectionId: string;
+        sourceName: string;
+    }>;
+    changedWikiPageKeys: string[];
+    result?: unknown;
+}
 export interface SourceAdapter {
     readonly source: string;
     readonly skillNames: string[];
@@ -89,6 +112,7 @@ export interface SourceAdapter {
     listTargetConnectionIds?(stagedDir: string): Promise<string[]>;
     chunk(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
     clusterWorkUnits?(ctx: ClusterWorkUnitsContext): Promise<WorkUnit[]>;
+    project?(ctx: DeterministicProjectionContext): Promise<ProjectionResult>;
     describeScope?(stagedDir: string): Promise<ScopeDescriptor>;
     onPullSucceeded?(ctx: {
         connectionId: string;

package/node_modules/@ktx/context/dist/ingest/wiki-body-refs.d.ts

@@ -0,0 +1,24 @@
+import type { SemanticLayerSource } from '../sl/index.js';
+export type WikiBodyRef = {
+    kind: 'sl_entity';
+    connectionId: string | null;
+    sourceName: string;
+    entityName: string;
+} | {
+    kind: 'sl_source';
+    connectionId: string | null;
+    sourceName: string;
+} | {
+    kind: 'table';
+    connectionId: string | null;
+    tableRef: string;
+};
+export interface WikiBodyRefValidationInput {
+    pageKey: string;
+    body: string;
+    visibleConnectionIds: string[];
+    loadSources(connectionId: string): Promise<SemanticLayerSource[]>;
+    tableExists(connectionId: string, tableRef: string): Promise<boolean>;
+}
+export declare function parseWikiBodyRefs(body: string): WikiBodyRef[];
+export declare function findInvalidWikiBodyRefs(input: WikiBodyRefValidationInput): Promise<string[]>;

package/node_modules/@ktx/context/dist/ingest/wiki-body-refs.js

@@ -0,0 +1,111 @@
+const inlineCodePattern = /`([^`\n]+)`/g;
+function visibleLinesOutsideFences(body) {
+    const lines = [];
+    let fenced = false;
+    for (const line of body.split('\n')) {
+        if (/^\s*```/.test(line)) {
+            fenced = !fenced;
+            continue;
+        }
+        if (!fenced) {
+            lines.push(line);
+        }
+    }
+    return lines;
+}
+function parseConnectionScoped(value) {
+    const slash = value.indexOf('/');
+    if (slash <= 0) {
+        return { connectionId: null, body: value };
+    }
+    return { connectionId: value.slice(0, slash), body: value.slice(slash + 1) };
+}
+function isIdentifierToken(value) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+export function parseWikiBodyRefs(body) {
+    const refs = [];
+    for (const line of visibleLinesOutsideFences(body)) {
+        for (const match of line.matchAll(inlineCodePattern)) {
+            const token = (match[1] ?? '').trim();
+            if (!token) {
+                continue;
+            }
+            const scoped = parseConnectionScoped(token);
+            if (scoped.body.startsWith('source:')) {
+                const sourceName = scoped.body.slice('source:'.length).trim();
+                if (sourceName) {
+                    refs.push({ kind: 'sl_source', connectionId: scoped.connectionId, sourceName });
+                }
+                continue;
+            }
+            if (scoped.body.startsWith('table:')) {
+                const tableRef = scoped.body.slice('table:'.length).trim();
+                if (tableRef) {
+                    refs.push({ kind: 'table', connectionId: scoped.connectionId, tableRef });
+                }
+                continue;
+            }
+            const parts = scoped.body.split('.');
+            if (parts.length === 2 && isIdentifierToken(parts[0] ?? '') && isIdentifierToken(parts[1] ?? '')) {
+                refs.push({
+                    kind: 'sl_entity',
+                    connectionId: scoped.connectionId,
+                    sourceName: parts[0],
+                    entityName: parts[1],
+                });
+            }
+        }
+    }
+    return refs;
+}
+function entityNames(source) {
+    return new Set([
+        ...(source.measures ?? []).map((measure) => measure.name),
+        ...(source.columns ?? []).map((column) => column.name),
+        ...(source.segments ?? []).map((segment) => segment.name),
+    ]);
+}
+export async function findInvalidWikiBodyRefs(input) {
+    const errors = [];
+    const sourceCache = new Map();
+    const loadSources = async (connectionId) => {
+        const cached = sourceCache.get(connectionId);
+        if (cached) {
+            return cached;
+        }
+        const sources = await input.loadSources(connectionId);
+        sourceCache.set(connectionId, sources);
+        return sources;
+    };
+    const findSource = async (connectionIds, sourceName) => {
+        for (const connectionId of connectionIds) {
+            const source = (await loadSources(connectionId)).find((candidate) => candidate.name === sourceName);
+            if (source) {
+                return { connectionId, source };
+            }
+        }
+        return null;
+    };
+    for (const ref of parseWikiBodyRefs(input.body)) {
+        const connectionIds = ref.connectionId ? [ref.connectionId] : input.visibleConnectionIds;
+        if (ref.kind === 'table') {
+            const found = await Promise.all(connectionIds.map((connectionId) => input.tableExists(connectionId, ref.tableRef)));
+            if (!found.some(Boolean)) {
+                errors.push(`${input.pageKey}: unknown raw table ${ref.connectionId ? `${ref.connectionId}/` : ''}${ref.tableRef}`);
+            }
+            continue;
+        }
+        const found = await findSource(connectionIds, ref.sourceName);
+        if (!found) {
+            if (ref.kind === 'sl_source') {
+                errors.push(`${input.pageKey}: unknown semantic-layer source ${ref.connectionId ? `${ref.connectionId}/` : ''}${ref.sourceName}`);
+            }
+            continue;
+        }
+        if (ref.kind === 'sl_entity' && !entityNames(found.source).has(ref.entityName)) {
+            errors.push(`${input.pageKey}: unknown semantic-layer entity ${ref.sourceName}.${ref.entityName}`);
+        }
+    }
+    return errors;
+}

package/node_modules/@ktx/context/dist/ingest/wiki-body-refs.test.d.ts

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