@kaelio/ktx 0.1.1 → 0.3.0

package/dist/scan.js

@@ -1,5 +1,5 @@
-import { loadKtxProject } from '@ktx/context/project';
 import { runLocalScan, } from '@ktx/context/scan';
+import { loadKtxCliProject } from './cli-project.js';
 import { createKtxCliLocalIngestAdapters } from './local-adapters.js';
 import { createKtxCliScanConnector } from './local-scan-connectors.js';
 import { profileMark } from './startup-profile.js';
@@ -237,7 +237,12 @@ export function createCliScanProgress(io, state = { progress: 0, hasPendingTrans
 }
 export async function runKtxScan(args, io = process, deps = {}) {
     try {
-        const project = await loadKtxProject({ projectDir: args.projectDir });
+        const project = await loadKtxCliProject({
+            projectDir: args.projectDir,
+            cliVersion: args.cliVersion ?? '0.0.0-private',
+            installPolicy: args.runtimeInstallPolicy ?? 'never',
+            io,
+        });
         const managedDaemon = managedDaemonOptionsForScanRun(args, deps.runtimeIo ?? io);
         const connector = args.mode !== 'structural' || args.detectRelationships
             ? await createKtxCliScanConnector(project, args.connectionId)

package/dist/scan.test.js

@@ -287,14 +287,14 @@ describe('runKtxScan', () => {
         expect(io.stdout()).toContain('Report: raw-sources/warehouse/live-database/sync-1/scan-report.json');
         expect(io.stdout()).toContain('Next:\n');
         expect(io.stdout()).toContain('ktx status --project-dir ');
-        expect(io.stdout()).not.toContain('ktx dev scan status');
-        expect(io.stdout()).not.toContain('ktx dev scan report');
+        expect(io.stdout()).not.toContain('ktx admin scan status');
+        expect(io.stdout()).not.toContain('ktx admin scan report');
         expect(io.stdout()).not.toContain('\u001b[');
         expect(io.stdout()).not.toContain('✓');
         expect(io.stdout()).not.toContain('+1');
         expect(io.stdout()).not.toContain('/~');
     });
-    it('passes managed daemon options to local ingest adapters when no explicit daemon URL is set', async () => {
+    it('passes KTX daemon options to local ingest adapters when no explicit daemon URL is set', async () => {
         await initKtxProject({ projectDir: tempDir });
         const createLocalIngestAdapters = vi.fn(() => []);
         const runLocalScan = vi.fn(async (_input) => ({

package/dist/setup-agents.js

@@ -426,8 +426,8 @@ function cliInstructionContent(input) {
         'Available commands:',
         '',
         `- \`${ktxCommandLine(input.launcher, ['status', ...jsonProjectDirArgs])}\``,
-        `- \`${ktxCommandLine(input.launcher, ['sl', 'list', ...jsonProjectDirArgs])}\``,
-        `- \`${ktxCommandLine(input.launcher, ['sl', 'search', '<text>', ...jsonProjectDirArgs, '--connection-id', '<id>'])}\``,
+        `- \`${ktxCommandLine(input.launcher, ['sl', ...jsonProjectDirArgs])}\``,
+        `- \`${ktxCommandLine(input.launcher, ['sl', '<text>', ...jsonProjectDirArgs, '--connection-id', '<id>'])}\``,
         `- \`${ktxCommandLine(input.launcher, [
             'sl',
             'query',
@@ -442,7 +442,7 @@ function cliInstructionContent(input) {
             '--max-rows',
             '100',
         ])}\``,
-        `- \`${ktxCommandLine(input.launcher, ['wiki', 'search', '<query>', ...jsonProjectDirArgs, '--limit', '10'])}\``,
+        `- \`${ktxCommandLine(input.launcher, ['wiki', '<query>', ...jsonProjectDirArgs, '--limit', '10'])}\``,
         '',
         'Use semantic-layer queries before direct database access. Do not print secrets or credential references.',
         '',

package/dist/setup-agents.test.js

@@ -149,7 +149,7 @@ describe('setup agents', () => {
         expect(skill).toContain(`--project-dir ${tempDir}`);
         expect(skill).toContain('must not print secrets');
         expect(skill).toContain('status --json');
-        expect(skill).toContain('sl list --json');
+        expect(skill).toContain('sl --json');
         expect(skill).toContain('sl query');
         expect(skill).toContain('--format json');
         expect(skill).not.toContain('sl query --json');

package/dist/setup-embeddings.js

@@ -209,12 +209,12 @@ function localEmbeddingSetupMessage(message, stderrTail = []) {
     const lines = [
         `Local embedding health check failed: ${message}`,
         'Local embeddings use the KTX-managed Python runtime.',
-        'Prepare the runtime with: ktx dev runtime start --feature local-embeddings',
+        'Prepare the runtime with: ktx admin runtime start --feature local-embeddings',
         'Use --yes with setup to install and start the runtime without prompting.',
         'The first run may download Python packages and the all-MiniLM-L6-v2 model.',
     ];
     if (stderrTail.length > 0) {
-        lines.push('Recent local embeddings daemon stderr:', ...stderrTail);
+        lines.push('Recent KTX daemon stderr:', ...stderrTail);
     }
     return lines.join('\n');
 }

package/dist/setup-embeddings.test.js

@@ -225,7 +225,7 @@ describe('setup embeddings step', () => {
     it('fails non-interactive local setup when the managed local embeddings runtime is missing', async () => {
         const io = makeIo();
         const ensureLocalEmbeddings = vi.fn(async () => {
-            throw new Error('KTX Python runtime is required for this command. Run: ktx dev runtime install --feature local-embeddings --yes');
+            throw new Error('KTX Python runtime is required for this command. Run: ktx admin runtime install --feature local-embeddings --yes');
         });
         const result = await runKtxSetupEmbeddingsStep({
             projectDir: tempDir,
@@ -235,7 +235,7 @@ describe('setup embeddings step', () => {
             skipEmbeddings: false,
         }, io.io, { env: {}, ensureLocalEmbeddings });
         expect(result.status).toBe('failed');
-        expect(io.stderr()).toContain('KTX Python runtime is required for this command. Run: ktx dev runtime install --feature local-embeddings --yes');
+        expect(io.stderr()).toContain('KTX Python runtime is required for this command. Run: ktx admin runtime install --feature local-embeddings --yes');
     });
     it('does not persist embedding completion when the health check fails', async () => {
         const io = makeIo();
@@ -255,7 +255,7 @@ describe('setup embeddings step', () => {
         expect(await readFile(join(tempDir, 'ktx.yaml'), 'utf-8')).not.toContain('completed_steps:');
         expect(config.ingest.embeddings.backend).toBe('none');
         expect(io.stderr()).toContain('Local embedding health check failed: 401 invalid api key [redacted]');
-        expect(io.stderr()).toContain('Prepare the runtime with: ktx dev runtime start --feature local-embeddings');
+        expect(io.stderr()).toContain('Prepare the runtime with: ktx admin runtime start --feature local-embeddings');
         expect(io.stderr()).not.toContain('skip for now');
     });
     it('prints the recent daemon stderr tail when local embedding health check fails', async () => {
@@ -275,7 +275,7 @@ describe('setup embeddings step', () => {
             healthCheck: vi.fn(async () => ({ ok: false, message: 'HTTP 500' })),
         });
         expect(result.status).toBe('failed');
-        expect(io.stderr()).toContain('Recent local embeddings daemon stderr:');
+        expect(io.stderr()).toContain('Recent KTX daemon stderr:');
         expect(io.stderr()).toContain('daemon traceback line 6');
         expect(io.stderr()).toContain('daemon traceback line 45');
         expect(io.stderr()).not.toContain('daemon traceback line 5');
@@ -296,7 +296,7 @@ describe('setup embeddings step', () => {
             healthCheck: vi.fn(async () => ({ ok: false, message: 'HTTP 500' })),
         });
         expect(result.status).toBe('failed');
-        expect(io.stderr()).not.toContain('Recent local embeddings daemon stderr:');
+        expect(io.stderr()).not.toContain('Recent KTX daemon stderr:');
     });
     it('uses fixed OpenAI defaults and only asks for credentials when OpenAI is selected', async () => {
         const io = makeIo();

package/dist/setup-runtime.test.js

@@ -56,7 +56,7 @@ describe('runKtxSetupRuntimeStep', () => {
     it('fails fast when required runtime features cannot be installed in no-input mode', async () => {
         const io = makeIo();
         const ensureRuntime = vi.fn(async () => {
-            throw new Error('KTX Python runtime is required for this command. Run: ktx dev runtime install --yes');
+            throw new Error('KTX Python runtime is required for this command. Run: ktx admin runtime install --yes');
         });
         await expect(runKtxSetupRuntimeStep({
             projectDir: tempDir,
@@ -71,9 +71,9 @@ describe('runKtxSetupRuntimeStep', () => {
         })).resolves.toMatchObject({ status: 'failed' });
         expect(ensureRuntime).toHaveBeenCalledWith(expect.objectContaining({ installPolicy: 'never' }));
         expect((await readKtxSetupState(tempDir)).completed_steps).not.toContain('runtime');
-        expect(io.stderr()).toContain('ktx dev runtime install --yes');
+        expect(io.stderr()).toContain('ktx admin runtime install --yes');
     });
-    it('starts the managed local embeddings daemon for configured sentence-transformers embeddings', async () => {
+    it('starts the KTX daemon for configured sentence-transformers embeddings', async () => {
         const io = makeIo();
         const ensureLocalEmbeddings = vi.fn(async () => ({
             baseUrl: 'http://127.0.0.1:61234',

package/dist/sl.js

@@ -99,7 +99,7 @@ export async function runKtxSl(args, io = process, deps = {}) {
             await printSlSources({
                 rows: sources,
                 emptyMessage: `No semantic-layer sources matched "${args.query}" in ${project.projectDir}`,
-                emptyHint: 'Run `ktx sl list` to inspect available sources.',
+                emptyHint: 'Run `ktx sl` to inspect available sources.',
                 command: 'sl search',
                 output: args.output,
                 json: args.json,

package/dist/standalone-smoke.test.js

@@ -116,6 +116,10 @@ describe('standalone built ktx CLI smoke', () => {
         const init = await runSetupNewProject(projectDir);
         expectSetupStderr(init);
         expect(init.stdout).toContain(`Project: ${projectDir}`);
+        const reindex = await runBuiltCli(['--project-dir', projectDir, 'admin', 'reindex', '--output', 'plain']);
+        expect(reindex.code).toBe(0);
+        expect(reindex.stdout).toContain('reindex\t');
+        expect(reindex.stderr).toContain('wiki/global');
         const run = await runBuiltCli([
             'ingest',
             'run',
@@ -125,7 +129,7 @@ describe('standalone built ktx CLI smoke', () => {
             'fake',
         ]);
         expect(run).toMatchObject({ code: 1, stdout: '' });
-        expect(run.stderr).toContain("unknown option '--connection-id'");
+        expect(run.stderr).toContain("unknown option '--adapter'");
     });
     it('rejects the removed agent command through the built binary', async () => {
         const result = await runBuiltCli(['agent']);
@@ -235,7 +239,7 @@ describe('standalone built ktx CLI smoke', () => {
         ]);
         expect(add.code).toBe(1);
         expect(add.stdout).toBe('');
-        expect(add.stderr).toContain("unknown command 'add'");
+        expect(add.stderr).toMatch(/unknown (command|option)|too many arguments/);
         const yaml = await readFile(join(projectDir, 'ktx.yaml'), 'utf-8');
         expect(yaml).not.toContain('driver: notion');
         expect(yaml).not.toContain('auth_token_ref: env:NOTION_TOKEN');

package/node_modules/@ktx/context/dist/core/git.service.d.ts

@@ -101,6 +101,7 @@ export declare class GitService {
         status: 'A' | 'M' | 'D';
         path: string;
     }>>;
+    changedPaths(): 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/node_modules/@ktx/context/dist/core/git.service.js

@@ -424,6 +424,18 @@ export class GitService {
         }
         return out;
     }
+    async changedPaths() {
+        const raw = await this.git.raw(['status', '--porcelain=v1', '-z']);
+        const fields = raw.split('\0').filter(Boolean);
+        const paths = [];
+        for (const field of fields) {
+            const path = field.slice(3);
+            if (path.length > 0) {
+                paths.push(path);
+            }
+        }
+        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.

package/node_modules/@ktx/context/dist/index-sync/index.d.ts

@@ -0,0 +1,2 @@
+export type { ReindexOptions, ReindexScopeResult, ReindexSummary, ReindexWorkResult } from './types.js';
+export { discoverReindexScopes, reindexLocalIndexes } from './reindex.js';

package/node_modules/@ktx/context/dist/index-sync/index.js

@@ -0,0 +1 @@
+export { discoverReindexScopes, reindexLocalIndexes } from './reindex.js';

package/node_modules/@ktx/context/dist/index-sync/reindex.d.ts

@@ -0,0 +1,20 @@
+import { type KtxLocalProject } from '../project/index.js';
+import type { ReindexOptions, ReindexSummary } from './types.js';
+type DiscoveredScope = {
+    kind: 'wiki';
+    scope: 'GLOBAL';
+    scopeId: null;
+    label: 'global';
+} | {
+    kind: 'wiki';
+    scope: 'USER';
+    scopeId: string;
+    label: `user/${string}`;
+} | {
+    kind: 'sl';
+    connectionId: string;
+    label: string;
+};
+export declare function discoverReindexScopes(project: KtxLocalProject): Promise<DiscoveredScope[]>;
+export declare function reindexLocalIndexes(project: KtxLocalProject, options: ReindexOptions): Promise<ReindexSummary>;
+export {};

package/node_modules/@ktx/context/dist/index-sync/reindex.js

@@ -0,0 +1,141 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { ktxLocalStateDbPath } from '../project/index.js';
+import { loadLocalSlSourceRecords, SlSearchService, SqliteSlSourcesIndex } from '../sl/index.js';
+import { KnowledgeWikiService, SqliteKnowledgeIndex } from '../wiki/index.js';
+const ZERO = {
+    scanned: 0,
+    updated: 0,
+    deleted: 0,
+    embeddingsRecomputed: 0,
+    embeddingsFailed: 0,
+};
+async function directoryExists(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function childDirectories(path) {
+    try {
+        const entries = await readdir(path, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort((left, right) => left.localeCompare(right));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+export async function discoverReindexScopes(project) {
+    const scopes = [];
+    if (await directoryExists(join(project.projectDir, 'wiki/global'))) {
+        scopes.push({ kind: 'wiki', scope: 'GLOBAL', scopeId: null, label: 'global' });
+    }
+    for (const userId of await childDirectories(join(project.projectDir, 'wiki/user'))) {
+        scopes.push({ kind: 'wiki', scope: 'USER', scopeId: userId, label: `user/${userId}` });
+    }
+    for (const connectionId of await childDirectories(join(project.projectDir, 'semantic-layer'))) {
+        if (connectionId !== '_schema') {
+            scopes.push({ kind: 'sl', connectionId, label: connectionId });
+        }
+    }
+    return scopes;
+}
+function errorMessage(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    return error.name && error.name !== 'Error' ? `${error.name}: ${error.message}` : error.message;
+}
+function addTotals(left, right) {
+    return {
+        scanned: left.scanned + right.scanned,
+        updated: left.updated + right.updated,
+        deleted: left.deleted + right.deleted,
+        embeddingsRecomputed: left.embeddingsRecomputed + right.embeddingsRecomputed,
+        embeddingsFailed: left.embeddingsFailed + right.embeddingsFailed,
+    };
+}
+function durationSince(startedAt) {
+    return Number((process.hrtime.bigint() - startedAt) / 1000000n);
+}
+function embeddingFailureError(work) {
+    if (work.embeddingsFailed === 0) {
+        return undefined;
+    }
+    return `${work.embeddingsFailed} embedding recomputation${work.embeddingsFailed === 1 ? '' : 's'} failed`;
+}
+export async function reindexLocalIndexes(project, options) {
+    const startedAt = process.hrtime.bigint();
+    const dbPath = ktxLocalStateDbPath(project);
+    const scopes = await discoverReindexScopes(project);
+    const wikiIndex = new SqliteKnowledgeIndex({ dbPath });
+    const slIndex = new SqliteSlSourcesIndex({ dbPath });
+    const wikiService = new KnowledgeWikiService(project.fileStore, options.embeddingService, wikiIndex, project.git);
+    const slService = new SlSearchService(options.embeddingService, slIndex);
+    const results = [];
+    for (const scope of scopes) {
+        const scopeStartedAt = process.hrtime.bigint();
+        try {
+            let work;
+            if (scope.kind === 'wiki') {
+                if (options.force) {
+                    wikiIndex.clear(scope.scope, scope.scopeId);
+                }
+                work = await wikiService.syncIndex(scope.scope, scope.scopeId);
+                results.push({
+                    kind: 'wiki',
+                    label: scope.label,
+                    scope: scope.scope === 'GLOBAL' ? 'global' : 'user',
+                    scopeId: scope.scopeId,
+                    ...work,
+                    ...(options.force ? { deleted: 0 } : {}),
+                    ...(options.embeddingService && work.embeddingsFailed > 0 ? { error: embeddingFailureError(work) } : {}),
+                    durationMs: durationSince(scopeStartedAt),
+                });
+                continue;
+            }
+            if (options.force) {
+                await slIndex.clear(scope.connectionId);
+            }
+            const records = await loadLocalSlSourceRecords(project, { connectionId: scope.connectionId });
+            work = await slService.indexSources(scope.connectionId, records.map((record) => record.source));
+            results.push({
+                kind: 'sl',
+                label: scope.label,
+                connectionId: scope.connectionId,
+                ...work,
+                ...(options.force ? { deleted: 0 } : {}),
+                ...(options.embeddingService && work.embeddingsFailed > 0 ? { error: embeddingFailureError(work) } : {}),
+                durationMs: durationSince(scopeStartedAt),
+            });
+        }
+        catch (error) {
+            results.push({
+                kind: scope.kind,
+                label: scope.label,
+                ...(scope.kind === 'wiki'
+                    ? { scope: scope.scope === 'GLOBAL' ? 'global' : 'user', scopeId: scope.scopeId }
+                    : { connectionId: scope.connectionId }),
+                ...ZERO,
+                durationMs: durationSince(scopeStartedAt),
+                error: errorMessage(error),
+            });
+        }
+    }
+    return {
+        scopes: results,
+        totals: results.reduce(addTotals, ZERO),
+        dbPath: relative(project.projectDir, dbPath) || dbPath,
+        force: options.force,
+        embeddingsAvailable: options.embeddingService !== null,
+        durationMs: durationSince(startedAt),
+    };
+}

package/node_modules/@ktx/context/dist/index-sync/reindex.test.d.ts

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

package/node_modules/@ktx/context/dist/index-sync/reindex.test.js

@@ -0,0 +1,139 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { initKtxProject, loadKtxProject } from '../project/index.js';
+import { SqliteKnowledgeIndex } from '../wiki/sqlite-knowledge-index.js';
+import { reindexLocalIndexes } from './reindex.js';
+class FakeEmbeddingPort {
+    maxBatchSize = 8;
+    async computeEmbedding(text) {
+        return [text.length, 1];
+    }
+    async computeEmbeddingsBulk(texts) {
+        return texts.map((text) => [text.length, 1]);
+    }
+}
+async function createProject(tempDir) {
+    await initKtxProject({ projectDir: tempDir, force: true });
+    return loadKtxProject({ projectDir: tempDir });
+}
+describe('reindexLocalIndexes', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-reindex-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('returns an empty summary when no wiki or semantic-layer directories exist', async () => {
+        const project = await createProject(tempDir);
+        await rm(join(project.projectDir, 'wiki'), { recursive: true, force: true });
+        await rm(join(project.projectDir, 'semantic-layer'), { recursive: true, force: true });
+        await expect(reindexLocalIndexes(project, { force: false, embeddingService: null })).resolves.toMatchObject({
+            scopes: [],
+            totals: { scanned: 0, updated: 0, deleted: 0, embeddingsRecomputed: 0, embeddingsFailed: 0 },
+            force: false,
+            embeddingsAvailable: false,
+        });
+    });
+    it('discovers empty directories as zero-row scopes', async () => {
+        const project = await createProject(tempDir);
+        await mkdir(join(project.projectDir, 'wiki/user/local'), { recursive: true });
+        await mkdir(join(project.projectDir, 'semantic-layer/warehouse'), { recursive: true });
+        const summary = await reindexLocalIndexes(project, { force: false, embeddingService: null });
+        expect(summary.scopes.map((scope) => scope.label)).toEqual(['global', 'user/local', 'warehouse']);
+        expect(summary.totals.scanned).toBe(0);
+    });
+    it('indexes mixed wiki and SL sources and reports totals', async () => {
+        const project = await createProject(tempDir);
+        await writeFile(join(project.projectDir, 'wiki/global/revenue.md'), '---\nsummary: Revenue\nusage_mode: auto\n---\n\nPaid orders.\n', 'utf-8');
+        await mkdir(join(project.projectDir, 'semantic-layer/warehouse'), { recursive: true });
+        await writeFile(join(project.projectDir, 'semantic-layer/warehouse/orders.yaml'), 'name: orders\ntable: public.orders\ngrain: [id]\ncolumns:\n  - name: id\n    type: number\njoins: []\nmeasures: []\n', 'utf-8');
+        const summary = await reindexLocalIndexes(project, {
+            force: false,
+            embeddingService: new FakeEmbeddingPort(),
+        });
+        expect(summary.scopes).toHaveLength(2);
+        expect(summary.totals).toMatchObject({ scanned: 2, updated: 2, deleted: 0, embeddingsRecomputed: 2 });
+        expect(summary.embeddingsAvailable).toBe(true);
+    });
+    it('does not report unchanged lexical-only rows as updated on repeated runs', async () => {
+        const project = await createProject(tempDir);
+        await writeFile(join(project.projectDir, 'wiki/global/revenue.md'), '---\nsummary: Revenue\nusage_mode: auto\n---\n\nPaid orders.\n', 'utf-8');
+        await mkdir(join(project.projectDir, 'semantic-layer/warehouse'), { recursive: true });
+        await writeFile(join(project.projectDir, 'semantic-layer/warehouse/orders.yaml'), 'name: orders\ntable: public.orders\ngrain: [id]\ncolumns:\n  - name: id\n    type: number\njoins: []\nmeasures: []\n', 'utf-8');
+        const first = await reindexLocalIndexes(project, { force: false, embeddingService: null });
+        expect(first.totals).toMatchObject({
+            scanned: 2,
+            updated: 2,
+            deleted: 0,
+            embeddingsRecomputed: 0,
+            embeddingsFailed: 0,
+        });
+        const second = await reindexLocalIndexes(project, { force: false, embeddingService: null });
+        expect(second.totals).toMatchObject({
+            scanned: 2,
+            updated: 0,
+            deleted: 0,
+            embeddingsRecomputed: 0,
+            embeddingsFailed: 0,
+        });
+        expect(second.scopes.map((scope) => [scope.label, scope.updated])).toEqual([
+            ['global', 0],
+            ['warehouse', 0],
+        ]);
+    });
+    it('force clears stale rows before rebuilding each discovered scope', async () => {
+        const project = await createProject(tempDir);
+        const wikiIndex = new SqliteKnowledgeIndex({ dbPath: join(project.projectDir, '.ktx/db.sqlite') });
+        wikiIndex.sync([
+            {
+                path: 'wiki/global/stale.md',
+                key: 'stale',
+                scope: 'GLOBAL',
+                scopeId: null,
+                summary: 'Stale',
+                content: 'Stale content',
+                tags: [],
+                embedding: [1, 0],
+            },
+        ]);
+        await writeFile(join(project.projectDir, 'wiki/global/revenue.md'), '---\nsummary: Revenue\nusage_mode: auto\n---\n\nPaid orders.\n', 'utf-8');
+        const summary = await reindexLocalIndexes(project, {
+            force: true,
+            embeddingService: new FakeEmbeddingPort(),
+        });
+        expect(summary.force).toBe(true);
+        expect(summary.totals).toMatchObject({ scanned: 1, updated: 1, deleted: 0 });
+        expect(wikiIndex.search('Stale', 10)).toEqual([]);
+    });
+    it('captures a per-scope error and continues other scopes', async () => {
+        const project = await createProject(tempDir);
+        await writeFile(join(project.projectDir, 'wiki/global/revenue.md'), '---\nsummary: Revenue\nusage_mode: auto\n---\n\nPaid orders.\n', 'utf-8');
+        await mkdir(join(project.projectDir, 'semantic-layer/warehouse'), { recursive: true });
+        await writeFile(join(project.projectDir, 'semantic-layer/warehouse/broken.yaml'), 'not: [valid', 'utf-8');
+        const summary = await reindexLocalIndexes(project, { force: false, embeddingService: null });
+        expect(summary.scopes.find((scope) => scope.label === 'global')?.error).toBeUndefined();
+        expect(summary.scopes.find((scope) => scope.label === 'warehouse')?.error).toContain('YAML');
+    });
+    it('marks a scope errored when configured embeddings fail', async () => {
+        const project = await createProject(tempDir);
+        await writeFile(join(project.projectDir, 'wiki/global/revenue.md'), '---\nsummary: Revenue\nusage_mode: auto\n---\n\nPaid orders.\n', 'utf-8');
+        const embeddingService = {
+            maxBatchSize: 8,
+            async computeEmbedding() {
+                throw new Error('embedding provider unavailable');
+            },
+            async computeEmbeddingsBulk() {
+                throw new Error('embedding provider unavailable');
+            },
+        };
+        const summary = await reindexLocalIndexes(project, { force: false, embeddingService });
+        expect(summary.scopes[0]).toMatchObject({
+            label: 'global',
+            embeddingsFailed: 1,
+            error: '1 embedding recomputation failed',
+        });
+    });
+});

package/node_modules/@ktx/context/dist/index-sync/types.d.ts

@@ -0,0 +1,29 @@
+import type { KtxEmbeddingPort } from '../core/index.js';
+export interface ReindexOptions {
+    force: boolean;
+    embeddingService: KtxEmbeddingPort | null;
+}
+export interface ReindexWorkResult {
+    scanned: number;
+    updated: number;
+    deleted: number;
+    embeddingsRecomputed: number;
+    embeddingsFailed: number;
+}
+export interface ReindexScopeResult extends ReindexWorkResult {
+    kind: 'wiki' | 'sl';
+    label: string;
+    scope?: 'global' | 'user';
+    scopeId?: string | null;
+    connectionId?: string;
+    durationMs: number;
+    error?: string;
+}
+export interface ReindexSummary {
+    scopes: ReindexScopeResult[];
+    totals: ReindexWorkResult;
+    dbPath: string;
+    force: boolean;
+    embeddingsAvailable: boolean;
+    durationMs: number;
+}

package/node_modules/@ktx/context/dist/index-sync/types.js

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

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

@@ -7,6 +7,7 @@ export * from './agent/index.js';
 export * from './core/index.js';
 export * from './daemon/index.js';
 export * from './ingest/index.js';
+export * from './index-sync/index.js';
 export * from './llm/index.js';
 export type { CaptureSession, CaptureSignals, MemoryAgentInput, MemoryAgentResult, MemoryAgentServiceDeps, MemoryAgentSettings, MemoryAgentSourceType, MemoryCommitMessagePort, MemoryConnectionPort, MemoryFileStorePort, MemoryKnowledgeSlRefsPort, MemoryLockPort, MemorySlSourceReconcilerPort, MemoryTelemetryPort, MemoryToolSetLike, MemoryToolsetFactoryPort, } from './memory/index.js';
 export * from './project/index.js';

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

@@ -6,6 +6,7 @@ export * from './agent/index.js';
 export * from './core/index.js';
 export * from './daemon/index.js';
 export * from './ingest/index.js';
+export * from './index-sync/index.js';
 export * from './llm/index.js';
 export * from './project/index.js';
 export * from './prompts/index.js';

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/historic-sql.adapter.d.ts

@@ -1,4 +1,4 @@
-import type { ChunkResult, DiffSet, FetchContext, ScopeDescriptor, SourceAdapter } from '../../types.js';
+import type { ChunkResult, DeterministicFinalizationContext, DiffSet, FetchContext, FinalizationResult, ScopeDescriptor, SourceAdapter } from '../../types.js';
 import { type HistoricSqlSourceAdapterDeps } from './types.js';
 export declare class HistoricSqlSourceAdapter implements SourceAdapter {
     private readonly deps;
@@ -11,4 +11,5 @@ export declare class HistoricSqlSourceAdapter implements SourceAdapter {
     fetch(pullConfig: unknown, stagedDir: string, ctx: FetchContext): Promise<void>;
     chunk(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
     describeScope(stagedDir: string): Promise<ScopeDescriptor>;
+    finalize(ctx: DeterministicFinalizationContext): Promise<FinalizationResult>;
 }

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/historic-sql.adapter.js

@@ -1,5 +1,6 @@
 import { chunkHistoricSqlUnifiedStagedDir, describeHistoricSqlUnifiedScope } from './chunk-unified.js';
 import { detectHistoricSqlStagedDir } from './detect.js';
+import { projectHistoricSqlEvidence } from './projection.js';
 import { stageHistoricSqlAggregatedSnapshot } from './stage-unified.js';
 export class HistoricSqlSourceAdapter {
     deps;
@@ -30,4 +31,21 @@ export class HistoricSqlSourceAdapter {
     describeScope(stagedDir) {
         return describeHistoricSqlUnifiedScope(stagedDir);
     }
+    async finalize(ctx) {
+        const projection = await projectHistoricSqlEvidence({
+            workdir: ctx.workdir,
+            connectionId: ctx.connectionId,
+            syncId: ctx.syncId,
+            runId: ctx.runId,
+            overrideReplay: ctx.overrideReplay,
+        });
+        return {
+            result: projection,
+            warnings: projection.warnings,
+            errors: [],
+            touchedSources: projection.touchedSources,
+            changedWikiPageKeys: projection.changedWikiPageKeys,
+            actions: projection.actions,
+        };
+    }
 }