@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/node_modules/@ktx/context/dist/ingest/adapters/metricflow/semantic-models.test.js

@@ -0,0 +1,204 @@
+import { describe, expect, it } from 'vitest';
+import { composeOverlay } from '../../../sl/index.js';
+import { buildMetricflowColumns, buildMetricflowJoinsForModel, buildMetricflowSemanticModelSource, countImportableMetricflowRelationships, findMatchingMetricflowTable, mapCrossModelMetricToSource, mapSemanticModelToSource, resolveMetricflowSemanticModelSourceName, rewriteMetricflowManifestJoins, toKebabCaseMetricflowName, } from './semantic-models.js';
+const ordersModel = {
+    name: 'orders',
+    description: 'Order facts',
+    modelRef: 'fct_orders',
+    dimensions: [
+        { name: 'status', column: 'status', type: 'string', label: 'Status', description: 'Order status' },
+        { name: 'ordered_at', column: 'ordered_at', type: 'time', label: 'Ordered At' },
+    ],
+    measures: [
+        {
+            type: 'simple',
+            name: 'total_revenue',
+            column: 'amount',
+            aggregation: 'sum',
+            label: 'Total Revenue',
+            description: 'Revenue',
+            filter: "status = 'completed'",
+        },
+        {
+            type: 'derived',
+            name: 'average_revenue',
+            expr: 'total_revenue / NULLIF(order_count, 0)',
+            dependsOn: ['total_revenue', 'order_count'],
+        },
+    ],
+    entities: [],
+    defaultTimeDimension: 'ordered_at',
+};
+describe('metricflow semantic model mapping', () => {
+    it('normalizes source names the same way the server importer did', () => {
+        expect(toKebabCaseMetricflowName('Fct Orders!')).toBe('fct-orders');
+    });
+    it('maps a parsed semantic model to a SemanticLayerSource', () => {
+        expect(mapSemanticModelToSource(ordersModel, 'analytics.orders')).toEqual({
+            name: 'fct-orders',
+            table: 'analytics.orders',
+            grain: ['status', 'ordered_at'],
+            columns: [
+                { name: 'status', type: 'string', description: 'Order status' },
+                { name: 'ordered_at', type: 'time' },
+            ],
+            measures: [
+                {
+                    name: 'total_revenue',
+                    expr: 'sum(amount)',
+                    description: 'Revenue',
+                    filter: "status = 'completed'",
+                },
+                {
+                    name: 'average_revenue',
+                    expr: 'total_revenue / NULLIF(order_count, 0)',
+                },
+            ],
+            joins: [],
+            descriptions: { dbt: 'Order facts' },
+        });
+    });
+    it('maps a cross-model metric to a SQL standalone source', () => {
+        const metric = {
+            name: 'roas',
+            label: 'ROAS',
+            description: 'Return on ad spend',
+            type: 'derived',
+            expr: 'revenue / spend',
+            dependsOn: [
+                { metricName: 'orders', alias: 'revenue' },
+                { metricName: 'campaigns', alias: 'spend' },
+            ],
+            filter: "channel = 'paid'",
+        };
+        expect(mapCrossModelMetricToSource(metric)).toEqual({
+            name: 'roas',
+            sql: 'revenue / spend',
+            descriptions: { dbt: 'Return on ad spend' },
+            grain: [],
+            columns: [],
+            measures: [
+                {
+                    name: 'roas',
+                    expr: 'revenue / spend',
+                    description: 'Return on ad spend',
+                    filter: "channel = 'paid'",
+                },
+            ],
+            joins: [],
+        });
+    });
+    it('finds matching tables using target schema, exact name, dotted suffix, and underscore suffix', () => {
+        const tables = [
+            { id: '1', name: 'fct_orders', catalog: null, db: 'analytics', columns: [] },
+            { id: '2', name: 'warehouse.marts.fct_orders', catalog: null, db: 'marts', columns: [] },
+            { id: '3', name: 'warehouse_fct_customers', catalog: null, db: null, columns: [] },
+        ];
+        expect(findMatchingMetricflowTable('fct_orders', tables, 'analytics')?.id).toBe('1');
+        expect(findMatchingMetricflowTable('fct_orders', [tables[1]], null)?.id).toBe('2');
+        expect(findMatchingMetricflowTable('fct_customers', [tables[2]], null)?.id).toBe('3');
+        expect(findMatchingMetricflowTable('missing', tables, null)).toBeUndefined();
+    });
+    it('counts only relationships whose tables and columns exist', () => {
+        const relationships = [
+            { fromTable: 'orders', fromColumn: 'customer_id', toTable: 'customers', toColumn: 'id' },
+            { fromTable: 'orders', fromColumn: 'missing', toTable: 'customers', toColumn: 'id' },
+            { fromTable: 'orders', fromColumn: 'customer_id', toTable: 'missing_table', toColumn: 'id' },
+        ];
+        const tables = [
+            { id: '1', name: 'orders', catalog: null, db: null, columns: [{ id: 'c1', name: 'customer_id' }] },
+            { id: '2', name: 'customers', catalog: null, db: null, columns: [{ id: 'c2', name: 'id' }] },
+        ];
+        expect(countImportableMetricflowRelationships(relationships, tables)).toBe(1);
+    });
+    it('resolves semantic-model source names to lowercase snake_case identifiers', () => {
+        expect(resolveMetricflowSemanticModelSourceName(ordersModel, {
+            id: '1',
+            name: 'ANALYTICS.Fct Orders',
+            catalog: null,
+            db: 'analytics',
+            columns: [],
+        })).toBe('fct_orders');
+        expect(resolveMetricflowSemanticModelSourceName({ ...ordersModel, modelRef: 'fallback_model' }, undefined)).toBe('fallback_model');
+    });
+    it('materializes entity join keys as hidden standalone columns', () => {
+        expect(buildMetricflowColumns({
+            ...ordersModel,
+            entities: [{ name: 'customer', type: 'foreign', expr: 'customer_id', description: 'FK to customers' }],
+        })).toContainEqual({ name: 'customer_id', type: 'string', visibility: 'hidden', description: 'FK to customers' });
+    });
+    it('builds standalone sources with semantic-model joins', () => {
+        const orders = {
+            ...ordersModel,
+            modelRef: 'orders',
+            entities: [{ name: 'customer', type: 'foreign', expr: 'customer_id' }],
+        };
+        const customers = {
+            ...ordersModel,
+            name: 'customers',
+            modelRef: 'customers',
+            dimensions: [{ name: 'id', column: 'id', type: 'string' }],
+            measures: [],
+            entities: [],
+        };
+        const sourceNameByModelRef = new Map([
+            [orders.modelRef, 'orders'],
+            [customers.modelRef, 'customers'],
+        ]);
+        const joins = buildMetricflowJoinsForModel(orders, [{ fromTable: 'orders', fromColumn: 'customer_id', toTable: 'customers', toColumn: 'id' }], sourceNameByModelRef);
+        expect(buildMetricflowSemanticModelSource({
+            model: orders,
+            matchedTable: undefined,
+            sourceName: 'orders',
+            manifestSource: null,
+        }, joins, new Map())).toMatchObject({
+            name: 'orders',
+            table: 'orders',
+            joins: [{ to: 'customers', on: 'orders.customer_id = customers.id', relationship: 'many_to_one' }],
+        });
+    });
+    it('builds overlays for exact manifest matches so scanned columns remain manifest-owned', () => {
+        const manifestSource = {
+            name: 'orders',
+            table: 'analytics.orders',
+            grain: ['id'],
+            columns: [
+                { name: 'id', type: 'string' },
+                { name: 'customer_id', type: 'string' },
+            ],
+            joins: [],
+            measures: [],
+            descriptions: { db: 'Orders table from scan' },
+        };
+        const overlay = buildMetricflowSemanticModelSource({
+            model: { ...ordersModel, modelRef: 'orders', description: 'dbt-described orders' },
+            matchedTable: undefined,
+            sourceName: 'orders',
+            manifestSource,
+        }, [{ to: 'customers', on: 'orders.customer_id = customers.id', relationship: 'many_to_one' }], new Map());
+        expect(overlay).not.toHaveProperty('table');
+        expect(overlay).not.toHaveProperty('grain');
+        expect(overlay).not.toHaveProperty('columns');
+        expect(overlay).toMatchObject({
+            name: 'orders',
+            joins: [{ to: 'customers', on: 'orders.customer_id = customers.id', relationship: 'many_to_one' }],
+            descriptions: { dbt: 'dbt-described orders' },
+        });
+        const composed = composeOverlay(manifestSource, overlay);
+        expect(composed.columns.map((column) => column.name)).toEqual(['id', 'customer_id']);
+        expect(composed.joins).toHaveLength(1);
+        expect(composed.descriptions).toEqual({ db: 'Orders table from scan', dbt: 'dbt-described orders' });
+    });
+    it('rewrites preserved manifest joins to synced bare source names', () => {
+        expect(rewriteMetricflowManifestJoins([
+            {
+                to: 'analytics.customers',
+                on: 'analytics.orders.customer_id = analytics.customers.id',
+                relationship: 'many_to_one',
+            },
+        ], new Map([
+            ['analytics.orders', 'orders'],
+            ['analytics.customers', 'customers'],
+        ]))).toEqual([{ to: 'customers', on: 'orders.customer_id = customers.id', relationship: 'many_to_one' }]);
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/notion/chunk.d.ts

@@ -0,0 +1,4 @@
+import type { ChunkResult, DiffSet, ScopeDescriptor } from '../../types.js';
+export declare const NOTION_ORG_KNOWLEDGE_WARNING = "Anything accessible to this Notion integration can become organization knowledge.";
+export declare function chunkNotionStagedDir(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
+export declare function describeNotionScope(stagedDir: string): Promise<ScopeDescriptor>;

package/node_modules/@ktx/context/dist/ingest/adapters/notion/chunk.js

@@ -0,0 +1,134 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { notionManifestSchema, notionMetadataSchema } from './types.js';
+const MAX_NOTION_WORK_UNIT_CHARS = 40_000;
+export const NOTION_ORG_KNOWLEDGE_WARNING = 'Anything accessible to this Notion integration can become organization knowledge.';
+async function walk(root) {
+    const entries = await readdir(root, { withFileTypes: true, recursive: true });
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(root, join(entry.parentPath, entry.name)).replace(/\\/g, '/'))
+        .sort();
+}
+function safeUnitKey(path) {
+    return `notion-${path
+        .replace(/^pages\//, 'page/')
+        .replace(/\/page\.md$/, '')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')}`;
+}
+function splitLineRanges(content, maxChars) {
+    const rawLines = content.split('\n');
+    const lines = rawLines.length > 0 && rawLines[rawLines.length - 1] === '' ? rawLines.slice(0, -1) : rawLines;
+    const ranges = [];
+    let startLine = 1;
+    let currentChars = 0;
+    for (let index = 0; index < lines.length; index += 1) {
+        const lineChars = lines[index].length + 1;
+        if (currentChars > 0 && currentChars + lineChars > maxChars) {
+            ranges.push({ startLine, endLine: index });
+            startLine = index + 1;
+            currentChars = 0;
+        }
+        currentChars += lineChars;
+    }
+    if (startLine <= lines.length) {
+        ranges.push({ startLine, endLine: lines.length });
+    }
+    return ranges.length > 0 ? ranges : [{ startLine: 1, endLine: 1 }];
+}
+async function readManifest(stagedDir) {
+    try {
+        return notionManifestSchema.parse(JSON.parse(await readFile(join(stagedDir, 'manifest.json'), 'utf-8')));
+    }
+    catch (error) {
+        throw new Error(`Invalid Notion manifest: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function chunkNotionStagedDir(stagedDir, diffSet) {
+    const files = await walk(stagedDir);
+    const manifest = await readManifest(stagedDir);
+    const touched = diffSet ? new Set([...diffSet.added, ...diffSet.modified]) : null;
+    const workUnits = [];
+    const warnings = [];
+    for (const pagePath of files.filter((path) => path.endsWith('/page.md'))) {
+        const metadataPath = pagePath.replace(/\/page\.md$/, '/metadata.json');
+        const blockPath = pagePath.replace(/\/page\.md$/, '/blocks.json');
+        const primary = [metadataPath, pagePath].filter((path) => files.includes(path));
+        if (touched && !primary.some((path) => touched.has(path))) {
+            continue;
+        }
+        const metadata = notionMetadataSchema.parse(JSON.parse(await readFile(join(stagedDir, metadataPath), 'utf-8')));
+        const rawFiles = touched ? primary.filter((path) => touched.has(path)).sort() : primary.sort();
+        const dependencyPaths = ['manifest.json', files.includes(blockPath) ? blockPath : null]
+            .filter((path) => typeof path === 'string' && !rawFiles.includes(path))
+            .sort();
+        const excluded = new Set([...rawFiles, ...dependencyPaths]);
+        const peerFileIndex = files.filter((path) => !excluded.has(path)).sort();
+        const pageContent = await readFile(join(stagedDir, pagePath), 'utf-8');
+        const unitKey = safeUnitKey(pagePath);
+        if (rawFiles.includes(pagePath) && pageContent.length > MAX_NOTION_WORK_UNIT_CHARS) {
+            warnings.push(`Oversized Notion page split into span-scoped work units: ${metadata.path}`);
+            const ranges = splitLineRanges(pageContent, MAX_NOTION_WORK_UNIT_CHARS);
+            for (let index = 0; index < ranges.length; index += 1) {
+                const range = ranges[index];
+                workUnits.push({
+                    unitKey: `${unitKey}-part-${index + 1}`,
+                    displayLabel: `${metadata.path} (part ${index + 1} of ${ranges.length})`,
+                    rawFiles,
+                    dependencyPaths,
+                    peerFileIndex,
+                    notes: `Synthesize durable wiki and SL knowledge from this Notion page span only. Use read_raw_span on ${pagePath} for lines ${range.startLine}-${range.endLine}; do not call read_raw_file for oversized pages. Cite evidence chunk/page IDs.`,
+                });
+            }
+            continue;
+        }
+        workUnits.push({
+            unitKey,
+            displayLabel: metadata.path,
+            rawFiles,
+            dependencyPaths,
+            peerFileIndex,
+            notes: 'Synthesize durable wiki and SL knowledge from this Notion page. Write wiki entries with wiki_write and SL sources with sl_write_source; cite evidence chunk/page IDs.',
+        });
+    }
+    return {
+        workUnits,
+        eviction: diffSet && diffSet.deleted.length > 0 ? { deletedRawPaths: [...diffSet.deleted].sort() } : undefined,
+        reconcileNotes: [
+            `Notion maxKnowledgeCreatesPerRun=${manifest.maxKnowledgeCreatesPerRun}`,
+            `Notion maxKnowledgeUpdatesPerRun=${manifest.maxKnowledgeUpdatesPerRun}`,
+        ],
+        contextReport: {
+            capped: manifest.capped,
+            warnings: [...new Set([NOTION_ORG_KNOWLEDGE_WARNING, ...manifest.warnings, ...warnings])],
+        },
+    };
+}
+export async function describeNotionScope(stagedDir) {
+    const manifest = await readManifest(stagedDir);
+    const files = await walk(stagedDir);
+    const presentPaths = new Set(files);
+    const partialSnapshot = manifest.partialSnapshot || manifest.capped;
+    const scopeKey = JSON.stringify({
+        crawlMode: manifest.crawlMode,
+        rootPageIds: [...manifest.rootPageIds].sort(),
+        rootDatabaseIds: [...manifest.rootDatabaseIds].sort(),
+        rootDataSourceIds: [...manifest.rootDataSourceIds].sort(),
+        partialSnapshot,
+    });
+    const fingerprint = createHash('sha256').update(scopeKey).digest('hex');
+    return {
+        fingerprint,
+        isPathInScope: (rawPath) => {
+            if (partialSnapshot) {
+                return presentPaths.has(rawPath);
+            }
+            return (rawPath === 'manifest.json' ||
+                rawPath.startsWith('pages/') ||
+                rawPath.startsWith('databases/') ||
+                rawPath.startsWith('data-sources/'));
+        },
+    };
+}

package/node_modules/@ktx/context/dist/ingest/adapters/notion/cluster.d.ts

@@ -0,0 +1,10 @@
+import type { KtxEmbeddingPort } from '../../../core/embedding.js';
+import type { WorkUnit } from '../../types.js';
+export declare const MIN_PAGES_TO_CLUSTER = 5;
+interface ClusterNotionWorkUnitsArgs {
+    workUnits: WorkUnit[];
+    stagedDir: string;
+    embedding: KtxEmbeddingPort;
+}
+export declare function clusterNotionWorkUnits(args: ClusterNotionWorkUnitsArgs): Promise<WorkUnit[]>;
+export {};

package/node_modules/@ktx/context/dist/ingest/adapters/notion/cluster.js

@@ -0,0 +1,81 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { kmeans, pickK } from '../../clustering/kmeans.js';
+import { notionMetadataSchema } from './types.js';
+export const MIN_PAGES_TO_CLUSTER = 5;
+const CLUSTER_TEXT_BODY_CHARS = 1024;
+const CLUSTER_SEED = 42;
+async function buildClusterText(wu, stagedDir) {
+    const metadataPath = wu.rawFiles.find((p) => p.endsWith('/metadata.json'));
+    const pagePath = wu.rawFiles.find((p) => p.endsWith('/page.md'));
+    let title = wu.displayLabel ?? wu.unitKey;
+    if (metadataPath) {
+        try {
+            const raw = await readFile(join(stagedDir, metadataPath), 'utf-8');
+            const md = notionMetadataSchema.parse(JSON.parse(raw));
+            title = md.path || md.title || title;
+        }
+        catch {
+            // fall through with displayLabel
+        }
+    }
+    let body = '';
+    if (pagePath) {
+        try {
+            const raw = await readFile(join(stagedDir, pagePath), 'utf-8');
+            body = raw.slice(0, CLUSTER_TEXT_BODY_CHARS);
+        }
+        catch {
+            // empty body OK
+        }
+    }
+    const combined = `${title}\n\n${body}`.trim();
+    return combined.length > 0 ? combined : title;
+}
+function mergeWorkUnits(bucket, clusterIndex) {
+    const rawFiles = Array.from(new Set(bucket.flatMap((w) => w.rawFiles))).sort();
+    const dependencyPaths = Array.from(new Set(bucket.flatMap((w) => w.dependencyPaths))).sort();
+    const allFiles = new Set([...rawFiles, ...dependencyPaths]);
+    const peerFileIndex = Array.from(new Set(bucket.flatMap((w) => w.peerFileIndex).filter((p) => !allFiles.has(p)))).sort();
+    const labels = bucket
+        .map((w) => w.displayLabel ?? w.unitKey)
+        .filter((label, i, arr) => arr.indexOf(label) === i)
+        .slice(0, 5);
+    const labelSummary = labels.join(', ');
+    return {
+        unitKey: `notion-cluster-${clusterIndex + 1}`,
+        displayLabel: `Notion cluster ${clusterIndex + 1} (${bucket.length} pages: ${labelSummary})`,
+        rawFiles,
+        dependencyPaths,
+        peerFileIndex,
+        notes: `Synthesize durable wiki and SL knowledge from these ${bucket.length} related Notion pages. ` +
+            'Read each page with read_raw_file (or read_raw_span for oversized pages). ' +
+            'Search nearby evidence with context_evidence_search/_read/_neighbors when needed. ' +
+            'Write wiki entries directly with wiki_write and SL sources directly with sl_write_source. ' +
+            'Do not call context_candidate_write.',
+    };
+}
+export async function clusterNotionWorkUnits(args) {
+    const { workUnits, stagedDir, embedding } = args;
+    if (workUnits.length < MIN_PAGES_TO_CLUSTER)
+        return workUnits;
+    const k = pickK(workUnits.length);
+    if (k <= 1)
+        return workUnits;
+    const texts = await Promise.all(workUnits.map((wu) => buildClusterText(wu, stagedDir)));
+    let vectors;
+    try {
+        vectors = await embedding.computeEmbeddingsBulk(texts);
+    }
+    catch {
+        return workUnits;
+    }
+    if (vectors.length !== workUnits.length)
+        return workUnits;
+    const { assignments } = kmeans(vectors, k, { seed: CLUSTER_SEED });
+    const buckets = Array.from({ length: k }, () => []);
+    workUnits.forEach((wu, i) => {
+        buckets[assignments[i]].push(wu);
+    });
+    return buckets.filter((b) => b.length > 0).map((b, idx) => mergeWorkUnits(b, idx));
+}

package/node_modules/@ktx/context/dist/ingest/adapters/notion/cluster.test.d.ts

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

package/node_modules/@ktx/context/dist/ingest/adapters/notion/cluster.test.js

@@ -0,0 +1,106 @@
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, test } from 'vitest';
+import { clusterNotionWorkUnits, MIN_PAGES_TO_CLUSTER } from './cluster.js';
+function fakeEmbedding(text) {
+    const v = [0, 0, 0, 0];
+    for (const ch of text) {
+        v[ch.charCodeAt(0) % 4] += 1;
+    }
+    return v;
+}
+const mockEmbed = {
+    maxBatchSize: 100,
+    computeEmbedding: async (t) => fakeEmbedding(t),
+    computeEmbeddingsBulk: async (texts) => texts.map(fakeEmbedding),
+};
+async function makeStaged(pages) {
+    const dir = await mkdtemp(join(tmpdir(), 'notion-cluster-'));
+    for (const p of pages) {
+        const pageDir = join(dir, 'pages', p.id);
+        await mkdir(pageDir, { recursive: true });
+        await writeFile(join(pageDir, 'page.md'), p.body);
+        await writeFile(join(pageDir, 'metadata.json'), JSON.stringify({
+            id: p.id,
+            title: p.title,
+            path: p.title,
+            objectType: 'page',
+            properties: {},
+        }));
+    }
+    return dir;
+}
+function makeWorkUnits(pages) {
+    return pages.map((p) => ({
+        unitKey: `notion-${p.id}`,
+        rawFiles: [`pages/${p.id}/page.md`, `pages/${p.id}/metadata.json`],
+        peerFileIndex: [],
+        dependencyPaths: ['manifest.json'],
+    }));
+}
+describe('clusterNotionWorkUnits', () => {
+    test('returns input unchanged when below threshold', async () => {
+        const pages = Array.from({ length: 3 }, (_, i) => ({
+            id: `p${i}`,
+            title: `Page ${i}`,
+            body: 'short body',
+        }));
+        const stagedDir = await makeStaged(pages);
+        const wus = makeWorkUnits(pages);
+        const out = await clusterNotionWorkUnits({ workUnits: wus, stagedDir, embedding: mockEmbed });
+        expect(out).toHaveLength(3);
+        expect(out[0].unitKey).toBe('notion-p0');
+    });
+    test('groups pages into k=ceil(N/8) clusters when above threshold', async () => {
+        const n = MIN_PAGES_TO_CLUSTER + 4;
+        const pages = Array.from({ length: n }, (_, i) => ({
+            id: `p${i}`,
+            title: `Topic ${i % 2 === 0 ? 'alpha' : 'beta'} ${i}`,
+            body: `Body for page ${i}`.repeat(20),
+        }));
+        const stagedDir = await makeStaged(pages);
+        const wus = makeWorkUnits(pages);
+        const out = await clusterNotionWorkUnits({ workUnits: wus, stagedDir, embedding: mockEmbed });
+        expect(out.length).toBeLessThanOrEqual(wus.length);
+        expect(out.length).toBe(Math.ceil(wus.length / 8));
+        for (const wu of out) {
+            expect(wu.unitKey).toMatch(/^notion-cluster-\d+$/);
+            expect(wu.rawFiles.length).toBeGreaterThan(0);
+            expect(wu.notes).toMatch(/Synthesize/);
+        }
+    });
+    test('preserves coverage: every input rawFile appears in some cluster', async () => {
+        const pages = Array.from({ length: 12 }, (_, i) => ({
+            id: `p${i}`,
+            title: `Page ${i}`,
+            body: 'body content',
+        }));
+        const stagedDir = await makeStaged(pages);
+        const wus = makeWorkUnits(pages);
+        const inputFiles = new Set(wus.flatMap((wu) => wu.rawFiles));
+        const out = await clusterNotionWorkUnits({ workUnits: wus, stagedDir, embedding: mockEmbed });
+        const outFiles = new Set(out.flatMap((wu) => wu.rawFiles));
+        expect(outFiles).toEqual(inputFiles);
+    });
+    test('falls back to input when embedding fails', async () => {
+        const pages = Array.from({ length: 10 }, (_, i) => ({
+            id: `p${i}`,
+            title: `Page ${i}`,
+            body: 'b',
+        }));
+        const stagedDir = await makeStaged(pages);
+        const wus = makeWorkUnits(pages);
+        const failingEmbed = {
+            maxBatchSize: 100,
+            computeEmbedding: async () => {
+                throw new Error('embedding down');
+            },
+            computeEmbeddingsBulk: async () => {
+                throw new Error('embedding down');
+            },
+        };
+        const out = await clusterNotionWorkUnits({ workUnits: wus, stagedDir, embedding: failingEmbed });
+        expect(out).toEqual(wus);
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/notion/detect.d.ts

@@ -0,0 +1 @@
+export declare function detectNotionStagedDir(stagedDir: string): Promise<boolean>;

package/node_modules/@ktx/context/dist/ingest/adapters/notion/detect.js

@@ -0,0 +1,20 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function detectNotionStagedDir(stagedDir) {
+    try {
+        const manifest = JSON.parse(await readFile(join(stagedDir, 'manifest.json'), 'utf-8'));
+        if (manifest.source === 'notion') {
+            return true;
+        }
+    }
+    catch {
+        // Fall through to structural detection for staged dirs without a manifest.
+    }
+    try {
+        const entries = await readdir(stagedDir, { withFileTypes: true, recursive: true });
+        return entries.some((entry) => entry.isFile() && entry.name === 'page.md');
+    }
+    catch {
+        return false;
+    }
+}

package/node_modules/@ktx/context/dist/ingest/adapters/notion/fetch.d.ts

@@ -0,0 +1,9 @@
+import type { NotionApi } from './notion-client.js';
+import { type NotionManifest, type NotionPullConfig } from './types.js';
+interface FetchNotionSnapshotParams {
+    client: NotionApi;
+    config: NotionPullConfig;
+    stagedDir: string;
+}
+export declare function fetchNotionSnapshot(params: FetchNotionSnapshotParams): Promise<NotionManifest>;
+export {};