@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/node_modules/@ktx/context/dist/tools/sql-edit-replacer.js

@@ -0,0 +1,173 @@
+function exactReplacer(sql, oldText, newText) {
+    if (oldText.length === 0) {
+        return null;
+    }
+    let count = 0;
+    let idx = -1;
+    let searchFrom = 0;
+    while (true) {
+        const found = sql.indexOf(oldText, searchFrom);
+        if (found === -1) {
+            break;
+        }
+        count++;
+        idx = found;
+        searchFrom = found + 1;
+    }
+    if (count === 0) {
+        return null;
+    }
+    if (count > 1) {
+        return { error: `Found ${count} matches for text, expected 1. Add more surrounding context.` };
+    }
+    return { sql: sql.slice(0, idx) + newText + sql.slice(idx + oldText.length) };
+}
+function buildCharacterMap(original) {
+    const map = [];
+    for (let i = 0; i < original.length; i++) {
+        if (/\s/.test(original[i])) {
+            if (map.length === 0 || !/\s/.test(original[i - 1])) {
+                map.push(i);
+            }
+        }
+        else {
+            map.push(i);
+        }
+    }
+    return map;
+}
+function whitespaceNormalizedReplacer(sql, oldText, newText) {
+    const normalizedSql = sql.replace(/\s+/g, ' ');
+    const normalizedOldText = oldText.replace(/\s+/g, ' ');
+    if (normalizedOldText.length === 0) {
+        return null;
+    }
+    let count = 0;
+    let matchIdx = -1;
+    let searchFrom = 0;
+    while (true) {
+        const found = normalizedSql.indexOf(normalizedOldText, searchFrom);
+        if (found === -1) {
+            break;
+        }
+        count++;
+        matchIdx = found;
+        searchFrom = found + 1;
+    }
+    if (count === 0) {
+        return null;
+    }
+    if (count > 1) {
+        return null;
+    }
+    const charMap = buildCharacterMap(sql);
+    const originalStart = charMap[matchIdx];
+    const normalizedEnd = matchIdx + normalizedOldText.length;
+    let originalEnd;
+    if (normalizedEnd >= charMap.length) {
+        originalEnd = sql.length;
+    }
+    else {
+        originalEnd = charMap[normalizedEnd];
+    }
+    return { sql: sql.slice(0, originalStart) + newText + sql.slice(originalEnd) };
+}
+function levenshteinDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0) {
+        return n;
+    }
+    if (n === 0) {
+        return m;
+    }
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++) {
+        dp[i][0] = i;
+    }
+    for (let j = 0; j <= n; j++) {
+        dp[0][j] = j;
+    }
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[m][n];
+}
+function fuzzyReplacer(sql, oldText, newText) {
+    if (oldText.length === 0) {
+        return null;
+    }
+    const targetLen = oldText.length;
+    const minWindow = Math.max(1, Math.floor(targetLen * 0.85));
+    const maxWindow = Math.ceil(targetLen * 1.15);
+    let bestDistance = Infinity;
+    let bestStart = -1;
+    let bestEnd = -1;
+    for (let windowLen = minWindow; windowLen <= maxWindow; windowLen++) {
+        if (windowLen > sql.length) {
+            break;
+        }
+        for (let start = 0; start <= sql.length - windowLen; start++) {
+            const candidate = sql.slice(start, start + windowLen);
+            const distance = levenshteinDistance(candidate, oldText);
+            if (distance < bestDistance) {
+                bestDistance = distance;
+                bestStart = start;
+                bestEnd = start + windowLen;
+            }
+        }
+    }
+    if (bestStart === -1) {
+        return null;
+    }
+    const maxLen = Math.max(oldText.length, bestEnd - bestStart);
+    const similarity = 1 - bestDistance / maxLen;
+    if (similarity < 0.85) {
+        return null;
+    }
+    const matchedText = sql.slice(bestStart, bestEnd);
+    return {
+        sql: sql.slice(0, bestStart) + newText + sql.slice(bestEnd),
+        note: `Fuzzy match used (similarity: ${(similarity * 100).toFixed(1)}%, matched: "${matchedText}")`,
+    };
+}
+export function applySqlEdits(sql, edits, options) {
+    let currentSql = sql;
+    let appliedEdits = 0;
+    const errors = [];
+    for (const edit of edits) {
+        const replacers = options?.exactOnly
+            ? [exactReplacer]
+            : [exactReplacer, whitespaceNormalizedReplacer, fuzzyReplacer];
+        let applied = false;
+        for (const replacer of replacers) {
+            const result = replacer(currentSql, edit.oldText, edit.newText);
+            if (result === null) {
+                continue;
+            }
+            if ('error' in result) {
+                const context = edit.reason ? ` (reason: ${edit.reason})` : '';
+                errors.push(`${result.error}${context}`);
+                applied = true;
+                break;
+            }
+            currentSql = result.sql;
+            appliedEdits++;
+            applied = true;
+            break;
+        }
+        if (!applied) {
+            const context = edit.reason ? ` (reason: ${edit.reason})` : '';
+            errors.push(`No match found for edit${context}: "${edit.oldText.slice(0, 80)}${edit.oldText.length > 80 ? '...' : ''}"`);
+        }
+    }
+    return {
+        success: errors.length === 0,
+        sql: currentSql,
+        appliedEdits,
+        errors,
+    };
+}

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

@@ -0,0 +1,54 @@
+import type { GitService, KtxFileStorePort } from '../core/index.js';
+import type { SemanticLayerService } from '../sl/index.js';
+import type { KnowledgeWikiService } from '../wiki/index.js';
+import type { TouchedSlSourceSet } from './touched-sl-sources.js';
+export interface IngestToolMetadata {
+    runId: string;
+    jobId: string;
+    syncId: string;
+    sourceKey: string;
+}
+export interface MemoryAction {
+    target: 'wiki' | 'sl';
+    type: 'created' | 'updated' | 'removed';
+    key: string;
+    detail: string;
+    targetConnectionId?: string | null;
+    rawPaths?: string[];
+}
+interface EvictionDecisionRecord {
+    rawPath: string;
+    artifactKind: 'wiki' | 'sl';
+    artifactKey: string;
+    action: 'removed';
+    reason: string;
+}
+/**
+ * Per-WU (or per-memory-agent) state threaded through ToolContext. When present,
+ * SL/wiki tools read session-scoped services and emit touched-set entries / actions
+ * instead of hitting shared services. When absent, tools behave as they do for
+ * interactive research/workshop callers.
+ */
+export interface ToolSession {
+    /**
+     * Warehouse connection targeted by SL tools. `null` when the session has no
+     * warehouse connection (wiki-only memory-agent turns) — SL tools must guard
+     * for this and return a structured error rather than execute against a
+     * blank connection.
+     */
+    connectionId: string | null;
+    /** When true, worktree-scoped service writes bypass DB index updates. */
+    isWorktreeScoped: boolean;
+    preHead: string | null;
+    touchedSlSources: TouchedSlSourceSet;
+    actions: MemoryAction[];
+    allowedRawPaths?: ReadonlySet<string>;
+    allowedConnectionNames?: ReadonlySet<string>;
+    semanticLayerService: SemanticLayerService;
+    wikiService: KnowledgeWikiService;
+    configService: KtxFileStorePort;
+    gitService: GitService;
+    ingest?: IngestToolMetadata;
+    evictionDecisions?: EvictionDecisionRecord[];
+}
+export {};

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

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

package/node_modules/@ktx/context/dist/tools/touched-sl-sources.d.ts

@@ -0,0 +1,12 @@
+export interface TouchedSlSource {
+    connectionId: string;
+    sourceName: string;
+}
+export type TouchedSlSourceSet = Map<string, Set<string>>;
+export declare function createTouchedSlSources(entries?: TouchedSlSource[]): TouchedSlSourceSet;
+export declare function addTouchedSlSource(touched: TouchedSlSourceSet, connectionId: string, sourceName: string): void;
+export declare function deleteTouchedSlSource(touched: TouchedSlSourceSet, connectionId: string, sourceName: string): void;
+export declare function hasTouchedSlSource(touched: TouchedSlSourceSet, connectionId: string, sourceName: string): boolean;
+export declare function listTouchedSlSources(touched: TouchedSlSourceSet): TouchedSlSource[];
+export declare function touchedSlSourceCount(touched: TouchedSlSourceSet): number;
+export declare function touchedSlSourceNamesForConnection(touched: TouchedSlSourceSet, connectionId: string): string[];

package/node_modules/@ktx/context/dist/tools/touched-sl-sources.js

@@ -0,0 +1,47 @@
+export function createTouchedSlSources(entries = []) {
+    const touched = new Map();
+    for (const entry of entries) {
+        addTouchedSlSource(touched, entry.connectionId, entry.sourceName);
+    }
+    return touched;
+}
+export function addTouchedSlSource(touched, connectionId, sourceName) {
+    const bucket = touched.get(connectionId) ?? new Set();
+    bucket.add(sourceName);
+    touched.set(connectionId, bucket);
+}
+export function deleteTouchedSlSource(touched, connectionId, sourceName) {
+    const bucket = touched.get(connectionId);
+    if (!bucket) {
+        return;
+    }
+    bucket.delete(sourceName);
+    if (bucket.size === 0) {
+        touched.delete(connectionId);
+    }
+}
+export function hasTouchedSlSource(touched, connectionId, sourceName) {
+    return touched.get(connectionId)?.has(sourceName) ?? false;
+}
+export function listTouchedSlSources(touched) {
+    const out = [];
+    for (const [connectionId, sources] of touched) {
+        for (const sourceName of sources) {
+            out.push({ connectionId, sourceName });
+        }
+    }
+    return out.sort((left, right) => {
+        const byConnection = left.connectionId.localeCompare(right.connectionId);
+        return byConnection === 0 ? left.sourceName.localeCompare(right.sourceName) : byConnection;
+    });
+}
+export function touchedSlSourceCount(touched) {
+    let total = 0;
+    for (const sources of touched.values()) {
+        total += sources.size;
+    }
+    return total;
+}
+export function touchedSlSourceNamesForConnection(touched, connectionId) {
+    return [...(touched.get(connectionId) ?? [])].sort();
+}

package/node_modules/@ktx/context/dist/tools/touched-sl-sources.test.d.ts

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

package/node_modules/@ktx/context/dist/tools/touched-sl-sources.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { addTouchedSlSource, createTouchedSlSources, deleteTouchedSlSource, hasTouchedSlSource, listTouchedSlSources, touchedSlSourceCount, touchedSlSourceNamesForConnection, } from './touched-sl-sources.js';
+describe('target-aware touched SL source helpers', () => {
+    it('deduplicates by connectionId and sourceName while preserving target identity', () => {
+        const touched = createTouchedSlSources();
+        addTouchedSlSource(touched, 'warehouse-a', 'orders');
+        addTouchedSlSource(touched, 'warehouse-a', 'orders');
+        addTouchedSlSource(touched, 'warehouse-b', 'orders');
+        expect(listTouchedSlSources(touched)).toEqual([
+            { connectionId: 'warehouse-a', sourceName: 'orders' },
+            { connectionId: 'warehouse-b', sourceName: 'orders' },
+        ]);
+        expect(touchedSlSourceCount(touched)).toBe(2);
+        expect(hasTouchedSlSource(touched, 'warehouse-a', 'orders')).toBe(true);
+        expect(hasTouchedSlSource(touched, 'warehouse-b', 'orders')).toBe(true);
+    });
+    it('lists touched names for one connection and deletes only that connection/source pair', () => {
+        const touched = createTouchedSlSources([
+            { connectionId: 'warehouse-a', sourceName: 'orders' },
+            { connectionId: 'warehouse-a', sourceName: 'customers' },
+            { connectionId: 'warehouse-b', sourceName: 'orders' },
+        ]);
+        deleteTouchedSlSource(touched, 'warehouse-a', 'orders');
+        expect(touchedSlSourceNamesForConnection(touched, 'warehouse-a')).toEqual(['customers']);
+        expect(touchedSlSourceNamesForConnection(touched, 'warehouse-b')).toEqual(['orders']);
+        expect(listTouchedSlSources(touched)).toEqual([
+            { connectionId: 'warehouse-a', sourceName: 'customers' },
+            { connectionId: 'warehouse-b', sourceName: 'orders' },
+        ]);
+    });
+});

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

@@ -0,0 +1,9 @@
+export { buildKnowledgeSearchText } from './knowledge-search-text.js';
+export { assertFlatWikiKey, invalidFlatWikiKeyMessage, isFlatWikiKey, suggestFlatWikiKey, validateFlatWikiKey, } from './keys.js';
+export { KnowledgeWikiService } from './knowledge-wiki.service.js';
+export * from './local-knowledge.js';
+export type { KnowledgeEventPort, KnowledgeGitDiffPort, KnowledgeIndexPort, KnowledgeIndexPageListing, UpsertPageParams, WikiFileStorePort, } from './ports.js';
+export type { ExistingKnowledgeIndexPage, SqliteKnowledgeIndexOptions, SqliteKnowledgeIndexPage, SqliteKnowledgeIndexSearchResult, WikiSqliteLaneCandidate, } from './sqlite-knowledge-index.js';
+export { SqliteKnowledgeIndex } from './sqlite-knowledge-index.js';
+export * from './tools/index.js';
+export type { HistoricSqlWikiUsageFrontmatter, WikiFrontmatter, WikiPage, WikiPageWithScope, WikiScope, WikiSearchLaneSummary, WikiSearchMatchReason, WikiSearchMetadata, } from './types.js';

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

@@ -0,0 +1,6 @@
+export { buildKnowledgeSearchText } from './knowledge-search-text.js';
+export { assertFlatWikiKey, invalidFlatWikiKeyMessage, isFlatWikiKey, suggestFlatWikiKey, validateFlatWikiKey, } from './keys.js';
+export { KnowledgeWikiService } from './knowledge-wiki.service.js';
+export * from './local-knowledge.js';
+export { SqliteKnowledgeIndex } from './sqlite-knowledge-index.js';
+export * from './tools/index.js';

package/node_modules/@ktx/context/dist/wiki/keys.d.ts

@@ -0,0 +1,11 @@
+export declare function suggestFlatWikiKey(key: string): string;
+export declare function invalidFlatWikiKeyMessage(key: string): string;
+export declare function isFlatWikiKey(key: string): boolean;
+export declare function validateFlatWikiKey(key: string): {
+    ok: true;
+    key: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function assertFlatWikiKey(key: string): string;

package/node_modules/@ktx/context/dist/wiki/keys.js

@@ -0,0 +1,26 @@
+const FLAT_WIKI_KEY_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+export function suggestFlatWikiKey(key) {
+    const suggested = key
+        .trim()
+        .replace(/[\\/]+/g, '-')
+        .replace(/[^a-zA-Z0-9_-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^[-_]+|[-_]+$/g, '');
+    return suggested.length > 0 ? suggested : 'page-key';
+}
+export function invalidFlatWikiKeyMessage(key) {
+    return `Invalid wiki key "${key}". Wiki keys must be flat; use "${suggestFlatWikiKey(key)}".`;
+}
+export function isFlatWikiKey(key) {
+    return FLAT_WIKI_KEY_PATTERN.test(key);
+}
+export function validateFlatWikiKey(key) {
+    return isFlatWikiKey(key) ? { ok: true, key } : { ok: false, error: invalidFlatWikiKeyMessage(key) };
+}
+export function assertFlatWikiKey(key) {
+    const result = validateFlatWikiKey(key);
+    if (!result.ok) {
+        throw new Error(result.error);
+    }
+    return result.key;
+}

package/node_modules/@ktx/context/dist/wiki/knowledge-search-text.d.ts

@@ -0,0 +1 @@
+export declare function buildKnowledgeSearchText(blockKey: string, summary: string, content: string, tags?: string[]): string;

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

@@ -0,0 +1,7 @@
+export function buildKnowledgeSearchText(blockKey, summary, content, tags) {
+    const parts = [blockKey, summary, content];
+    if (tags && tags.length > 0) {
+        parts.push(tags.join(' '));
+    }
+    return parts.join('\n');
+}

package/node_modules/@ktx/context/dist/wiki/knowledge-wiki.service.d.ts

@@ -0,0 +1,76 @@
+import type { KtxEmbeddingPort, KtxFileStorePort, KtxLogger } from '../core/index.js';
+import type { KnowledgeGitDiffPort, KnowledgeIndexPort } from './ports.js';
+import type { WikiFrontmatter, WikiPage, WikiPageWithScope } from './types.js';
+export type { WikiFrontmatter };
+export declare class KnowledgeWikiService {
+    private readonly configService;
+    private readonly embeddingService;
+    private readonly pagesRepository;
+    private readonly gitService;
+    private readonly logger;
+    private isWorktreeScoped;
+    constructor(configService: KtxFileStorePort, embeddingService: KtxEmbeddingPort, pagesRepository: KnowledgeIndexPort, gitService: KnowledgeGitDiffPort, logger?: KtxLogger);
+    /**
+     * Return a clone of this service whose disk writes go through a worktree-scoped
+     * ConfigService AND whose DB-index writes are no-ops. Used by memory-agent
+     * session worktrees so wiki tool calls during the LLM loop land on the session
+     * branch. The shared `knowledge` table is only touched once per run, atomically,
+     * via `syncFromCommit` after Stage 6 squashes the branch into main.
+     */
+    forWorktree(workdir: string): KnowledgeWikiService;
+    private markWorktreeScoped;
+    private scopeDir;
+    pagePath(scope: string, scopeId: string | null | undefined, pageKey: string): string;
+    parsePage(raw: string): {
+        frontmatter: WikiFrontmatter;
+        content: string;
+    };
+    serializePage(frontmatter: WikiFrontmatter, content: string): string;
+    writePage(scope: string, scopeId: string | null | undefined, pageKey: string, frontmatter: WikiFrontmatter, content: string, author: string, authorEmail: string, commitMessage?: string, options?: {
+        skipLock?: boolean;
+    }): Promise<import("../core/file-store.js").KtxFileWriteResult>;
+    readPage(scope: string, scopeId: string | null | undefined, pageKey: string): Promise<WikiPage | null>;
+    deletePage(scope: string, scopeId: string | null | undefined, pageKey: string, author: string, authorEmail: string): Promise<import("../core/file-store.js").KtxFileWriteResult | null>;
+    listPageKeys(scope: string, scopeId?: string | null): Promise<string[]>;
+    getPageHistory(scope: string, scopeId: string | null | undefined, pageKey: string): Promise<unknown>;
+    readPageForUser(userId: string, pageKey: string): Promise<WikiPageWithScope | null>;
+    /**
+     * Write a page verbatim from raw .md text (front-matter + body) after parse-validation.
+     * Preserves the user's exact formatting (raw mode source-of-truth).
+     */
+    writeRawPageAndSync(scope: string, scopeId: string | null | undefined, pageKey: string, rawContent: string, author: string, authorEmail: string, commitMessage?: string): Promise<{
+        frontmatter: WikiFrontmatter;
+        content: string;
+    }>;
+    /**
+     * Write a wiki page and then sync it to the DB search index.
+     * Chains the two operations so the index is only updated after the file write succeeds.
+     */
+    writePageAndSync(scope: string, scopeId: string | null | undefined, pageKey: string, frontmatter: WikiFrontmatter, content: string, author: string, authorEmail: string, commitMessage?: string): Promise<void>;
+    /**
+     * Sync a single page to the DB search index after a write.
+     * Computes search_text and embedding, then upserts to knowledge index.
+     */
+    syncSinglePage(scope: string, scopeId: string | null | undefined, pageKey: string, frontmatter: WikiFrontmatter, content: string, contentHash?: string | null): Promise<void>;
+    /**
+     * Full sync: load all pages from disk for a scope, reindex changed pages, clean stale entries.
+     * Mirrors SlSearchService.indexSources() pattern.
+     */
+    syncIndex(scope: string, scopeId?: string | null): Promise<void>;
+    /**
+     * Delete a page from the DB index (after file deletion).
+     */
+    deleteFromIndex(scope: string, scopeId: string | null | undefined, pageKey: string): Promise<void>;
+    /**
+     * Apply the diff between two commits on the config repo to the shared
+     * wiki index in a single transaction. Called by the ingest runner
+     * after Stage 6 squashes the session branch into main: the pre-squash main
+     * SHA and the post-squash SHA bracket exactly the set of wiki-file
+     * changes this run produced.
+     *
+     * Any added/modified file becomes an upsert (tagged with `source_run_id`),
+     * any deleted file becomes a delete. Parsing errors fail the whole
+     * transaction so the shared table stays consistent.
+     */
+    syncFromCommit(fromSha: string, toSha: string, runId: string): Promise<void>;
+}