@kaelio/ktx 0.1.0-rc.5 → 0.1.0

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

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+import { findInvalidWikiBodyRefs, parseWikiBodyRefs } from './wiki-body-refs.js';
+const sources = [
+    {
+        name: 'mart_account_segments',
+        grain: ['account_id'],
+        columns: [
+            { name: 'account_id', type: 'string' },
+            { name: 'segment', type: 'string' },
+        ],
+        joins: [],
+        measures: [{ name: 'total_contract_arr', expr: 'sum(contract_arr)' }],
+        segments: [{ name: 'enterprise', expr: "segment = 'enterprise'" }],
+        table: 'analytics.mart_account_segments',
+    },
+];
+describe('wiki body refs', () => {
+    it('parses only explicit inline-code body references outside fenced blocks', () => {
+        const body = [
+            'Valid `mart_account_segments.total_contract_arr` and `source:mart_account_segments`.',
+            'Also `warehouse/mart_account_segments.segment` and `table:analytics.mart_account_segments`.',
+            'Ignore prose mart_account_segments.total_contract_arr_cents.',
+            'Ignore `single_token`.',
+            'Ignore wildcard pattern `mart_nrr_quarterly.*_arr_cents`.',
+            'Ignore condition `users.is_internal = false`.',
+            '```sql',
+            'select `mart_account_segments.total_contract_arr_cents`',
+            '```',
+        ].join('\n');
+        expect(parseWikiBodyRefs(body)).toEqual([
+            { kind: 'sl_entity', connectionId: null, sourceName: 'mart_account_segments', entityName: 'total_contract_arr' },
+            { kind: 'sl_source', connectionId: null, sourceName: 'mart_account_segments' },
+            { kind: 'sl_entity', connectionId: 'warehouse', sourceName: 'mart_account_segments', entityName: 'segment' },
+            { kind: 'table', connectionId: null, tableRef: 'analytics.mart_account_segments' },
+        ]);
+    });
+    it('rejects stale inline-code semantic-layer references', async () => {
+        const invalid = await findInvalidWikiBodyRefs({
+            pageKey: 'account-segments',
+            body: 'ARR is documented as `mart_account_segments.total_contract_arr_cents`.',
+            visibleConnectionIds: ['warehouse'],
+            loadSources: async () => sources,
+            tableExists: async () => true,
+        });
+        expect(invalid).toEqual([
+            'account-segments: unknown semantic-layer entity mart_account_segments.total_contract_arr_cents',
+        ]);
+    });
+    it('does not treat wildcard inline-code patterns as exact semantic-layer entity references', async () => {
+        const invalid = await findInvalidWikiBodyRefs({
+            pageKey: 'revenue-metrics-encoding',
+            body: 'Cents columns include `mart_nrr_quarterly.*_arr_cents` and `mart_retention_movement_breakout.*_arr_cents`.',
+            visibleConnectionIds: ['warehouse'],
+            loadSources: async () => [
+                { name: 'mart_nrr_quarterly', grain: [], columns: [], joins: [], measures: [], table: 'analytics.mart_nrr_quarterly' },
+                {
+                    name: 'mart_retention_movement_breakout',
+                    grain: [],
+                    columns: [],
+                    joins: [],
+                    measures: [],
+                    table: 'analytics.mart_retention_movement_breakout',
+                },
+            ],
+            tableExists: async () => true,
+        });
+        expect(invalid).toEqual([]);
+    });
+    it('does not treat inline-code SQL predicates as exact semantic-layer entity references', async () => {
+        const invalid = await findInvalidWikiBodyRefs({
+            pageKey: 'account-reporting-exclusions',
+            body: 'Exclude internal users with `users.is_internal = false` and test users with `users.is_test = false`.',
+            visibleConnectionIds: ['warehouse'],
+            loadSources: async () => [
+                {
+                    name: 'users',
+                    grain: [],
+                    columns: [
+                        { name: 'is_internal', type: 'boolean' },
+                        { name: 'is_test', type: 'boolean' },
+                    ],
+                    joins: [],
+                    measures: [],
+                    table: 'analytics.users',
+                },
+            ],
+            tableExists: async () => true,
+        });
+        expect(invalid).toEqual([]);
+    });
+    it('validates source, dimension, segment, measure, and table references', async () => {
+        const invalid = await findInvalidWikiBodyRefs({
+            pageKey: 'account-segments',
+            body: [
+                '`mart_account_segments.total_contract_arr`',
+                '`mart_account_segments.segment`',
+                '`mart_account_segments.enterprise`',
+                '`source:mart_account_segments`',
+                '`table:analytics.mart_account_segments`',
+            ].join('\n'),
+            visibleConnectionIds: ['warehouse'],
+            loadSources: async () => sources,
+            tableExists: async (_connectionId, tableRef) => tableRef === 'analytics.mart_account_segments',
+        });
+        expect(invalid).toEqual([]);
+    });
+    it('ignores two-part inline code when the source is not visible', async () => {
+        const invalid = await findInvalidWikiBodyRefs({
+            pageKey: 'engineering-notes',
+            body: [
+                'A version token like `node.v22` is not a semantic-layer reference.',
+                'A raw table must use `table:analytics.mart_account_segments`.',
+            ].join('\n'),
+            visibleConnectionIds: ['warehouse'],
+            loadSources: async () => sources,
+            tableExists: async (_connectionId, tableRef) => tableRef === 'analytics.mart_account_segments',
+        });
+        expect(invalid).toEqual([]);
+    });
+    it('still rejects explicit missing source and table references', async () => {
+        const invalid = await findInvalidWikiBodyRefs({
+            pageKey: 'account-segments',
+            body: [
+                '`source:missing_source`',
+                '`warehouse/source:missing_source`',
+                '`table:analytics.missing_table`',
+            ].join('\n'),
+            visibleConnectionIds: ['warehouse'],
+            loadSources: async () => sources,
+            tableExists: async () => false,
+        });
+        expect(invalid).toEqual([
+            'account-segments: unknown semantic-layer source missing_source',
+            'account-segments: unknown semantic-layer source warehouse/missing_source',
+            'account-segments: unknown raw table analytics.missing_table',
+        ]);
+    });
+});

package/node_modules/@ktx/context/dist/llm/claude-code-runtime.js

@@ -18,6 +18,7 @@ const BUILTIN_TOOLS = [
     'WebSearch',
     'TodoWrite',
 ];
+const KTX_MCP_SERVER_NAME = 'ktx';
 function isResult(message) {
     return message.type === 'result';
 }
@@ -66,11 +67,18 @@ function assertInitIsolation(message, allowedToolIds, expectedMcpServerNames) {
     }
 }
 function expectedMcpServerNames(tools) {
-    return tools && Object.keys(tools).length > 0 ? new Set(['ktx']) : new Set();
+    return tools && Object.keys(tools).length > 0 ? new Set([KTX_MCP_SERVER_NAME]) : new Set();
+}
+function managedMcpSettings(serverNames) {
+    return {
+        allowManagedMcpServersOnly: true,
+        allowedMcpServers: serverNames.map((serverName) => ({ serverName })),
+    };
 }
 function baseOptions(input) {
     const toolIds = mcpToolIds(input.tools ?? {});
     const allowedToolIds = new Set(toolIds);
+    const expectedServerNames = [...expectedMcpServerNames(input.tools)];
     return {
         cwd: input.projectDir,
         model: input.model,
@@ -79,6 +87,8 @@ function baseOptions(input) {
         skills: [],
         plugins: [],
         tools: [],
+        managedSettings: managedMcpSettings(expectedServerNames),
+        strictMcpConfig: true,
         allowedTools: toolIds,
         disallowedTools: BUILTIN_TOOLS,
         canUseTool: async (toolName, _toolInput, options) => allowedToolIds.has(toolName)
@@ -92,7 +102,14 @@ function baseOptions(input) {
         persistSession: false,
         env: createKtxClaudeCodeEnv(input.env),
         ...(input.tools && Object.keys(input.tools).length > 0
-            ? { mcpServers: { ktx: createSdkMcpServer({ name: 'ktx', tools: createClaudeSdkTools(input.tools) }) } }
+            ? {
+                mcpServers: {
+                    [KTX_MCP_SERVER_NAME]: createSdkMcpServer({
+                        name: KTX_MCP_SERVER_NAME,
+                        tools: createClaudeSdkTools(input.tools),
+                    }),
+                },
+            }
             : {}),
     };
 }

package/node_modules/@ktx/context/dist/llm/claude-code-runtime.test.js

@@ -66,6 +66,11 @@ describe('ClaudeCodeKtxLlmRuntime', () => {
                 skills: [],
                 plugins: [],
                 tools: [],
+                managedSettings: {
+                    allowManagedMcpServersOnly: true,
+                    allowedMcpServers: [],
+                },
+                strictMcpConfig: true,
                 allowedTools: [],
                 permissionMode: 'dontAsk',
                 persistSession: false,
@@ -125,6 +130,11 @@ describe('ClaudeCodeKtxLlmRuntime', () => {
         });
         const options = query.mock.calls[0][0].options;
         expect(options.allowedTools).toEqual(['mcp__ktx__load_skill']);
+        expect(options.managedSettings).toEqual({
+            allowManagedMcpServersOnly: true,
+            allowedMcpServers: [{ serverName: 'ktx' }],
+        });
+        expect(options.strictMcpConfig).toBe(true);
         expect(await options.canUseTool('mcp__ktx__load_skill', {}, { signal: new AbortController().signal, toolUseID: '1' })).toEqual({
             behavior: 'allow',
             toolUseID: '1',
@@ -155,6 +165,11 @@ describe('ClaudeCodeKtxLlmRuntime', () => {
             skills: [],
             plugins: [],
             tools: [],
+            managedSettings: {
+                allowManagedMcpServersOnly: true,
+                allowedMcpServers: [],
+            },
+            strictMcpConfig: true,
             allowedTools: [],
             permissionMode: 'dontAsk',
             persistSession: false,
@@ -233,6 +248,11 @@ describe('ClaudeCodeKtxLlmRuntime', () => {
         })).resolves.toEqual({ stopReason: 'budget' });
         const options = query.mock.calls[0][0].options;
         expect(options.allowedTools).toEqual(['mcp__ktx__load_skill']);
+        expect(options.managedSettings).toEqual({
+            allowManagedMcpServersOnly: true,
+            allowedMcpServers: [{ serverName: 'ktx' }],
+        });
+        expect(options.strictMcpConfig).toBe(true);
         expect(await options.canUseTool('mcp__ktx__load_skill', {}, { signal: new AbortController().signal, toolUseID: '1' })).toEqual({
             behavior: 'allow',
             toolUseID: '1',
@@ -287,6 +307,10 @@ describe('ClaudeCodeKtxLlmRuntime', () => {
             answer: 'yes',
         });
         expect(objectQuery.mock.calls[0][0].options.env).toEqual(expect.objectContaining({ PATH: '/usr/bin' }));
+        expect(objectQuery.mock.calls[0][0].options.managedSettings).toEqual({
+            allowManagedMcpServersOnly: true,
+            allowedMcpServers: [],
+        });
         expect(objectQuery.mock.calls[0][0].options.env).not.toEqual(expect.objectContaining({ ANTHROPIC_API_KEY: 'sk-ant-test', AWS_PROFILE: 'prod' }));
         const agentQuery = vi.fn((_input) => stream([
             initMessage({ tools: ['mcp__ktx__load_skill'], mcp_servers: [{ name: 'ktx', status: 'connected' }] }),
@@ -321,6 +345,10 @@ describe('ClaudeCodeKtxLlmRuntime', () => {
             telemetryTags: { operationName: 'test' },
         });
         expect(agentQuery.mock.calls[0][0].options.env).toEqual(expect.objectContaining({ HOME: '/Users/test' }));
+        expect(agentQuery.mock.calls[0][0].options.managedSettings).toEqual({
+            allowManagedMcpServersOnly: true,
+            allowedMcpServers: [{ serverName: 'ktx' }],
+        });
         expect(agentQuery.mock.calls[0][0].options.env).not.toEqual(expect.objectContaining({ ANTHROPIC_AUTH_TOKEN: 'token', CLAUDE_CODE_USE_VERTEX: '1' }));
     });
     it('logs and ignores onStepFinish callback errors', async () => {
@@ -376,6 +404,11 @@ describe('ClaudeCodeKtxLlmRuntime', () => {
             skills: [],
             plugins: [],
             tools: [],
+            managedSettings: {
+                allowManagedMcpServersOnly: true,
+                allowedMcpServers: [],
+            },
+            strictMcpConfig: true,
             allowedTools: [],
             persistSession: false,
             env: expect.not.objectContaining({ ANTHROPIC_API_KEY: 'sk-ant-test' }),

package/node_modules/@ktx/context/dist/project/setup-config.d.ts

@@ -1,5 +1,5 @@
 import type { KtxProjectConfig } from './config.js';
-export declare const KTX_SETUP_STEPS: readonly ["project", "llm", "embeddings", "databases", "sources", "context", "agents"];
+export declare const KTX_SETUP_STEPS: readonly ["project", "llm", "embeddings", "databases", "sources", "runtime", "context", "agents"];
 export type KtxSetupStep = (typeof KTX_SETUP_STEPS)[number];
 export interface KtxSetupState {
     completed_steps: KtxSetupStep[];

package/node_modules/@ktx/context/dist/project/setup-config.js

@@ -1,6 +1,15 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-export const KTX_SETUP_STEPS = ['project', 'llm', 'embeddings', 'databases', 'sources', 'context', 'agents'];
+export const KTX_SETUP_STEPS = [
+    'project',
+    'llm',
+    'embeddings',
+    'databases',
+    'sources',
+    'runtime',
+    'context',
+    'agents',
+];
 const SETUP_GITIGNORE_ENTRIES = [
     'cache/',
     'db.sqlite',

package/node_modules/@ktx/context/dist/project/setup-config.test.js

@@ -16,11 +16,12 @@ describe('KTX setup config helpers', () => {
         await markKtxSetupStateStepComplete(tempDir, 'project');
         await markKtxSetupStateStepComplete(tempDir, 'project');
         await markKtxSetupStateStepComplete(tempDir, 'llm');
+        await markKtxSetupStateStepComplete(tempDir, 'runtime');
         await markKtxSetupStateStepComplete(tempDir, 'context');
         expect(await readKtxSetupState(tempDir)).toEqual({
-            completed_steps: ['project', 'llm', 'context'],
+            completed_steps: ['project', 'llm', 'runtime', 'context'],
         });
-        await expect(readFile(join(tempDir, '.ktx', 'setup', 'state.json'), 'utf-8')).resolves.toBe(`${JSON.stringify({ completed_steps: ['project', 'llm', 'context'] }, null, 2)}\n`);
+        await expect(readFile(join(tempDir, '.ktx', 'setup', 'state.json'), 'utf-8')).resolves.toBe(`${JSON.stringify({ completed_steps: ['project', 'llm', 'runtime', 'context'] }, null, 2)}\n`);
     });
     it('sets setup database connection ids without duplicates', () => {
         const config = buildDefaultKtxProjectConfig();

package/node_modules/@ktx/context/dist/sl/tools/sl-edit-source.tool.js

@@ -1,6 +1,6 @@
 import YAML from 'yaml';
 import { z } from 'zod';
-import { addTouchedSlSource, validateActionRawPaths } from '../../tools/index.js';
+import { addTouchedSlSource, validateActionRawPaths, validateActionTargetConnection, } from '../../tools/index.js';
 import { applySqlEdits } from '../../tools/sql-edit-replacer.js';
 import { normalizeSemanticLayerDescriptions } from '../description-normalization.js';
 import { BaseSemanticLayerTool, } from './base-semantic-layer.tool.js';
@@ -59,6 +59,10 @@ If no source exists yet, use sl_write_source instead — this tool will reject t
         const { name: author, email: authorEmail } = await this.authorResolver.resolve(context.userId);
         const semanticLayerService = context.session?.semanticLayerService ?? this.semanticLayerService;
         const skipIndex = context.session?.isWorktreeScoped === true;
+        const targetConnectionValidation = validateActionTargetConnection(context.session, connectionId);
+        if (!targetConnectionValidation.ok) {
+            return this.buildOutput(false, [targetConnectionValidation.error], sourceName);
+        }
         const rawPathValidation = validateActionRawPaths(context.session, input.rawPaths);
         if (!rawPathValidation.ok) {
             return this.buildOutput(false, [rawPathValidation.error], sourceName);

package/node_modules/@ktx/context/dist/sl/tools/sl-edit-source.tool.test.js

@@ -80,6 +80,21 @@ describe('SlEditSourceTool — session gating', () => {
             targetConnectionId: warehouseConnectionId,
         }));
     });
+    it('rejects session-scoped edits outside allowed target connections', async () => {
+        const { tool } = makeTool();
+        const session = makeSession({
+            allowedConnectionNames: new Set(['warehouse']),
+        });
+        const context = { ...baseContext, session };
+        const result = await tool.call({
+            connectionId: 'finance',
+            sourceName: 'orders',
+            yaml_edits: [{ oldText: 'measures: []', newText: 'measures: []' }],
+        }, context);
+        expect(result.structured.success).toBe(false);
+        expect(result.markdown).toContain('connectionId "finance" is outside this ingest session');
+        expect(session.actions).toEqual([]);
+    });
     it('indexes normally when no session is present', async () => {
         const { tool, slSearchService } = makeTool();
         const result = await tool.call({

package/node_modules/@ktx/context/dist/sl/tools/sl-write-source.tool.js

@@ -1,6 +1,6 @@
 import YAML from 'yaml';
 import { z } from 'zod';
-import { addTouchedSlSource, validateActionRawPaths } from '../../tools/index.js';
+import { addTouchedSlSource, validateActionRawPaths, validateActionTargetConnection, } from '../../tools/index.js';
 import { sourceOverlaySchema } from '../schemas.js';
 import { BaseSemanticLayerTool, sourceDefinitionSchema, } from './base-semantic-layer.tool.js';
 import { normalizeSemanticLayerDescriptions } from '../description-normalization.js';
@@ -83,6 +83,10 @@ Do NOT join back to a table that the SQL already aggregates from if the grain co
         const { name: author, email: authorEmail } = await this.authorResolver.resolve(context.userId);
         const semanticLayerService = context.session?.semanticLayerService ?? this.semanticLayerService;
         const skipIndex = context.session?.isWorktreeScoped === true;
+        const targetConnectionValidation = validateActionTargetConnection(context.session, connectionId);
+        if (!targetConnectionValidation.ok) {
+            return this.buildOutput(false, [targetConnectionValidation.error], sourceName);
+        }
         const rawPathValidation = validateActionRawPaths(context.session, input.rawPaths);
         if (!rawPathValidation.ok) {
             return this.buildOutput(false, [rawPathValidation.error], sourceName);

package/node_modules/@ktx/context/dist/sl/tools/sl-write-source.tool.test.js

@@ -112,6 +112,28 @@ describe('SlWriteSourceTool — session gating', () => {
             targetConnectionId: warehouseConnectionId,
         }));
     });
+    it('rejects session-scoped writes outside allowed target connections', async () => {
+        const { tool } = makeTool();
+        const session = makeSession({
+            allowedConnectionNames: new Set(['warehouse']),
+        });
+        const context = { ...baseContext, session };
+        const result = await tool.call({
+            connectionId: 'finance',
+            sourceName: 'finance_orders',
+            source: {
+                name: 'finance_orders',
+                table: 'public.orders',
+                grain: ['id'],
+                columns: [{ name: 'id', type: 'string' }],
+                measures: [],
+                joins: [],
+            },
+        }, context);
+        expect(result.structured.success).toBe(false);
+        expect(result.markdown).toContain('connectionId "finance" is outside this ingest session');
+        expect(session.actions).toEqual([]);
+    });
     it('indexes normally when no session is present', async () => {
         const { tool, slSearchService } = makeTool();
         const result = await tool.call({

package/node_modules/@ktx/context/dist/tools/action-target-connection.d.ts

@@ -0,0 +1,9 @@
+import type { ToolSession } from './tool-session.js';
+type ActionTargetConnectionValidation = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function validateActionTargetConnection(session: ToolSession | undefined, connectionId: string): ActionTargetConnectionValidation;
+export {};

package/node_modules/@ktx/context/dist/tools/action-target-connection.js

@@ -0,0 +1,14 @@
+export function validateActionTargetConnection(session, connectionId) {
+    const allowed = session?.allowedConnectionNames;
+    if (!allowed) {
+        return { ok: true };
+    }
+    if (allowed.has(connectionId)) {
+        return { ok: true };
+    }
+    const allowedList = [...allowed].sort();
+    return {
+        ok: false,
+        error: `connectionId "${connectionId}" is outside this ingest session's allowed target connections: ${allowedList.length > 0 ? allowedList.join(', ') : '(none)'}`,
+    };
+}

package/node_modules/@ktx/context/dist/tools/context-candidate-write.tool.d.ts

@@ -13,9 +13,9 @@ declare const contextCandidateWriteInputSchema: z.ZodObject<{
     actionHint: z.ZodEnum<{
         merge: "merge";
         conflict: "conflict";
-        skip: "skip";
-        update: "update";
         create: "create";
+        update: "update";
+        skip: "skip";
     }>;
     durabilityScore: z.ZodNumber;
     authorityScore: z.ZodNumber;
@@ -48,9 +48,9 @@ export declare class ContextCandidateWriteTool extends BaseTool<typeof contextCa
         actionHint: z.ZodEnum<{
             merge: "merge";
             conflict: "conflict";
-            skip: "skip";
-            update: "update";
             create: "create";
+            update: "update";
+            skip: "skip";
         }>;
         durabilityScore: z.ZodNumber;
         authorityScore: z.ZodNumber;

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

@@ -14,5 +14,6 @@ export type { SqlEdit } from './sql-edit-replacer.js';
 export { applySqlEdits } from './sql-edit-replacer.js';
 export type { IngestToolMetadata, MemoryAction, ToolSession } from './tool-session.js';
 export { validateActionRawPaths } from './action-raw-paths.js';
+export { validateActionTargetConnection } from './action-target-connection.js';
 export type { TouchedSlSource, TouchedSlSourceSet } from './touched-sl-sources.js';
 export { addTouchedSlSource, createTouchedSlSources, deleteTouchedSlSource, hasTouchedSlSource, listTouchedSlSources, touchedSlSourceCount, touchedSlSourceNamesForConnection, } from './touched-sl-sources.js';

package/node_modules/@ktx/context/dist/tools/index.js

@@ -8,4 +8,5 @@ export { ContextEvidenceSearchTool } from './context-evidence-search.tool.js';
 export { ingestMetadataRequired, resolveIngestMetadata } from './context-ingest-metadata.js';
 export { applySqlEdits } from './sql-edit-replacer.js';
 export { validateActionRawPaths } from './action-raw-paths.js';
+export { validateActionTargetConnection } from './action-target-connection.js';
 export { addTouchedSlSource, createTouchedSlSources, deleteTouchedSlSource, hasTouchedSlSource, listTouchedSlSources, touchedSlSourceCount, touchedSlSourceNamesForConnection, } from './touched-sl-sources.js';

package/node_modules/@ktx/context/dist/wiki/local-knowledge.js

@@ -211,6 +211,7 @@ async function searchLocalKnowledgePagesWithSqlite(project, input) {
         },
         {
             lane: 'semantic',
+            weight: 3,
             async generate(args) {
                 if (!embeddingService) {
                     return { status: 'skipped', candidates: [], reason: 'embedding_unconfigured' };
@@ -222,7 +223,9 @@ async function searchLocalKnowledgePagesWithSqlite(project, input) {
                         limit: args.laneCandidatePoolLimit,
                     });
                     return {
-                        candidates: rows.map((row) => ({ id: row.id, rank: row.rank, rawScore: row.rawScore })),
+                        candidates: rows
+                            .filter((row) => row.rawScore > 0)
+                            .map((row, index) => ({ id: row.id, rank: index + 1, rawScore: row.rawScore })),
                     };
                 }
                 catch (error) {

package/node_modules/@ktx/context/dist/wiki/local-knowledge.test.js

@@ -13,6 +13,22 @@ class FakeEmbeddingPort {
         return Promise.all(texts.map((text) => this.computeEmbedding(text)));
     }
 }
+class ArrSynonymEmbeddingPort {
+    maxBatchSize = 16;
+    async computeEmbedding(text) {
+        const lower = text.toLowerCase();
+        if (lower.trim() === 'annual recurring revenue' || lower.includes('arr') || lower.includes('contract-first')) {
+            return [1, 0];
+        }
+        if (lower.includes('net revenue') || lower.includes('gross') || lower.includes('refund')) {
+            return [0, 1];
+        }
+        return [0.5, 0.5];
+    }
+    async computeEmbeddingsBulk(texts) {
+        return Promise.all(texts.map((text) => this.computeEmbedding(text)));
+    }
+}
 describe('local knowledge helpers', () => {
     let tempDir;
     let project;
@@ -108,6 +124,34 @@ describe('local knowledge helpers', () => {
             lanes: expect.arrayContaining([expect.objectContaining({ lane: 'semantic', status: 'available' })]),
         });
     });
+    it('ranks ARR synonym queries by semantic page embeddings over stronger lexical revenue matches', async () => {
+        await writeLocalKnowledgePage(project, {
+            key: 'arr-definition',
+            scope: 'GLOBAL',
+            summary: 'ARR is calculated contract-first for active customer contracts.',
+            content: 'Contract-first active contract value takes precedence over subscription values.',
+            tags: ['arr', 'contracts', 'finance'],
+        });
+        await writeLocalKnowledgePage(project, {
+            key: 'net-revenue-definition',
+            scope: 'GLOBAL',
+            summary: 'Net revenue definition',
+            content: 'Annual revenue is gross invoice revenue minus credits and refunds.',
+            tags: ['revenue', 'finance'],
+        });
+        const search = await searchLocalKnowledgePages(project, {
+            query: 'annual recurring revenue',
+            userId: 'local',
+            limit: 2,
+            embeddingService: new ArrSynonymEmbeddingPort(),
+        });
+        expect(search.map((result) => result.key)).toEqual(['arr-definition', 'net-revenue-definition']);
+        expect(search[0]).toMatchObject({
+            key: 'arr-definition',
+            matchReasons: expect.arrayContaining(['semantic']),
+            lanes: expect.arrayContaining([expect.objectContaining({ lane: 'semantic', status: 'available' })]),
+        });
+    });
     it('reports semantic lane as skipped when wiki embeddings are not configured', async () => {
         await writeLocalKnowledgePage(project, {
             key: 'metrics-revenue',

package/node_modules/@ktx/context/dist/wiki/tools/wiki-write.tool.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { validateFlatWikiKey } from '../keys.js';
+import { findMissingWikiRefs } from '../wiki-ref-validation.js';
 import { applySqlEdits } from '../../tools/sql-edit-replacer.js';
 import { BaseTool, validateActionRawPaths } from '../../tools/index.js';
 const MAX_USER_BLOCKS = 100;
@@ -51,53 +52,6 @@ function normalizeAccidentalEscapedMarkdownNewlines(content) {
         return content;
     return content.replace(/\\r\\n/g, '\n').replace(/\\n/g, '\n').replace(/\\r/g, '\n');
 }
-function isWikiPageKeyRef(ref) {
-    return /^[a-z0-9][a-z0-9_-]*(?:-[a-z0-9_]+)*$/.test(ref);
-}
-function extractInlineWikiRefs(content) {
-    const refs = new Set();
-    const re = /\[\[([^\]\n]+)\]\]/g;
-    for (const match of content.matchAll(re)) {
-        const target = match[1]?.split('|', 1)[0]?.trim();
-        if (target && isWikiPageKeyRef(target)) {
-            refs.add(target);
-        }
-    }
-    return [...refs].sort();
-}
-async function visibleWikiPageKeys(wikiService, scope, scopeId) {
-    const keys = new Set();
-    if (scope === 'USER') {
-        for (const key of await wikiService.listPageKeys('GLOBAL', null)) {
-            keys.add(key);
-        }
-        for (const key of await wikiService.listPageKeys('USER', scopeId)) {
-            keys.add(key);
-        }
-        return keys;
-    }
-    for (const key of await wikiService.listPageKeys('GLOBAL', null)) {
-        keys.add(key);
-    }
-    return keys;
-}
-async function findMissingWikiRefs(input) {
-    const candidates = new Set();
-    for (const ref of input.refs ?? []) {
-        if (isWikiPageKeyRef(ref)) {
-            candidates.add(ref);
-        }
-    }
-    for (const ref of extractInlineWikiRefs(input.content)) {
-        candidates.add(ref);
-    }
-    if (candidates.size === 0) {
-        return [];
-    }
-    const available = await visibleWikiPageKeys(input.wikiService, input.scope, input.scopeId);
-    available.add(input.pageKey);
-    return [...candidates].filter((ref) => !available.has(ref)).sort();
-}
 export class WikiWriteTool extends BaseTool {
     wikiService;
     pagesRepository;
@@ -208,7 +162,8 @@ Keys must be flat file names, not directory paths. Use tags/source frontmatter f
             refs: finalFm.refs,
             content: finalContent,
         });
-        if (missingRefs.length > 0) {
+        const deferMissingRefs = !!context.session?.ingest;
+        if (!deferMissingRefs && missingRefs.length > 0) {
             return {
                 markdown: `Error: wiki references target missing page(s): ${missingRefs.join(', ')}. ` +
                     'Create those pages first, retarget the links, or remove the refs.',

package/node_modules/@ktx/context/dist/wiki/tools/wiki-write.tool.test.js

@@ -233,4 +233,32 @@ describe('WikiWriteTool', () => {
         expect(result.markdown).toMatch(/orbit-team-lanes-detail/);
         expect(wikiService.writePage).not.toHaveBeenCalled();
     });
+    it('accepts forward refs during ingest sessions for post-pass validation', async () => {
+        const { tool, wikiService } = makeTool({
+            wikiService: {
+                listPageKeys: vi.fn().mockResolvedValue(['orbit-company-overview']),
+            },
+        });
+        const session = {
+            connectionId: 'conn-1',
+            isWorktreeScoped: true,
+            preHead: null,
+            touchedSlSources: createTouchedSlSources(),
+            actions: [],
+            semanticLayerService: {},
+            wikiService: wikiService,
+            configService: {},
+            gitService: {},
+            ingest: { runId: 'run-1', jobId: 'job-1', syncId: 'sync-1', sourceKey: 'notion' },
+        };
+        const result = await tool.call({
+            key: 'orbit-how-we-work',
+            summary: 'Operating norms',
+            content: 'See [[orbit-team-lanes-detail]].',
+            refs: ['orbit-company-overview', 'orbit-team-lanes-detail'],
+        }, { ...baseContext, session });
+        expect(result.structured).toMatchObject({ success: true, key: 'orbit-how-we-work', action: 'created' });
+        expect(wikiService.writePage).toHaveBeenCalledTimes(1);
+        expect(session.actions).toContainEqual(expect.objectContaining({ target: 'wiki', type: 'created', key: 'orbit-how-we-work' }));
+    });
 });