@kaelio/ktx 0.0.0 → 0.1.0-rc.1

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

@@ -0,0 +1,272 @@
+import { access, mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import YAML from 'yaml';
+import { rawSourcesDirForSync } from '../../raw-sources-paths.js';
+import { mergeUsagePreservingExternal } from '../live-database/manifest.js';
+import { historicSqlEvidenceEnvelopeSchema } from './evidence.js';
+import { stagedManifestSchema } from './types.js';
+function safeKnowledgeSlug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function walkFiles(root) {
+    if (!(await pathExists(root)))
+        return [];
+    const result = [];
+    async function visit(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const absolute = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await visit(absolute);
+            }
+            else if (entry.isFile()) {
+                result.push(relative(root, absolute).replace(/\\/g, '/'));
+            }
+        }
+    }
+    await visit(root);
+    return result.sort();
+}
+async function readJson(path) {
+    return JSON.parse(await readFile(path, 'utf-8'));
+}
+async function writeYamlAtomic(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, YAML.stringify(value, { indent: 2, lineWidth: 0, version: '1.1' }), 'utf-8');
+    await rename(tmp, path);
+}
+function tableSourceName(tableRef) {
+    return tableRef.split('.').filter(Boolean).at(-1) ?? tableRef;
+}
+function staleUsage(fetchedAt) {
+    return {
+        narrative: 'No recent historic SQL usage was observed in the latest snapshot.',
+        frequencyTier: 'unused',
+        commonFilters: [],
+        commonGroupBys: [],
+        commonJoins: [],
+        staleSince: fetchedAt,
+    };
+}
+async function loadEvidence(workdir, runId) {
+    const root = join(workdir, '.ktx/ingest-evidence/historic-sql', runId);
+    const files = await walkFiles(root);
+    const evidence = [];
+    for (const file of files.filter((candidate) => candidate.endsWith('.json'))) {
+        evidence.push(historicSqlEvidenceEnvelopeSchema.parse(await readJson(join(root, file))));
+    }
+    return evidence;
+}
+function renderPatternMarkdown(pattern) {
+    return [
+        `# ${pattern.pattern.title}`,
+        '',
+        pattern.pattern.narrative,
+        '',
+        '## Representative SQL',
+        '',
+        '```sql',
+        pattern.pattern.definitionSql,
+        '```',
+        '',
+        '## Tables',
+        '',
+        ...pattern.pattern.tablesInvolved.map((table) => `- ${table}`),
+        '',
+        '## Constituent Templates',
+        '',
+        ...pattern.pattern.constituentTemplateIds.map((id) => `- ${id}`),
+        '',
+    ].join('\n');
+}
+function overlapRatio(left, right) {
+    const rightSet = new Set(right);
+    const intersection = left.filter((value) => rightSet.has(value)).length;
+    return left.length === 0 ? 0 : intersection / left.length;
+}
+function parseMarkdownPage(key, path, raw) {
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match)
+        return null;
+    return {
+        key,
+        path,
+        frontmatter: (YAML.parse(match[1] ?? '') ?? {}),
+        content: match[2] ?? '',
+    };
+}
+function isHistoricPatternPage(page) {
+    const tags = Array.isArray(page.frontmatter.tags) ? page.frontmatter.tags : [];
+    return (page.frontmatter.source === 'historic-sql' &&
+        tags.includes('historic-sql') &&
+        tags.includes('pattern'));
+}
+function isArchivedPatternPage(page) {
+    const tags = Array.isArray(page.frontmatter.tags) ? page.frontmatter.tags : [];
+    return tags.includes('archived');
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
+}
+function renderMarkdownPage(frontmatter, content) {
+    let yaml = YAML.stringify(frontmatter, { indent: 2, lineWidth: 0 }).trimEnd();
+    const staleSince = frontmatter.stale_since;
+    if (typeof staleSince === 'string') {
+        yaml = yaml.replace(`stale_since: ${staleSince}`, `stale_since: "${staleSince}"`);
+    }
+    return `---\n${yaml}\n---\n\n${content.trim()}\n`;
+}
+function existingPageSignals(page) {
+    return [...stringArray(page.frontmatter.tables), ...stringArray(page.frontmatter.fingerprints)];
+}
+function shouldArchive(staleSince, fetchedAt, days) {
+    if (typeof staleSince !== 'string')
+        return false;
+    const staleTime = Date.parse(staleSince);
+    const fetchedTime = Date.parse(fetchedAt);
+    if (!Number.isFinite(staleTime) || !Number.isFinite(fetchedTime))
+        return false;
+    return fetchedTime - staleTime > days * 24 * 60 * 60 * 1000;
+}
+async function loadPatternPages(root) {
+    const files = await walkFiles(root);
+    const pages = [];
+    for (const file of files.filter((candidate) => candidate.endsWith('.md'))) {
+        if (file.includes('/')) {
+            continue;
+        }
+        const key = file.replace(/\.md$/, '');
+        const path = join(root, file);
+        const page = parseMarkdownPage(key, path, await readFile(path, 'utf-8'));
+        if (page) {
+            pages.push(page);
+        }
+    }
+    return pages;
+}
+function historicSqlFlatKey(slug) {
+    return `historic-sql-${safeKnowledgeSlug(slug)}`;
+}
+async function currentStagedTables(rawDir) {
+    const tablesRoot = join(rawDir, 'tables');
+    const files = await walkFiles(tablesRoot);
+    const tables = new Set();
+    for (const file of files.filter((candidate) => candidate.endsWith('.json'))) {
+        const value = await readJson(join(tablesRoot, file));
+        if (typeof value === 'object' && value !== null && 'table' in value && typeof value.table === 'string') {
+            tables.add(value.table);
+        }
+    }
+    return tables;
+}
+export async function projectHistoricSqlEvidence(input) {
+    const result = {
+        tableUsageMerged: 0,
+        staleTablesMarked: 0,
+        patternPagesWritten: 0,
+        stalePatternPagesMarked: 0,
+        archivedPatternPages: 0,
+        touchedSources: [],
+        warnings: [],
+    };
+    const touchedKeys = new Set();
+    const rawDir = join(input.workdir, rawSourcesDirForSync(input.connectionId, 'historic-sql', input.syncId));
+    const manifest = stagedManifestSchema.parse(await readJson(join(rawDir, 'manifest.json')));
+    const currentTables = await currentStagedTables(rawDir);
+    const evidence = await loadEvidence(input.workdir, input.runId);
+    const tableEvidence = evidence.filter((entry) => entry.kind === 'table_usage');
+    const patternEvidence = evidence.filter((entry) => entry.kind === 'pattern');
+    const schemaRoot = join(input.workdir, 'semantic-layer', input.connectionId, '_schema');
+    for (const file of (await walkFiles(schemaRoot)).filter((candidate) => candidate.endsWith('.yaml') || candidate.endsWith('.yml'))) {
+        const path = join(schemaRoot, file);
+        const before = await readFile(path, 'utf-8');
+        const shard = (YAML.parse(before) ?? {});
+        if (!shard.tables)
+            continue;
+        for (const [tableName, entry] of Object.entries(shard.tables)) {
+            const tableRef = entry.table ?? tableName;
+            const matchingEvidence = tableEvidence.find((candidate) => candidate.table === tableRef || tableSourceName(candidate.table) === tableName);
+            if (matchingEvidence) {
+                const merged = mergeUsagePreservingExternal(entry.usage, matchingEvidence.usage);
+                if (JSON.stringify(entry.usage ?? null) !== JSON.stringify(merged ?? null)) {
+                    entry.usage = merged;
+                    result.tableUsageMerged += 1;
+                    const sourceName = tableSourceName(matchingEvidence.table);
+                    const key = `${input.connectionId}:${sourceName}`;
+                    if (!touchedKeys.has(key)) {
+                        touchedKeys.add(key);
+                        result.touchedSources.push({ connectionId: input.connectionId, sourceName });
+                    }
+                }
+            }
+            else if (entry.usage && !currentTables.has(tableRef)) {
+                const merged = mergeUsagePreservingExternal(entry.usage, staleUsage(manifest.fetchedAt));
+                if (JSON.stringify(entry.usage ?? null) !== JSON.stringify(merged ?? null)) {
+                    entry.usage = merged;
+                    result.staleTablesMarked += 1;
+                    const sourceName = tableSourceName(tableRef);
+                    const key = `${input.connectionId}:${sourceName}`;
+                    if (!touchedKeys.has(key)) {
+                        touchedKeys.add(key);
+                        result.touchedSources.push({ connectionId: input.connectionId, sourceName });
+                    }
+                }
+            }
+        }
+        const after = YAML.stringify(shard, { indent: 2, lineWidth: 0, version: '1.1' });
+        if (after !== before) {
+            await writeYamlAtomic(path, shard);
+        }
+    }
+    const wikiRoot = join(input.workdir, 'wiki/global');
+    await mkdir(wikiRoot, { recursive: true });
+    const allPages = await loadPatternPages(wikiRoot);
+    const activePages = allPages.filter((page) => !isArchivedPatternPage(page));
+    const patternPages = activePages.filter(isHistoricPatternPage);
+    const writtenKeys = new Set();
+    for (const pattern of patternEvidence) {
+        const incomingSignals = [...pattern.pattern.tablesInvolved, ...pattern.pattern.constituentTemplateIds];
+        const reusable = patternPages.find((page) => overlapRatio(incomingSignals, existingPageSignals(page)) >= 0.6);
+        const key = reusable?.key ?? historicSqlFlatKey(pattern.pattern.slug);
+        const pagePath = join(wikiRoot, `${key}.md`);
+        const frontmatter = {
+            summary: pattern.pattern.title,
+            tags: ['historic-sql', 'pattern'],
+            refs: [],
+            sl_refs: pattern.pattern.slRefs,
+            usage_mode: 'auto',
+            source: 'historic-sql',
+            tables: pattern.pattern.tablesInvolved,
+            representative_sql: pattern.pattern.definitionSql,
+            fingerprints: pattern.pattern.constituentTemplateIds,
+        };
+        await mkdir(dirname(pagePath), { recursive: true });
+        await writeFile(pagePath, renderMarkdownPage(frontmatter, renderPatternMarkdown(pattern)), 'utf-8');
+        writtenKeys.add(key);
+        result.patternPagesWritten += 1;
+    }
+    for (const page of patternPages) {
+        if (writtenKeys.has(page.key))
+            continue;
+        if (shouldArchive(page.frontmatter.stale_since, manifest.fetchedAt, manifest.staleArchiveAfterDays)) {
+            const tags = [...new Set([...stringArray(page.frontmatter.tags), 'archived'])];
+            await writeFile(page.path, renderMarkdownPage({ ...page.frontmatter, tags, archived_since: manifest.fetchedAt }, page.content), 'utf-8');
+            result.archivedPatternPages += 1;
+            continue;
+        }
+        const tags = [...new Set([...stringArray(page.frontmatter.tags), 'stale'])];
+        await writeFile(page.path, renderMarkdownPage({ ...page.frontmatter, tags, stale_since: manifest.fetchedAt }, page.content), 'utf-8');
+        result.stalePatternPagesMarked += 1;
+    }
+    return result;
+}

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

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

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

@@ -0,0 +1,309 @@
+import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import YAML from 'yaml';
+import { describe, expect, it } from 'vitest';
+import { projectHistoricSqlEvidence } from './projection.js';
+async function tempWorkdir() {
+    return mkdtemp(join(tmpdir(), 'historic-sql-projection-'));
+}
+async function writeText(root, relPath, content) {
+    const target = join(root, relPath);
+    await mkdir(join(target, '..'), { recursive: true });
+    await writeFile(target, content, 'utf-8');
+}
+async function writeJson(root, relPath, value) {
+    await writeText(root, relPath, `${JSON.stringify(value, null, 2)}\n`);
+}
+describe('projectHistoricSqlEvidence', () => {
+    it('merges table usage into matching _schema shards and preserves external usage keys', async () => {
+        const workdir = await tempWorkdir();
+        await writeText(workdir, 'semantic-layer/warehouse/_schema/public.yaml', YAML.stringify({
+            tables: {
+                orders: {
+                    table: 'public.orders',
+                    usage: {
+                        narrative: 'Old generated usage.',
+                        frequencyTier: 'low',
+                        commonFilters: ['old_status'],
+                        commonJoins: [],
+                        ownerNote: 'keep me',
+                    },
+                    columns: [{ name: 'id', type: 'string' }],
+                },
+            },
+        }));
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/manifest.json', {
+            source: 'historic-sql',
+            connectionId: 'warehouse',
+            dialect: 'postgres',
+            fetchedAt: '2026-05-11T00:00:00.000Z',
+            windowStart: '2026-02-10T00:00:00.000Z',
+            windowEnd: '2026-05-11T00:00:00.000Z',
+            snapshotRowCount: 1,
+            touchedTableCount: 1,
+            parseFailures: 0,
+            warnings: [],
+            probeWarnings: [],
+            staleArchiveAfterDays: 90,
+        });
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/tables/public.orders.json', { table: 'public.orders' });
+        await writeJson(workdir, '.ktx/ingest-evidence/historic-sql/run-1/orders.json', {
+            kind: 'table_usage',
+            connectionId: 'warehouse',
+            table: 'public.orders',
+            rawPath: 'tables/public.orders.json',
+            usage: {
+                narrative: 'Orders are repeatedly queried for lifecycle analysis.',
+                frequencyTier: 'high',
+                commonFilters: ['status', 'created_at'],
+                commonGroupBys: ['status'],
+                commonJoins: [{ table: 'public.customers', on: ['customer_id'] }],
+                staleSince: null,
+            },
+        });
+        const result = await projectHistoricSqlEvidence({ workdir, connectionId: 'warehouse', syncId: 'sync-1', runId: 'run-1' });
+        expect(result.touchedSources).toEqual([{ connectionId: 'warehouse', sourceName: 'orders' }]);
+        const shard = YAML.parse(await readFile(join(workdir, 'semantic-layer/warehouse/_schema/public.yaml'), 'utf-8'));
+        expect(shard.tables.orders.usage).toEqual({
+            ownerNote: 'keep me',
+            narrative: 'Orders are repeatedly queried for lifecycle analysis.',
+            frequencyTier: 'high',
+            commonFilters: ['status', 'created_at'],
+            commonGroupBys: ['status'],
+            commonJoins: [{ table: 'public.customers', on: ['customer_id'] }],
+            staleSince: null,
+        });
+    });
+    it('writes pattern pages, reuses similar slugs, and marks missing old pattern pages stale', async () => {
+        const workdir = await tempWorkdir();
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/manifest.json', {
+            source: 'historic-sql',
+            connectionId: 'warehouse',
+            dialect: 'postgres',
+            fetchedAt: '2026-05-11T00:00:00.000Z',
+            windowStart: '2026-02-10T00:00:00.000Z',
+            windowEnd: '2026-05-11T00:00:00.000Z',
+            snapshotRowCount: 2,
+            touchedTableCount: 2,
+            parseFailures: 0,
+            warnings: [],
+            probeWarnings: [],
+            staleArchiveAfterDays: 90,
+        });
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/tables/public.orders.json', { table: 'public.orders' });
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/tables/public.customers.json', { table: 'public.customers' });
+        await writeText(workdir, 'wiki/global/historic-sql-old-order-lifecycle.md', [
+            '---',
+            YAML.stringify({
+                summary: 'Old order lifecycle page',
+                tags: ['historic-sql', 'pattern'],
+                refs: [],
+                sl_refs: ['orders'],
+                usage_mode: 'auto',
+                source: 'historic-sql',
+                tables: ['public.orders', 'public.customers'],
+                fingerprints: ['pg:1'],
+            }).trimEnd(),
+            '---',
+            '',
+            'Old body',
+            '',
+        ].join('\n'));
+        await writeText(workdir, 'wiki/global/historic-sql-retired-pattern.md', [
+            '---',
+            YAML.stringify({
+                summary: 'Retired pattern',
+                tags: ['historic-sql', 'pattern'],
+                refs: [],
+                sl_refs: [],
+                usage_mode: 'auto',
+                source: 'historic-sql',
+                tables: ['public.tickets'],
+                fingerprints: ['pg:9'],
+            }).trimEnd(),
+            '---',
+            '',
+            'Retired body',
+            '',
+        ].join('\n'));
+        await writeJson(workdir, '.ktx/ingest-evidence/historic-sql/run-1/pattern.json', {
+            kind: 'pattern',
+            connectionId: 'warehouse',
+            rawPath: 'patterns-input.json',
+            pattern: {
+                slug: 'order-lifecycle-analysis',
+                title: 'Order Lifecycle Analysis',
+                narrative: 'Analysts compare order status with customer segment.',
+                definitionSql: 'select * from public.orders join public.customers on customers.id = orders.customer_id',
+                tablesInvolved: ['public.orders', 'public.customers'],
+                slRefs: ['orders', 'customers'],
+                constituentTemplateIds: ['pg:1', 'pg:2'],
+            },
+        });
+        const result = await projectHistoricSqlEvidence({ workdir, connectionId: 'warehouse', syncId: 'sync-1', runId: 'run-1' });
+        expect(result.patternPagesWritten).toBe(1);
+        await expect(readFile(join(workdir, 'wiki/global/historic-sql-old-order-lifecycle.md'), 'utf-8')).resolves.toContain('Order Lifecycle Analysis');
+        await expect(readFile(join(workdir, 'wiki/global/historic-sql-retired-pattern.md'), 'utf-8')).resolves.toContain('stale_since: "2026-05-11T00:00:00.000Z"');
+    });
+    it('rewrites a reappearing archived pattern at the flat slug', async () => {
+        const workdir = await tempWorkdir();
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/manifest.json', {
+            source: 'historic-sql',
+            connectionId: 'warehouse',
+            dialect: 'postgres',
+            fetchedAt: '2026-05-11T00:00:00.000Z',
+            windowStart: '2026-02-10T00:00:00.000Z',
+            windowEnd: '2026-05-11T00:00:00.000Z',
+            snapshotRowCount: 2,
+            touchedTableCount: 2,
+            parseFailures: 0,
+            warnings: [],
+            probeWarnings: [],
+            staleArchiveAfterDays: 30,
+        });
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/tables/public.orders.json', { table: 'public.orders' });
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/tables/public.customers.json', { table: 'public.customers' });
+        await writeText(workdir, 'wiki/global/historic-sql-order-lifecycle-analysis.md', [
+            '---',
+            YAML.stringify({
+                summary: 'Archived order lifecycle page',
+                tags: ['historic-sql', 'pattern', 'archived'],
+                refs: [],
+                sl_refs: ['orders'],
+                usage_mode: 'auto',
+                source: 'historic-sql',
+                tables: ['public.orders', 'public.customers'],
+                fingerprints: ['pg:1'],
+                stale_since: '2026-01-01T00:00:00.000Z',
+            }).trimEnd(),
+            '---',
+            '',
+            'Archived body',
+            '',
+        ].join('\n'));
+        await writeJson(workdir, '.ktx/ingest-evidence/historic-sql/run-1/pattern.json', {
+            kind: 'pattern',
+            connectionId: 'warehouse',
+            rawPath: 'patterns-input.json',
+            pattern: {
+                slug: 'order-lifecycle-analysis',
+                title: 'Order Lifecycle Analysis',
+                narrative: 'Analysts compare order status with customer segment again.',
+                definitionSql: 'select * from public.orders join public.customers on customers.id = orders.customer_id',
+                tablesInvolved: ['public.orders', 'public.customers'],
+                slRefs: ['orders', 'customers'],
+                constituentTemplateIds: ['pg:1', 'pg:2'],
+            },
+        });
+        const result = await projectHistoricSqlEvidence({ workdir, connectionId: 'warehouse', syncId: 'sync-1', runId: 'run-1' });
+        expect(result.patternPagesWritten).toBe(1);
+        const page = await readFile(join(workdir, 'wiki/global/historic-sql-order-lifecycle-analysis.md'), 'utf-8');
+        expect(page).toContain('Analysts compare order status with customer segment again.');
+        expect(page).not.toContain('Archived body');
+        expect(page).not.toContain('archived');
+    });
+    it('leaves already archived pattern pages stable when they are still absent', async () => {
+        const workdir = await tempWorkdir();
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/manifest.json', {
+            source: 'historic-sql',
+            connectionId: 'warehouse',
+            dialect: 'postgres',
+            fetchedAt: '2026-05-11T00:00:00.000Z',
+            windowStart: '2026-02-10T00:00:00.000Z',
+            windowEnd: '2026-05-11T00:00:00.000Z',
+            snapshotRowCount: 0,
+            touchedTableCount: 0,
+            parseFailures: 0,
+            warnings: [],
+            probeWarnings: [],
+            staleArchiveAfterDays: 30,
+        });
+        await writeText(workdir, 'wiki/global/historic-sql-retired-pattern.md', [
+            '---',
+            YAML.stringify({
+                summary: 'Retired pattern',
+                tags: ['historic-sql', 'pattern', 'archived'],
+                refs: [],
+                sl_refs: [],
+                usage_mode: 'auto',
+                source: 'historic-sql',
+                tables: ['public.tickets'],
+                fingerprints: ['pg:9'],
+                stale_since: '2026-01-01T00:00:00.000Z',
+            }).trimEnd(),
+            '---',
+            '',
+            'Archived retired body',
+            '',
+        ].join('\n'));
+        const result = await projectHistoricSqlEvidence({ workdir, connectionId: 'warehouse', syncId: 'sync-1', runId: 'run-1' });
+        expect(result.archivedPatternPages).toBe(0);
+        expect(result.stalePatternPagesMarked).toBe(0);
+        await expect(readFile(join(workdir, 'wiki/global/historic-sql-retired-pattern.md'), 'utf-8')).resolves.toContain('Archived retired body');
+    });
+    it('marks missing table usage stale without deleting old query pages', async () => {
+        const workdir = await tempWorkdir();
+        await writeText(workdir, 'semantic-layer/warehouse/_schema/public.yaml', YAML.stringify({
+            tables: {
+                orders: {
+                    table: 'public.orders',
+                    usage: {
+                        narrative: 'Orders were active before.',
+                        frequencyTier: 'high',
+                        commonFilters: ['status'],
+                        commonGroupBys: ['status'],
+                        commonJoins: [{ table: 'public.customers', on: ['customer_id'] }],
+                        ownerNote: 'keep analyst annotation',
+                    },
+                    columns: [{ name: 'id', type: 'string' }],
+                },
+            },
+        }));
+        await writeJson(workdir, 'raw-sources/warehouse/historic-sql/sync-1/manifest.json', {
+            source: 'historic-sql',
+            connectionId: 'warehouse',
+            dialect: 'postgres',
+            fetchedAt: '2026-05-11T00:00:00.000Z',
+            windowStart: '2026-02-10T00:00:00.000Z',
+            windowEnd: '2026-05-11T00:00:00.000Z',
+            snapshotRowCount: 0,
+            touchedTableCount: 0,
+            parseFailures: 0,
+            warnings: [],
+            probeWarnings: [],
+            staleArchiveAfterDays: 90,
+        });
+        await writeText(workdir, 'wiki/global/historic-sql-old-template.md', [
+            '---',
+            YAML.stringify({
+                summary: 'Old template page',
+                tags: ['historic-sql', 'query-pattern'],
+                refs: [],
+                sl_refs: ['orders'],
+                usage_mode: 'auto',
+                source: 'historic-sql',
+                tables: ['public.orders'],
+                fingerprints: ['old:1'],
+            }).trimEnd(),
+            '---',
+            '',
+            'Old body',
+            '',
+        ].join('\n'));
+        const result = await projectHistoricSqlEvidence({ workdir, connectionId: 'warehouse', syncId: 'sync-1', runId: 'run-1' });
+        expect(result.staleTablesMarked).toBe(1);
+        expect(result.touchedSources).toEqual([{ connectionId: 'warehouse', sourceName: 'orders' }]);
+        const shard = YAML.parse(await readFile(join(workdir, 'semantic-layer/warehouse/_schema/public.yaml'), 'utf-8'));
+        expect(shard.tables.orders.usage).toEqual({
+            ownerNote: 'keep analyst annotation',
+            narrative: 'No recent historic SQL usage was observed in the latest snapshot.',
+            frequencyTier: 'unused',
+            commonFilters: [],
+            commonGroupBys: [],
+            commonJoins: [],
+            staleSince: '2026-05-11T00:00:00.000Z',
+        });
+        await expect(readFile(join(workdir, 'wiki/global/historic-sql-old-template.md'), 'utf-8')).resolves.toContain('Old body');
+    });
+});

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

@@ -0,0 +1,6 @@
+export interface HistoricSqlRedactionPattern {
+    pattern: string;
+    expression: RegExp;
+}
+export declare function compileHistoricSqlRedactionPatterns(patterns: readonly string[]): HistoricSqlRedactionPattern[];
+export declare function redactHistoricSqlText(text: string, redactors: readonly HistoricSqlRedactionPattern[]): string;

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

@@ -0,0 +1,30 @@
+const CASE_INSENSITIVE_PREFIX = '(?i)';
+const REDACTION_TOKEN = '[REDACTED]';
+export function compileHistoricSqlRedactionPatterns(patterns) {
+    return patterns.map((pattern) => {
+        const trimmed = pattern.trim();
+        const caseInsensitive = trimmed.startsWith(CASE_INSENSITIVE_PREFIX);
+        const source = caseInsensitive ? trimmed.slice(CASE_INSENSITIVE_PREFIX.length) : trimmed;
+        if (source.length === 0) {
+            throw new Error(`Invalid historicSql.redactionPatterns entry "${pattern}": pattern must not be empty`);
+        }
+        try {
+            return {
+                pattern,
+                expression: new RegExp(source, caseInsensitive ? 'gi' : 'g'),
+            };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid historicSql.redactionPatterns entry "${pattern}": ${reason}`);
+        }
+    });
+}
+export function redactHistoricSqlText(text, redactors) {
+    let next = text;
+    for (const redactor of redactors) {
+        redactor.expression.lastIndex = 0;
+        next = next.replace(redactor.expression, REDACTION_TOKEN);
+    }
+    return next;
+}

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

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

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

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { compileHistoricSqlRedactionPatterns, redactHistoricSqlText } from './redaction.js';
+describe('historic-SQL redaction', () => {
+    it('redacts regex matches and supports the (?i) case-insensitive prefix', () => {
+        const redactors = compileHistoricSqlRedactionPatterns([
+            'sk_live_[A-Za-z0-9]+',
+            '(?i)secret_token_[a-z0-9]+',
+        ]);
+        const sql = "select * from public.api_events where api_key = 'sk_live_abc123' and note = 'Secret_Token_9f'"; // pragma: allowlist secret
+        expect(redactHistoricSqlText(sql, redactors)).toBe("select * from public.api_events where api_key = '[REDACTED]' and note = '[REDACTED]'");
+    });
+    it('returns the original SQL text when no redaction patterns are configured', () => {
+        const sql = "select * from public.orders where status = 'paid'";
+        expect(redactHistoricSqlText(sql, compileHistoricSqlRedactionPatterns([]))).toBe(sql);
+    });
+    it('throws a config-focused error for invalid redaction regex patterns', () => {
+        expect(() => compileHistoricSqlRedactionPatterns(['[broken'])).toThrow('Invalid historicSql.redactionPatterns entry "[broken"');
+    });
+    it('throws a config-focused error for empty redaction regex patterns', () => {
+        expect(() => compileHistoricSqlRedactionPatterns(['   '])).toThrow('Invalid historicSql.redactionPatterns entry "   "');
+    });
+});