@kaelio/ktx 0.0.0 → 0.1.0-rc.0

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

@@ -0,0 +1,167 @@
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { detectHistoricSqlStagedDir } from './detect.js';
+import { HISTORIC_SQL_SOURCE_KEY, historicSqlManifestSchema, historicSqlMetadataSchema, historicSqlPullConfigSchema, historicSqlUsageSchema, } from './types.js';
+async function tempDir() {
+    return mkdtemp(join(tmpdir(), 'historic-sql-detect-'));
+}
+async function writeJson(root, relPath, value) {
+    const target = join(root, relPath);
+    await mkdir(join(target, '..'), { recursive: true });
+    await writeFile(target, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+describe('historic-sql staged dir detection', () => {
+    it('detects manifest source', async () => {
+        const stagedDir = await tempDir();
+        await writeJson(stagedDir, 'manifest.json', {
+            source: HISTORIC_SQL_SOURCE_KEY,
+            connectionId: 'conn_1',
+            dialect: 'snowflake',
+            fetchedAt: '2026-05-04T12:00:00.000Z',
+            windowStart: '2026-02-03T12:00:00.000Z',
+            windowEnd: '2026-05-04T12:00:00.000Z',
+            nextSuccessfulCursor: '2026-05-04T11:55:00.000Z',
+            templateCount: 0,
+            capped: false,
+            warnings: [],
+            templates: [],
+        });
+        await expect(detectHistoricSqlStagedDir(stagedDir)).resolves.toBe(true);
+    });
+    it('detects document-shaped template structure without manifest', async () => {
+        const stagedDir = await tempDir();
+        await writeFile(join(stagedDir, 'not-a-match.txt'), 'x', 'utf-8');
+        await mkdir(join(stagedDir, 'templates', 'fp_1'), { recursive: true });
+        await writeFile(join(stagedDir, 'templates', 'fp_1', 'metadata.json'), '{}', 'utf-8');
+        await writeFile(join(stagedDir, 'templates', 'fp_1', 'page.md'), '# fp_1\n', 'utf-8');
+        await expect(detectHistoricSqlStagedDir(stagedDir)).resolves.toBe(true);
+    });
+    it('does not detect unrelated directories', async () => {
+        const stagedDir = await tempDir();
+        await writeJson(stagedDir, 'manifest.json', { source: 'notion' });
+        await expect(detectHistoricSqlStagedDir(stagedDir)).resolves.toBe(false);
+    });
+});
+describe('historic-sql schemas', () => {
+    it('defaults disabled optional pull-config fields through the parser', () => {
+        expect(historicSqlPullConfigSchema.parse({
+            dialect: 'bigquery',
+        })).toEqual({
+            dialect: 'bigquery',
+            windowDays: 90,
+            lastSuccessfulCursor: null,
+            serviceAccountUserPatterns: [],
+            redactionPatterns: [],
+            maxTemplatesPerRun: 5000,
+            minCalls: 5,
+        });
+    });
+    it('accepts postgres pull config with a minCalls floor', () => {
+        expect(historicSqlPullConfigSchema.parse({
+            dialect: 'postgres',
+            minCalls: 12,
+        })).toEqual({
+            dialect: 'postgres',
+            windowDays: 90,
+            lastSuccessfulCursor: null,
+            serviceAccountUserPatterns: [],
+            redactionPatterns: [],
+            maxTemplatesPerRun: 5000,
+            minCalls: 12,
+        });
+    });
+    it('accepts postgres manifest fields with defaults for older dialects', () => {
+        expect(historicSqlManifestSchema.parse({
+            source: HISTORIC_SQL_SOURCE_KEY,
+            connectionId: 'conn_pg',
+            dialect: 'postgres',
+            fetchedAt: '2026-05-08T12:00:00.000Z',
+            windowStart: '2026-05-08T11:00:00.000Z',
+            windowEnd: '2026-05-08T12:00:00.000Z',
+            nextSuccessfulCursor: '2026-05-08T12:00:00.000Z',
+            templateCount: 0,
+            capped: false,
+            warnings: [],
+            templates: [],
+            degraded: true,
+            statsResetAt: '2026-05-01T00:00:00.000Z',
+            baselineFirstRun: true,
+            pgServerVersion: 'PostgreSQL 16.4',
+            deallocCount: 3,
+        })).toMatchObject({
+            dialect: 'postgres',
+            degraded: true,
+            statsResetAt: '2026-05-01T00:00:00.000Z',
+            baselineFirstRun: true,
+            pgServerVersion: 'PostgreSQL 16.4',
+            deallocCount: 3,
+        });
+        expect(historicSqlManifestSchema.parse({
+            source: HISTORIC_SQL_SOURCE_KEY,
+            connectionId: 'conn_sf',
+            dialect: 'snowflake',
+            fetchedAt: '2026-05-08T12:00:00.000Z',
+            windowStart: '2026-05-01T12:00:00.000Z',
+            windowEnd: '2026-05-08T12:00:00.000Z',
+            nextSuccessfulCursor: null,
+            templateCount: 0,
+            capped: false,
+            warnings: [],
+            templates: [],
+        })).toMatchObject({
+            degraded: false,
+            statsResetAt: null,
+            baselineFirstRun: false,
+            pgServerVersion: null,
+            deallocCount: null,
+        });
+    });
+    it('accepts postgres usage stats with mean_runtime_ms and empty samples', () => {
+        const parsed = historicSqlUsageSchema.parse({
+            stats: {
+                executions: 25,
+                distinct_users: 2,
+                first_seen: '2026-05-08T10:00:00.000Z',
+                last_seen: '2026-05-08T12:00:00.000Z',
+                p50_runtime_ms: null,
+                p95_runtime_ms: null,
+                mean_runtime_ms: 32.5,
+                error_rate: 0,
+                rows_produced: 1042,
+            },
+            literal_slots: [],
+            samples: [],
+        });
+        expect(parsed.stats.mean_runtime_ms).toBe(32.5);
+        expect(parsed.samples).toEqual([]);
+    });
+    it('pins the Notion-compatible metadata envelope', () => {
+        const parsed = historicSqlMetadataSchema.parse({
+            id: 'fp_1',
+            title: 'snowflake · analytics.orders [fp_1]',
+            path: 'templates/fp_1/page.md',
+            objectType: 'historic_sql_template',
+            lastEditedAt: null,
+            properties: {
+                fingerprint: 'fp_1',
+                sub_cluster_id: null,
+                dialect: 'snowflake',
+                tables_touched: ['analytics.orders'],
+                literal_slots: [{ position: 1, type: 'string', classification: 'constant' }],
+                triage_signals: {
+                    executions_bucket: 'high',
+                    distinct_users_bucket: 'team',
+                    error_rate_bucket: 'ok',
+                    recency_bucket: 'active',
+                    service_account_only: 'false',
+                    slot_summary: '1 constant, 0 runtime',
+                },
+            },
+        });
+        expect(parsed.objectType).toBe('historic_sql_template');
+        expect(parsed.lastEditedAt).toBeNull();
+        expect(parsed.properties.triage_signals.service_account_only).toBe('false');
+    });
+});

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

@@ -0,0 +1,35 @@
+import type { HistoricSqlDialect } from './types.js';
+interface HistoricSqlGrantsMissingErrorOptions {
+    dialect: HistoricSqlDialect;
+    message: string;
+    remediation: string;
+    cause?: unknown;
+}
+export declare class HistoricSqlGrantsMissingError extends Error {
+    readonly dialect: HistoricSqlDialect;
+    readonly remediation: string;
+    constructor(options: HistoricSqlGrantsMissingErrorOptions);
+}
+interface HistoricSqlExtensionMissingErrorOptions {
+    dialect: HistoricSqlDialect;
+    message: string;
+    remediation: string;
+    cause?: unknown;
+}
+export declare class HistoricSqlExtensionMissingError extends Error {
+    readonly dialect: HistoricSqlDialect;
+    readonly remediation: string;
+    constructor(options: HistoricSqlExtensionMissingErrorOptions);
+}
+interface HistoricSqlVersionUnsupportedErrorOptions {
+    dialect: HistoricSqlDialect;
+    detectedVersion: string;
+    minimumVersion: string;
+}
+export declare class HistoricSqlVersionUnsupportedError extends Error {
+    readonly dialect: HistoricSqlDialect;
+    readonly detectedVersion: string;
+    readonly minimumVersion: string;
+    constructor(options: HistoricSqlVersionUnsupportedErrorOptions);
+}
+export {};

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

@@ -0,0 +1,32 @@
+export class HistoricSqlGrantsMissingError extends Error {
+    dialect;
+    remediation;
+    constructor(options) {
+        super(options.message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'HistoricSqlGrantsMissingError';
+        this.dialect = options.dialect;
+        this.remediation = options.remediation;
+    }
+}
+export class HistoricSqlExtensionMissingError extends Error {
+    dialect;
+    remediation;
+    constructor(options) {
+        super(options.message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'HistoricSqlExtensionMissingError';
+        this.dialect = options.dialect;
+        this.remediation = options.remediation;
+    }
+}
+export class HistoricSqlVersionUnsupportedError extends Error {
+    dialect;
+    detectedVersion;
+    minimumVersion;
+    constructor(options) {
+        super(`Unsupported ${options.dialect} version for historic-SQL ingest: detected ${options.detectedVersion}; requires ${options.minimumVersion} or newer.`);
+        this.name = 'HistoricSqlVersionUnsupportedError';
+        this.dialect = options.dialect;
+        this.detectedVersion = options.detectedVersion;
+        this.minimumVersion = options.minimumVersion;
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { ChunkResult, DiffSet, FetchContext, IngestTrigger, ScopeDescriptor, SourceAdapter, TriageSignals } from '../../types.js';
+import { type HistoricSqlSourceAdapterDeps } from './types.js';
+export declare class HistoricSqlSourceAdapter implements SourceAdapter {
+    private readonly deps;
+    readonly source = "historic-sql";
+    readonly skillNames: string[];
+    readonly reconcileSkillNames: string[];
+    readonly evidenceIndexing: "documents";
+    readonly triageSupported = true;
+    private readonly pendingPgssBaselines;
+    constructor(deps: HistoricSqlSourceAdapterDeps);
+    detect(stagedDir: string): Promise<boolean>;
+    fetch(pullConfig: unknown, stagedDir: string, ctx: FetchContext): Promise<void>;
+    chunk(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
+    describeScope(stagedDir: string): Promise<ScopeDescriptor>;
+    getTriageSignals(stagedDir: string, externalId: string): Promise<TriageSignals>;
+    onPullSucceeded(ctx: {
+        connectionId: string;
+        sourceKey: string;
+        syncId: string;
+        trigger: IngestTrigger;
+        completedAt: Date;
+        stagedDir: string;
+    }): Promise<void>;
+}

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

@@ -0,0 +1,90 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { chunkHistoricSqlStagedDir, describeHistoricSqlScope } from './chunk.js';
+import { detectHistoricSqlStagedDir } from './detect.js';
+import { stageHistoricSqlTemplates } from './stage.js';
+import { pgssBaselinePath, stagePgStatStatementsTemplates, writePgssBaselineAtomic, } from './stage-pgss.js';
+import { historicSqlManifestSchema, historicSqlMetadataSchema, historicSqlPullConfigSchema, historicSqlUsageSchema, } from './types.js';
+export class HistoricSqlSourceAdapter {
+    deps;
+    source = 'historic-sql';
+    skillNames = ['historic_sql_ingest'];
+    reconcileSkillNames = ['historic_sql_curator'];
+    evidenceIndexing = 'documents';
+    triageSupported = true;
+    pendingPgssBaselines = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    detect(stagedDir) {
+        return detectHistoricSqlStagedDir(stagedDir);
+    }
+    async fetch(pullConfig, stagedDir, ctx) {
+        const config = historicSqlPullConfigSchema.parse(pullConfig);
+        if (config.dialect === 'postgres') {
+            if (!this.deps.postgresReader) {
+                throw new Error('Historic SQL Postgres fetch requires deps.postgresReader');
+            }
+            const postgresQueryClient = this.deps.postgresQueryClient ?? this.deps.queryClient;
+            if (!postgresQueryClient ||
+                typeof postgresQueryClient !== 'object' ||
+                !('executeQuery' in postgresQueryClient) ||
+                typeof postgresQueryClient.executeQuery !== 'function') {
+                throw new Error('Historic SQL Postgres fetch requires deps.postgresQueryClient with executeQuery(sql, params?)');
+            }
+            const result = await stagePgStatStatementsTemplates({
+                stagedDir,
+                connectionId: ctx.connectionId,
+                queryClient: postgresQueryClient,
+                reader: this.deps.postgresReader,
+                sqlAnalysis: this.deps.sqlAnalysis,
+                pullConfig: config,
+                baselinePath: pgssBaselinePath(this.deps.postgresBaselineRootDir, ctx.connectionId),
+                now: this.deps.now?.(),
+            });
+            this.pendingPgssBaselines.set(stagedDir, result);
+            return;
+        }
+        await stageHistoricSqlTemplates({
+            stagedDir,
+            connectionId: ctx.connectionId,
+            queryClient: this.deps.queryClient,
+            reader: this.deps.reader,
+            sqlAnalysis: this.deps.sqlAnalysis,
+            pullConfig: config,
+            now: this.deps.now?.(),
+        });
+    }
+    chunk(stagedDir, diffSet) {
+        return chunkHistoricSqlStagedDir(stagedDir, diffSet);
+    }
+    describeScope(stagedDir) {
+        return describeHistoricSqlScope(stagedDir);
+    }
+    async getTriageSignals(stagedDir, externalId) {
+        const manifest = historicSqlManifestSchema.parse(JSON.parse(await readFile(join(stagedDir, 'manifest.json'), 'utf-8')));
+        const template = manifest.templates.find((entry) => entry.id === externalId);
+        if (!template) {
+            return {};
+        }
+        const templateDir = template.path.replace(/\/page\.md$/, '');
+        const metadata = historicSqlMetadataSchema.parse(JSON.parse(await readFile(join(stagedDir, templateDir, 'metadata.json'), 'utf-8')));
+        const usage = historicSqlUsageSchema.parse(JSON.parse(await readFile(join(stagedDir, templateDir, 'usage.json'), 'utf-8')));
+        return {
+            objectType: metadata.objectType,
+            lastEditedAt: usage.stats.last_seen,
+            propertyHints: metadata.properties.triage_signals,
+        };
+    }
+    async onPullSucceeded(ctx) {
+        const manifest = historicSqlManifestSchema.parse(JSON.parse(await readFile(join(ctx.stagedDir, 'manifest.json'), 'utf-8')));
+        if (manifest.dialect === 'postgres') {
+            const pending = this.pendingPgssBaselines.get(ctx.stagedDir);
+            if (pending) {
+                await writePgssBaselineAtomic(pending.baselinePath, pending.baseline);
+                this.pendingPgssBaselines.delete(ctx.stagedDir);
+            }
+        }
+        await this.deps.onPullSucceeded?.({ ...ctx, nextSuccessfulCursor: manifest.nextSuccessfulCursor });
+    }
+}

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

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

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

@@ -0,0 +1,259 @@
+import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+import { HistoricSqlSourceAdapter } from './historic-sql.adapter.js';
+import { pgssBaselinePath } from './stage-pgss.js';
+async function tempDir() {
+    return mkdtemp(join(tmpdir(), 'historic-sql-adapter-'));
+}
+async function writeJson(root, relPath, value) {
+    const target = join(root, relPath);
+    await mkdir(join(target, '..'), { recursive: true });
+    await writeFile(target, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+const sqlAnalysis = {
+    async analyzeForFingerprint() {
+        return {
+            fingerprint: 'fp_1',
+            normalizedSql: 'SELECT count(*) FROM analytics.orders WHERE status = ?',
+            tablesTouched: ['analytics.orders'],
+            literalSlots: [{ position: 1, type: 'string', exampleValue: 'paid' }],
+        };
+    },
+};
+const reader = {
+    async probe() { },
+    async *fetch() {
+        yield {
+            id: 'q1',
+            sql: "SELECT count(*) FROM analytics.orders WHERE status = 'paid'",
+            user: 'analyst',
+            startedAt: '2026-05-04T11:00:00.000Z',
+            endedAt: null,
+            runtimeMs: 10,
+            rowsProduced: 1,
+            success: true,
+            errorMessage: null,
+        };
+    },
+};
+describe('HistoricSqlSourceAdapter', () => {
+    it('declares canonical adapter metadata', () => {
+        const adapter = new HistoricSqlSourceAdapter({ sqlAnalysis, reader, queryClient: {} });
+        expect(adapter.source).toBe('historic-sql');
+        expect(adapter.skillNames).toEqual(['historic_sql_ingest']);
+        expect(adapter.reconcileSkillNames).toEqual(['historic_sql_curator']);
+        expect(adapter.evidenceIndexing).toBe('documents');
+        expect(adapter.triageSupported).toBe(true);
+    });
+    it('fetches staged templates through injected reader and SqlAnalysisPort', async () => {
+        const stagedDir = await tempDir();
+        const adapter = new HistoricSqlSourceAdapter({
+            sqlAnalysis,
+            reader,
+            queryClient: {},
+            now: () => new Date('2026-05-04T12:00:00.000Z'),
+        });
+        await adapter.fetch({
+            dialect: 'snowflake',
+            windowDays: 90,
+            lastSuccessfulCursor: null,
+            serviceAccountUserPatterns: [],
+            redactionPatterns: [],
+            maxTemplatesPerRun: 5000,
+        }, stagedDir, { connectionId: 'conn_1', sourceKey: 'historic-sql' });
+        await expect(adapter.detect(stagedDir)).resolves.toBe(true);
+    });
+    it('reads triage signals from usage.json and metadata properties', async () => {
+        const stagedDir = await tempDir();
+        await writeJson(stagedDir, 'manifest.json', {
+            source: 'historic-sql',
+            connectionId: 'conn_1',
+            dialect: 'snowflake',
+            fetchedAt: '2026-05-04T12:00:00.000Z',
+            windowStart: '2026-02-03T12:00:00.000Z',
+            windowEnd: '2026-05-04T12:00:00.000Z',
+            nextSuccessfulCursor: '2026-05-04T11:55:00.000Z',
+            templateCount: 1,
+            capped: false,
+            warnings: [],
+            templates: [{ id: 'fp_1', fingerprint: 'fp_1', subClusterId: null, path: 'templates/fp_1/page.md' }],
+        });
+        await writeJson(stagedDir, 'templates/fp_1/metadata.json', {
+            id: 'fp_1',
+            title: 'snowflake · analytics.orders [fp_1]',
+            path: 'templates/fp_1/page.md',
+            objectType: 'historic_sql_template',
+            lastEditedAt: null,
+            properties: {
+                fingerprint: 'fp_1',
+                sub_cluster_id: null,
+                dialect: 'snowflake',
+                tables_touched: ['analytics.orders'],
+                literal_slots: [{ position: 1, type: 'string', classification: 'constant' }],
+                triage_signals: {
+                    executions_bucket: 'high',
+                    distinct_users_bucket: 'team',
+                    error_rate_bucket: 'ok',
+                    recency_bucket: 'active',
+                    service_account_only: 'false',
+                    slot_summary: '1 constant, 0 runtime',
+                },
+            },
+        });
+        await writeFile(join(stagedDir, 'templates/fp_1/page.md'), '# fp_1\n', 'utf-8');
+        await writeJson(stagedDir, 'templates/fp_1/usage.json', {
+            stats: {
+                executions: 20,
+                distinct_users: 3,
+                first_seen: '2026-05-01T00:00:00.000Z',
+                last_seen: '2026-05-04T11:55:00.000Z',
+                p50_runtime_ms: 100,
+                p95_runtime_ms: 200,
+                error_rate: 0,
+            },
+            literal_slots: [{ position: 1, distinct_values: 1, top_values: [['paid', 20]] }],
+            samples: [],
+        });
+        const adapter = new HistoricSqlSourceAdapter({ sqlAnalysis, reader, queryClient: {} });
+        await expect(adapter.getTriageSignals(stagedDir, 'fp_1')).resolves.toEqual({
+            objectType: 'historic_sql_template',
+            lastEditedAt: '2026-05-04T11:55:00.000Z',
+            propertyHints: {
+                executions_bucket: 'high',
+                distinct_users_bucket: 'team',
+                error_rate_bucket: 'ok',
+                recency_bucket: 'active',
+                service_account_only: 'false',
+                slot_summary: '1 constant, 0 runtime',
+            },
+        });
+    });
+    it('dispatches postgres fetches through PGSS staging and writes the baseline only after pull success', async () => {
+        const stagedDir = await tempDir();
+        const baselineRootDir = await tempDir();
+        const baselinePath = pgssBaselinePath(baselineRootDir, 'conn_pg');
+        const unusedPerExecutionReader = {
+            async probe() {
+                throw new Error('per-execution reader must not be used for postgres');
+            },
+            async *fetch() {
+                throw new Error('per-execution reader must not be used for postgres');
+            },
+        };
+        const postgresReader = {
+            async probe() {
+                return { pgServerVersion: 'PostgreSQL 16.4', warnings: [] };
+            },
+            async readSnapshot() {
+                return {
+                    statsResetAt: '2026-05-08T08:00:00.000Z',
+                    deallocCount: 0,
+                    rows: [
+                        {
+                            queryid: '901',
+                            userid: '11',
+                            username: 'analyst',
+                            dbid: '5',
+                            database: 'warehouse',
+                            query: 'SELECT count(*) FROM analytics.orders WHERE status = $1',
+                            calls: 9,
+                            totalExecTime: 90,
+                            meanExecTime: 10,
+                            totalRows: 18,
+                        },
+                    ],
+                };
+            },
+        };
+        const adapter = new HistoricSqlSourceAdapter({
+            sqlAnalysis,
+            reader: unusedPerExecutionReader,
+            queryClient: {},
+            postgresReader,
+            postgresQueryClient: {
+                async executeQuery() {
+                    return { headers: [], rows: [] };
+                },
+            },
+            postgresBaselineRootDir: baselineRootDir,
+            now: () => new Date('2026-05-08T12:00:00.000Z'),
+        });
+        await adapter.fetch({
+            dialect: 'postgres',
+            windowDays: 90,
+            lastSuccessfulCursor: null,
+            serviceAccountUserPatterns: [],
+            redactionPatterns: [],
+            maxTemplatesPerRun: 5000,
+            minCalls: 5,
+        }, stagedDir, { connectionId: 'conn_pg', sourceKey: 'historic-sql' });
+        const manifest = JSON.parse(await readFile(join(stagedDir, 'manifest.json'), 'utf-8'));
+        expect(manifest.dialect).toBe('postgres');
+        expect(manifest.baselineFirstRun).toBe(true);
+        expect(manifest.templates).toEqual([
+            { id: 'db5_q901', fingerprint: 'fp_1', subClusterId: null, path: 'templates/db5_q901/page.md' },
+        ]);
+        await expect(readFile(baselinePath, 'utf-8')).rejects.toMatchObject({ code: 'ENOENT' });
+        await adapter.onPullSucceeded({
+            connectionId: 'conn_pg',
+            sourceKey: 'historic-sql',
+            syncId: 'sync_pg',
+            trigger: 'scheduled_pull',
+            completedAt: new Date('2026-05-08T12:01:00.000Z'),
+            stagedDir,
+        });
+        const baseline = JSON.parse(await readFile(baselinePath, 'utf-8'));
+        expect(baseline.fetchedAt).toBe('2026-05-08T12:00:00.000Z');
+        expect(baseline.templates.db5_q901.perUser['11'].calls).toBe(9);
+    });
+    it('fails postgres fetches clearly when no PGSS reader is configured', async () => {
+        const adapter = new HistoricSqlSourceAdapter({ sqlAnalysis, reader, queryClient: {} });
+        await expect(adapter.fetch({
+            dialect: 'postgres',
+            windowDays: 90,
+            lastSuccessfulCursor: null,
+            serviceAccountUserPatterns: [],
+            redactionPatterns: [],
+            maxTemplatesPerRun: 5000,
+            minCalls: 5,
+        }, await tempDir(), { connectionId: 'conn_pg', sourceKey: 'historic-sql' })).rejects.toThrow('Historic SQL Postgres fetch requires deps.postgresReader');
+    });
+    it('forwards manifest cursor through onPullSucceeded without changing the SourceAdapter signature', async () => {
+        const stagedDir = await tempDir();
+        await writeJson(stagedDir, 'manifest.json', {
+            source: 'historic-sql',
+            connectionId: 'conn_1',
+            dialect: 'snowflake',
+            fetchedAt: '2026-05-04T12:00:00.000Z',
+            windowStart: '2026-02-03T12:00:00.000Z',
+            windowEnd: '2026-05-04T12:00:00.000Z',
+            nextSuccessfulCursor: '2026-05-04T11:55:00.000Z',
+            templateCount: 0,
+            capped: false,
+            warnings: [],
+            templates: [],
+        });
+        const onPullSucceeded = vi.fn(async () => { });
+        const adapter = new HistoricSqlSourceAdapter({ sqlAnalysis, reader, queryClient: {}, onPullSucceeded });
+        const completedAt = new Date('2026-05-04T12:01:00.000Z');
+        await adapter.onPullSucceeded({
+            connectionId: 'conn_1',
+            sourceKey: 'historic-sql',
+            syncId: 'sync_1',
+            trigger: 'scheduled_pull',
+            completedAt,
+            stagedDir,
+        });
+        expect(onPullSucceeded).toHaveBeenCalledWith({
+            connectionId: 'conn_1',
+            sourceKey: 'historic-sql',
+            syncId: 'sync_1',
+            trigger: 'scheduled_pull',
+            completedAt,
+            stagedDir,
+            nextSuccessfulCursor: '2026-05-04T11:55:00.000Z',
+        });
+    });
+});

package/node_modules/@ktx/context/dist/ingest/adapters/historic-sql/postgres-pgss-query-history-reader.d.ts

@@ -0,0 +1,8 @@
+import type { PostgresPgssProbeResult, PostgresPgssReader, PostgresPgssSnapshot } from './types.js';
+export declare class PostgresPgssQueryHistoryReader implements PostgresPgssReader {
+    probe(client: unknown): Promise<PostgresPgssProbeResult>;
+    readSnapshot(client: unknown, options: {
+        minCalls: number;
+        maxTemplates: number;
+    }): Promise<PostgresPgssSnapshot>;
+}