@kaelio/ktx 0.13.0 → 0.14.0

package/dist/context/scan/relationship-llm-proposal.js

@@ -45,6 +45,9 @@ function profileForColumn(profile, table, column) {
 function rowCountForTable(profile, table) {
     return profile.tables.find((item) => item.table.name.toLowerCase() === table.ref.name.toLowerCase())?.rowCount ?? null;
 }
+function resolvedDescription(descriptions) {
+    return descriptions.ai ?? descriptions.db ?? null;
+}
 function buildEvidencePacket(schema, profile, settings) {
     return {
         connectionId: schema.connectionId,
@@ -52,33 +55,39 @@ function buildEvidencePacket(schema, profile, settings) {
         tables: schema.tables
             .filter((table) => table.enabled)
             .slice(0, settings.maxTablesPerBatch)
-            .map((table) => ({
-            name: table.ref.name,
-            catalog: table.ref.catalog,
-            db: table.ref.db,
-            rowCount: rowCountForTable(profile, table),
-            columns: table.columns.slice(0, settings.maxColumnsPerTable).map((column) => {
-                const columnProfile = profileForColumn(profile, table, column);
-                return {
-                    name: column.name,
-                    nativeType: column.nativeType,
-                    normalizedType: column.normalizedType,
-                    dimensionType: column.dimensionType,
-                    nullable: column.nullable,
-                    declaredPrimaryKey: column.primaryKey,
-                    profile: columnProfile
-                        ? {
-                            rowCount: columnProfile.rowCount,
-                            nullCount: columnProfile.nullCount,
-                            distinctCount: columnProfile.distinctCount,
-                            uniquenessRatio: columnProfile.uniquenessRatio,
-                            nullRate: columnProfile.nullRate,
-                            sampleValues: columnProfile.sampleValues.slice(0, settings.maxSampleValuesPerColumn),
-                        }
-                        : null,
-                };
-            }),
-        })),
+            .map((table) => {
+            const tableDescription = resolvedDescription(table.descriptions);
+            return {
+                name: table.ref.name,
+                catalog: table.ref.catalog,
+                db: table.ref.db,
+                rowCount: rowCountForTable(profile, table),
+                ...(tableDescription ? { description: tableDescription } : {}),
+                columns: table.columns.slice(0, settings.maxColumnsPerTable).map((column) => {
+                    const columnProfile = profileForColumn(profile, table, column);
+                    const columnDescription = resolvedDescription(column.descriptions);
+                    return {
+                        name: column.name,
+                        nativeType: column.nativeType,
+                        normalizedType: column.normalizedType,
+                        dimensionType: column.dimensionType,
+                        nullable: column.nullable,
+                        declaredPrimaryKey: column.primaryKey,
+                        ...(columnDescription ? { description: columnDescription } : {}),
+                        profile: columnProfile
+                            ? {
+                                rowCount: columnProfile.rowCount,
+                                nullCount: columnProfile.nullCount,
+                                distinctCount: columnProfile.distinctCount,
+                                uniquenessRatio: columnProfile.uniquenessRatio,
+                                nullRate: columnProfile.nullRate,
+                                sampleValues: columnProfile.sampleValues.slice(0, settings.maxSampleValuesPerColumn),
+                            }
+                            : null,
+                    };
+                }),
+            };
+        }),
     };
 }
 function pkProposalKey(table, column) {

package/dist/context/scan/relationship-profiling.d.ts

@@ -1,6 +1,7 @@
-import type { KtxDialect } from '../connections/dialects.js';
+import type { KtxSqlDialect } from '../connections/dialects.js';
 import type { KtxEnrichedSchema } from './enrichment-types.js';
-import type { KtxConnectionDriver, KtxQueryResult, KtxReadOnlyQueryInput, KtxScanContext, KtxTableRef } from './types.js';
+import { type KtxRelationshipDetectionBudget } from './relationship-detection-budget.js';
+import type { KtxConnectionDriver, KtxProgressPort, KtxQueryResult, KtxReadOnlyQueryInput, KtxScanContext, KtxTableRef } from './types.js';
 export interface KtxRelationshipReadOnlyExecutor {
     executeReadOnly(input: KtxReadOnlyQueryInput, ctx: KtxScanContext): Promise<KtxQueryResult>;
 }
@@ -42,7 +43,8 @@ export interface KtxRelationshipProfileCache {
 }
 export interface ProfileKtxRelationshipSchemaInput {
     connectionId: string;
-    dialect: KtxDialect;
+    driver: KtxConnectionDriver;
+    dialect: KtxSqlDialect | null;
     schema: KtxEnrichedSchema;
     executor: KtxRelationshipReadOnlyExecutor | null;
     ctx: KtxScanContext;
@@ -50,6 +52,8 @@ export interface ProfileKtxRelationshipSchemaInput {
     profileSampleRows?: number;
     profileConcurrency?: number;
     cache?: KtxRelationshipProfileCache;
+    budget?: KtxRelationshipDetectionBudget;
+    progress?: KtxProgressPort;
 }
 export declare function createKtxRelationshipProfileCache(): KtxRelationshipProfileCache;
 export declare function profileKtxRelationshipSchema(input: ProfileKtxRelationshipSchemaInput): Promise<KtxRelationshipProfileArtifact>;

package/dist/context/scan/relationship-profiling.js

@@ -1,4 +1,4 @@
-import { mapWithConcurrency } from './relationship-validation.js';
+import { mapWithBudget } from './relationship-detection-budget.js';
 export function createKtxRelationshipProfileCache() {
     return { tableProfiles: new Map() };
 }
@@ -180,10 +180,10 @@ async function queryTableProfile(input) {
     };
 }
 export async function profileKtxRelationshipSchema(input) {
-    if (!input.executor) {
+    if (!input.executor || !input.dialect) {
         return {
             connectionId: input.connectionId,
-            driver: input.dialect.type,
+            driver: input.driver,
             sqlAvailable: false,
             queryCount: 0,
             tables: [],
@@ -196,51 +196,63 @@ export async function profileKtxRelationshipSchema(input) {
     const columns = {};
     const warnings = [];
     const executor = input.executor;
+    const dialect = input.dialect;
     const enabledTables = input.schema.tables.filter((candidate) => candidate.enabled);
-    const tableResults = await mapWithConcurrency(enabledTables, input.profileConcurrency ?? 4, async (table) => {
-        const sampleValuesPerColumn = input.sampleValuesPerColumn ?? 5;
-        const profileSampleRows = input.profileSampleRows ?? 10000;
-        const cacheKey = tableProfileCacheKey({
-            connectionId: input.connectionId,
-            dialect: input.dialect,
-            ctx: input.ctx,
-            table: table.ref,
-            sampleValuesPerColumn,
-            profileSampleRows,
-        });
-        const cached = input.cache?.tableProfiles.get(cacheKey);
-        if (cached) {
-            return { cached, queryCount: 0 };
-        }
-        try {
-            const tableProfile = await queryTableProfile({
+    const { results: tableResults } = await mapWithBudget({
+        inputs: enabledTables,
+        concurrency: input.profileConcurrency ?? 4,
+        budget: input.budget,
+        onStart: async (index, total) => {
+            await input.progress?.update((index + 1) / total, `Profiling table ${index + 1}/${total}`, { transient: true });
+        },
+        mapOne: async (table) => {
+            const sampleValuesPerColumn = input.sampleValuesPerColumn ?? 5;
+            const profileSampleRows = input.profileSampleRows ?? 10000;
+            const cacheKey = tableProfileCacheKey({
                 connectionId: input.connectionId,
-                dialect: input.dialect,
-                table,
-                executor,
+                dialect,
                 ctx: input.ctx,
+                table: table.ref,
                 sampleValuesPerColumn,
                 profileSampleRows,
             });
-            input.cache?.tableProfiles.set(cacheKey, {
-                table: tableProfile.table,
-                columns: tableProfile.columns,
-                warnings: [],
-            });
-            return { tableProfile };
-        }
-        catch (error) {
-            const failureWarning = `profile_failed:${table.ref.name}:${error instanceof Error ? error.message : String(error)}`;
-            const cachedFailure = {
-                table: { table: table.ref, rowCount: 0 },
-                columns: {},
-                warnings: [failureWarning],
-            };
-            input.cache?.tableProfiles.set(cacheKey, cachedFailure);
-            return { cached: cachedFailure, queryCount: 0 };
-        }
+            const cached = input.cache?.tableProfiles.get(cacheKey);
+            if (cached) {
+                return { cached, queryCount: 0 };
+            }
+            try {
+                const tableProfile = await queryTableProfile({
+                    connectionId: input.connectionId,
+                    dialect,
+                    table,
+                    executor,
+                    ctx: input.ctx,
+                    sampleValuesPerColumn,
+                    profileSampleRows,
+                });
+                input.cache?.tableProfiles.set(cacheKey, {
+                    table: tableProfile.table,
+                    columns: tableProfile.columns,
+                    warnings: [],
+                });
+                return { tableProfile };
+            }
+            catch (error) {
+                const failureWarning = `profile_failed:${table.ref.name}:${error instanceof Error ? error.message : String(error)}`;
+                const cachedFailure = {
+                    table: { table: table.ref, rowCount: 0 },
+                    columns: {},
+                    warnings: [failureWarning],
+                };
+                input.cache?.tableProfiles.set(cacheKey, cachedFailure);
+                return { cached: cachedFailure, queryCount: 0 };
+            }
+        },
     });
     for (const result of tableResults) {
+        if (!result) {
+            continue;
+        }
         if ('tableProfile' in result) {
             queryTotal += result.tableProfile.queryCount;
             tables.push(result.tableProfile.table);
@@ -255,7 +267,7 @@ export async function profileKtxRelationshipSchema(input) {
     }
     return {
         connectionId: input.connectionId,
-        driver: input.dialect.type,
+        driver: input.driver,
         sqlAvailable: true,
         queryCount: queryTotal,
         tables,

package/dist/context/scan/relationship-validation.d.ts

@@ -1,8 +1,9 @@
-import type { KtxDialect } from '../connections/dialects.js';
+import type { KtxSqlDialect } from '../connections/dialects.js';
 import { type KtxRelationshipValidationBudget } from './relationship-budget.js';
 import type { KtxRelationshipDiscoveryCandidate } from './relationship-candidates.js';
+import { type KtxRelationshipDetectionBudget } from './relationship-detection-budget.js';
 import { type KtxRelationshipProfileArtifact, type KtxRelationshipReadOnlyExecutor } from './relationship-profiling.js';
-import type { KtxScanContext } from './types.js';
+import type { KtxProgressPort, KtxScanContext } from './types.js';
 type KtxValidatedRelationshipStatus = 'accepted' | 'review' | 'rejected';
 interface KtxRelationshipValidationSettings {
     acceptThreshold: number;
@@ -34,14 +35,15 @@ export interface KtxValidatedRelationshipDiscoveryCandidate extends Omit<KtxRela
 }
 export interface ValidateKtxRelationshipDiscoveryCandidatesInput {
     connectionId: string;
-    dialect: KtxDialect;
+    dialect: KtxSqlDialect | null;
     candidates: readonly KtxRelationshipDiscoveryCandidate[];
     profiles: KtxRelationshipProfileArtifact;
     executor: KtxRelationshipReadOnlyExecutor | null;
     ctx: KtxScanContext;
     tableCount?: number;
     settings?: Partial<KtxRelationshipValidationSettings>;
+    budget?: KtxRelationshipDetectionBudget;
+    progress?: KtxProgressPort;
 }
-export declare function mapWithConcurrency<TInput, TOutput>(inputs: readonly TInput[], concurrency: number, mapOne: (input: TInput) => Promise<TOutput>): Promise<TOutput[]>;
 export declare function validateKtxRelationshipDiscoveryCandidates(input: ValidateKtxRelationshipDiscoveryCandidatesInput): Promise<KtxValidatedRelationshipDiscoveryCandidate[]>;
 export {};

package/dist/context/scan/relationship-validation.js

@@ -1,4 +1,6 @@
+import { KtxQueryError } from '../../errors.js';
 import { applyKtxRelationshipValidationBudget } from './relationship-budget.js';
+import { mapWithBudget } from './relationship-detection-budget.js';
 const DEFAULT_SETTINGS = {
     acceptThreshold: 0.85,
     reviewThreshold: 0.55,
@@ -89,20 +91,6 @@ function statusFor(input) {
     }
     return 'rejected';
 }
-export async function mapWithConcurrency(inputs, concurrency, mapOne) {
-    const safeConcurrency = Math.max(1, Math.floor(concurrency));
-    const outputs = new Array(inputs.length);
-    let nextIndex = 0;
-    async function worker() {
-        while (nextIndex < inputs.length) {
-            const index = nextIndex;
-            nextIndex += 1;
-            outputs[index] = await mapOne(inputs[index]);
-        }
-    }
-    await Promise.all(Array.from({ length: Math.min(safeConcurrency, inputs.length) }, () => worker()));
-    return outputs;
-}
 function reviewWithoutValidation(candidate, profiles, reason) {
     const sourceColumn = singleRelationshipColumn(candidate.from);
     const targetColumn = singleRelationshipColumn(candidate.to);
@@ -129,10 +117,11 @@ function reviewWithoutValidation(candidate, profiles, reason) {
 }
 export async function validateKtxRelationshipDiscoveryCandidates(input) {
     const settings = mergeSettings(input.settings);
-    if (!input.executor || !input.profiles.sqlAvailable) {
+    if (!input.executor || !input.profiles.sqlAvailable || !input.dialect) {
         return input.candidates.map((candidate) => reviewWithoutValidation(candidate, input.profiles, 'validation_unavailable'));
     }
     const executor = input.executor;
+    const dialect = input.dialect;
     async function validateCandidate(candidate) {
         const sourceColumn = singleRelationshipColumn(candidate.from);
         const targetColumn = singleRelationshipColumn(candidate.to);
@@ -141,18 +130,31 @@ export async function validateKtxRelationshipDiscoveryCandidates(input) {
         if (!sourceProfile || !targetProfile) {
             return reviewWithoutValidation(candidate, input.profiles, 'profile_unavailable');
         }
-        const result = await executor.executeReadOnly({
-            connectionId: input.connectionId,
-            sql: buildCoverageSql({
-                dialect: input.dialect,
-                childTable: candidate.from.table,
-                childColumn: sourceColumn,
-                parentTable: candidate.to.table,
-                parentColumn: targetColumn,
-                maxDistinctSourceValues: settings.maxDistinctSourceValues,
-            }),
-            maxRows: 1,
-        }, input.ctx);
+        let result;
+        try {
+            result = await executor.executeReadOnly({
+                connectionId: input.connectionId,
+                sql: buildCoverageSql({
+                    dialect,
+                    childTable: candidate.from.table,
+                    childColumn: sourceColumn,
+                    parentTable: candidate.to.table,
+                    parentColumn: targetColumn,
+                    maxDistinctSourceValues: settings.maxDistinctSourceValues,
+                }),
+                maxRows: 1,
+            }, input.ctx);
+        }
+        catch (error) {
+            // A bounded-query timeout (or other query rejection) on this one coverage
+            // probe is best-effort: skip the candidate to review rather than aborting
+            // the whole validation pass.
+            if (error instanceof KtxQueryError) {
+                input.ctx.logger?.warn(`relationship validation query skipped for ${candidate.from.table.name}.${sourceColumn} -> ${candidate.to.table.name}.${targetColumn}: ${error.message}`);
+                return reviewWithoutValidation(candidate, input.profiles, 'validation_query_failed');
+            }
+            throw error;
+        }
         const childDistinct = numberAt(result, 'child_distinct');
         const parentDistinct = numberAt(result, 'parent_distinct');
         const overlap = numberAt(result, 'overlap');
@@ -208,14 +210,26 @@ export async function validateKtxRelationshipDiscoveryCandidates(input) {
         budget: settings.validationBudget,
         score: (candidate) => candidate.confidence,
     });
-    const validated = await mapWithConcurrency(budgeted.toValidate.map((entry) => entry.candidate), settings.concurrency, validateCandidate);
+    const { results: validated } = await mapWithBudget({
+        inputs: budgeted.toValidate,
+        concurrency: settings.concurrency,
+        budget: input.budget,
+        onStart: async (index, total) => {
+            await input.progress?.update((index + 1) / total, `Validating candidate ${index + 1}/${total}`, {
+                transient: true,
+            });
+        },
+        mapOne: (entry) => validateCandidate(entry.candidate),
+    });
     const byOriginalIndex = new Map();
     for (let index = 0; index < budgeted.toValidate.length; index += 1) {
-        const originalIndex = budgeted.toValidate[index]?.originalIndex;
-        const candidate = validated[index];
-        if (originalIndex !== undefined && candidate) {
-            byOriginalIndex.set(originalIndex, candidate);
+        const entry = budgeted.toValidate[index];
+        if (!entry) {
+            continue;
         }
+        // A candidate left unvalidated by the wall-clock budget degrades to the
+        // same review status as one deferred by the validation count budget.
+        byOriginalIndex.set(entry.originalIndex, validated[index] ?? reviewWithoutValidation(entry.candidate, input.profiles, 'validation_unattempted'));
     }
     for (const entry of budgeted.deferred) {
         byOriginalIndex.set(entry.originalIndex, reviewWithoutValidation(entry.candidate, input.profiles, 'validation_unattempted'));

package/dist/context/scan/sqlite-local-enrichment-state-store.d.ts

@@ -1,11 +1,18 @@
+import type { ContentResultCache } from '../cache/content-result-cache.js';
 import type { KtxScanEnrichmentCompletedStage, KtxScanEnrichmentFailedStage, KtxScanEnrichmentStageLookup, KtxScanEnrichmentStageRecord, KtxScanEnrichmentStateStore } from './enrichment-state.js';
+import type { KtxScanEnrichmentStage } from './types.js';
 export interface SqliteLocalScanEnrichmentStateStoreOptions {
     dbPath: string;
+    cache?: ContentResultCache;
 }
 export declare class SqliteLocalScanEnrichmentStateStore implements KtxScanEnrichmentStateStore {
-    private readonly db;
+    private readonly cache;
     constructor(options: SqliteLocalScanEnrichmentStateStoreOptions);
     findCompletedStage<TOutput = unknown>(input: KtxScanEnrichmentStageLookup): Promise<KtxScanEnrichmentCompletedStage<TOutput> | null>;
+    findLatestCompletedStage(input: {
+        connectionId: string;
+        stage: KtxScanEnrichmentStage;
+    }): Promise<KtxScanEnrichmentCompletedStage | null>;
     saveCompletedStage<TOutput = unknown>(input: Omit<KtxScanEnrichmentCompletedStage<TOutput>, 'status' | 'errorMessage'>): Promise<void>;
     saveFailedStage(input: Omit<KtxScanEnrichmentFailedStage, 'status' | 'output'>): Promise<void>;
     listRunStages(runId: string): Promise<KtxScanEnrichmentStageRecord[]>;

package/dist/context/scan/sqlite-local-enrichment-state-store.js

@@ -1,190 +1,102 @@
-import { mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
-import Database from 'better-sqlite3';
-function parseStageRow(row) {
-    if (row.status === 'completed') {
+import { SqliteContentResultCache } from '../cache/sqlite-content-result-cache.js';
+import { KTX_SCAN_ENRICHMENT_STAGES } from './enrichment-state.js';
+import { KTX_SCAN_MODES } from './types.js';
+function namespace(stage) {
+    return `scan:${stage}`;
+}
+function metadataFor(input) {
+    return {
+        connectionId: input.connectionId,
+        syncId: input.syncId,
+        mode: input.mode,
+        stage: input.stage,
+    };
+}
+function isScanMode(value) {
+    return typeof value === 'string' && KTX_SCAN_MODES.includes(value);
+}
+function isScanEnrichmentStage(value) {
+    return typeof value === 'string' && KTX_SCAN_ENRICHMENT_STAGES.includes(value);
+}
+function parseMetadata(record) {
+    const { connectionId, syncId, mode, stage } = record.metadata;
+    if (typeof connectionId !== 'string' || typeof syncId !== 'string' || !isScanMode(mode) || !isScanEnrichmentStage(stage)) {
+        throw new Error(`Invalid scan enrichment cache metadata for ${record.namespace}/${record.scopeKey}`);
+    }
+    return { connectionId, syncId, mode, stage };
+}
+function toScanRecord(record) {
+    const metadata = parseMetadata(record);
+    const base = {
+        runId: record.runId,
+        connectionId: metadata.connectionId,
+        syncId: metadata.syncId,
+        mode: metadata.mode,
+        stage: metadata.stage,
+        inputHash: record.inputHash,
+        updatedAt: record.updatedAt,
+    };
+    if (record.status === 'completed') {
         return {
-            runId: row.run_id,
-            connectionId: row.connection_id,
-            syncId: row.sync_id,
-            mode: row.mode,
-            stage: row.stage,
-            inputHash: row.input_hash,
+            ...base,
             status: 'completed',
-            output: JSON.parse(row.output_json ?? 'null'),
+            output: record.output,
             errorMessage: null,
-            updatedAt: row.updated_at,
         };
     }
     return {
-        runId: row.run_id,
-        connectionId: row.connection_id,
-        syncId: row.sync_id,
-        mode: row.mode,
-        stage: row.stage,
-        inputHash: row.input_hash,
+        ...base,
         status: 'failed',
         output: null,
-        errorMessage: row.error_message ?? 'Unknown enrichment stage failure',
-        updatedAt: row.updated_at,
+        errorMessage: record.errorMessage,
     };
 }
-function isSafeRunId(runId) {
-    return /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(runId);
-}
 export class SqliteLocalScanEnrichmentStateStore {
-    db;
+    cache;
     constructor(options) {
-        mkdirSync(dirname(options.dbPath), { recursive: true });
-        this.db = new Database(options.dbPath);
-        this.db.pragma('journal_mode = WAL');
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS local_scan_enrichment_stages (
-        run_id TEXT NOT NULL,
-        stage TEXT NOT NULL,
-        input_hash TEXT NOT NULL,
-        connection_id TEXT NOT NULL,
-        sync_id TEXT NOT NULL,
-        mode TEXT NOT NULL,
-        status TEXT NOT NULL,
-        output_json TEXT,
-        error_message TEXT,
-        updated_at TEXT NOT NULL,
-        PRIMARY KEY (run_id, stage)
-      );
-
-      CREATE INDEX IF NOT EXISTS local_scan_enrichment_stages_run_idx
-        ON local_scan_enrichment_stages (run_id, updated_at, stage);
-    `);
+        this.cache = options.cache ?? new SqliteContentResultCache({ dbPath: options.dbPath });
     }
     async findCompletedStage(input) {
-        if (!isSafeRunId(input.runId)) {
-            return null;
-        }
-        const row = this.db
-            .prepare(`
-        SELECT *
-        FROM local_scan_enrichment_stages
-        WHERE run_id = ?
-          AND stage = ?
-          AND input_hash = ?
-          AND status = 'completed'
-      `)
-            .get(input.runId, input.stage, input.inputHash);
-        if (!row) {
-            return null;
-        }
-        const parsed = parseStageRow(row);
-        return parsed.status === 'completed' ? parsed : null;
+        const record = await this.cache.findCompletedResult({
+            namespace: namespace(input.stage),
+            scopeKey: input.connectionId,
+            inputHash: input.inputHash,
+        });
+        return record ? toScanRecord(record) : null;
+    }
+    async findLatestCompletedStage(input) {
+        const record = await this.cache.findLatestCompletedResult({
+            namespace: namespace(input.stage),
+            scopeKey: input.connectionId,
+        });
+        return record ? toScanRecord(record) : null;
     }
     async saveCompletedStage(input) {
-        this.db
-            .prepare(`
-        INSERT INTO local_scan_enrichment_stages (
-          run_id,
-          stage,
-          input_hash,
-          connection_id,
-          sync_id,
-          mode,
-          status,
-          output_json,
-          error_message,
-          updated_at
-        )
-        VALUES (
-          @runId,
-          @stage,
-          @inputHash,
-          @connectionId,
-          @syncId,
-          @mode,
-          'completed',
-          @outputJson,
-          NULL,
-          @updatedAt
-        )
-        ON CONFLICT(run_id, stage) DO UPDATE SET
-          input_hash = excluded.input_hash,
-          connection_id = excluded.connection_id,
-          sync_id = excluded.sync_id,
-          mode = excluded.mode,
-          status = excluded.status,
-          output_json = excluded.output_json,
-          error_message = excluded.error_message,
-          updated_at = excluded.updated_at
-      `)
-            .run({
+        await this.cache.saveCompletedResult({
             runId: input.runId,
-            stage: input.stage,
+            namespace: namespace(input.stage),
+            scopeKey: input.connectionId,
             inputHash: input.inputHash,
-            connectionId: input.connectionId,
-            syncId: input.syncId,
-            mode: input.mode,
-            outputJson: JSON.stringify(input.output),
+            output: input.output,
+            metadata: metadataFor(input),
             updatedAt: input.updatedAt,
         });
     }
     async saveFailedStage(input) {
-        this.db
-            .prepare(`
-        INSERT INTO local_scan_enrichment_stages (
-          run_id,
-          stage,
-          input_hash,
-          connection_id,
-          sync_id,
-          mode,
-          status,
-          output_json,
-          error_message,
-          updated_at
-        )
-        VALUES (
-          @runId,
-          @stage,
-          @inputHash,
-          @connectionId,
-          @syncId,
-          @mode,
-          'failed',
-          NULL,
-          @errorMessage,
-          @updatedAt
-        )
-        ON CONFLICT(run_id, stage) DO UPDATE SET
-          input_hash = excluded.input_hash,
-          connection_id = excluded.connection_id,
-          sync_id = excluded.sync_id,
-          mode = excluded.mode,
-          status = excluded.status,
-          output_json = excluded.output_json,
-          error_message = excluded.error_message,
-          updated_at = excluded.updated_at
-      `)
-            .run({
+        await this.cache.saveFailedResult({
             runId: input.runId,
-            stage: input.stage,
+            namespace: namespace(input.stage),
+            scopeKey: input.connectionId,
             inputHash: input.inputHash,
-            connectionId: input.connectionId,
-            syncId: input.syncId,
-            mode: input.mode,
             errorMessage: input.errorMessage,
+            metadata: metadataFor(input),
             updatedAt: input.updatedAt,
         });
     }
     async listRunStages(runId) {
-        if (!isSafeRunId(runId)) {
-            return [];
-        }
-        const rows = this.db
-            .prepare(`
-        SELECT *
-        FROM local_scan_enrichment_stages
-        WHERE run_id = ?
-        ORDER BY updated_at ASC, stage ASC
-      `)
-            .all(runId);
-        return rows.map((row) => parseStageRow(row));
+        const records = await this.cache.listRunResults(runId);
+        return records
+            .filter((record) => record.namespace.startsWith('scan:'))
+            .map((record) => toScanRecord(record));
     }
 }