@kaelio/ktx 0.13.1 → 0.15.0

package/dist/context/scan/local-enrichment.d.ts

@@ -1,11 +1,13 @@
 import type { KtxLlmRuntimePort } from '../../context/llm/runtime-port.js';
 import { type KtxScanRelationshipConfig } from '../project/config.js';
-import { type KtxScanEnrichmentStateStore } from './enrichment-state.js';
+import { type KtxScanEmbeddingIdentity, type KtxScanEnrichmentStateStore, type KtxScanLlmIdentity } from './enrichment-state.js';
+import type { KtxScanDescriptionResumeStore } from './local-enrichment-artifacts.js';
 import type { KtxEmbeddingUpdate, KtxEnrichedSchema, KtxRelationshipUpdate } from './enrichment-types.js';
 import type { KtxCompositeRelationshipCandidate } from './relationship-composite-candidates.js';
+import type { KtxRelationshipDetectionStopReason } from './relationship-detection-budget.js';
 import type { KtxResolvedRelationshipDiscoveryCandidate } from './relationship-graph-resolver.js';
 import type { KtxRelationshipProfileArtifact } from './relationship-profiling.js';
-import type { KtxEmbeddingPort, KtxScanConnector, KtxScanContext, KtxScanEnrichmentStateSummary, KtxScanEnrichmentSummary, KtxScanMode, KtxScanRelationshipSummary, KtxScanWarning, KtxSchemaSnapshot, KtxTableRef } from './types.js';
+import type { KtxEmbeddingPort, KtxScanConnector, KtxScanContext, KtxScanEnrichmentStage, KtxScanEnrichmentStateSummary, KtxScanEnrichmentSummary, KtxScanMode, KtxScanRelationshipSummary, KtxScanWarning, KtxSchemaSnapshot, KtxTableRef } from './types.js';
 export interface KtxLocalScanEnrichmentProviders {
     llmRuntime: KtxLlmRuntimePort;
     embedding?: KtxEmbeddingPort | null;
@@ -14,15 +16,45 @@ export interface KtxLocalScanEnrichmentInput {
     connectionId: string;
     mode: KtxScanMode;
     detectRelationships?: boolean;
+    /**
+     * Enrichment stages to (re)run this invocation. Undefined runs every eligible
+     * stage and respects the completed-stage short-circuit (spec-19 resume). When
+     * present, only the named stages run — each force-recomputes (bypassing the
+     * short-circuit) while unselected stages are left untouched on disk (D3).
+     */
+    stages?: KtxScanEnrichmentStage[];
     connector: KtxScanConnector;
     snapshot?: KtxSchemaSnapshot;
     context: KtxScanContext;
     providers: KtxLocalScanEnrichmentProviders | null;
     stateStore?: KtxScanEnrichmentStateStore | null;
+    /**
+     * Durable per-batch resume record for the descriptions stage. When present, an
+     * interrupted descriptions stage resumes by re-enriching only the tables not
+     * already flushed (inputHash-gated). Null/undefined disables incremental flush.
+     */
+    descriptionResumeStore?: KtxScanDescriptionResumeStore | null;
+    /**
+     * Lazily loads the descriptions already persisted in the on-disk _schema, used
+     * to feed embeddings + relationships their description context when the
+     * descriptions stage does not run this invocation (e.g. `--stages relationships`).
+     * Called at most once and only when a downstream stage needs it, so a normal
+     * full run never pays the read.
+     */
+    loadPriorDescriptions?: (snapshot: KtxSchemaSnapshot) => Promise<KtxLocalScanEnrichmentResult['descriptionUpdates']>;
     syncId?: string;
-    providerIdentity?: Record<string, unknown>;
+    /** Description-LLM identity that keys the descriptions + relationships stage hashes. */
+    llmIdentity?: KtxScanLlmIdentity;
+    /** Embedding-model identity that keys the embeddings stage hash. */
+    embeddingIdentity?: KtxScanEmbeddingIdentity;
     relationshipSettings?: KtxScanRelationshipConfig;
     now?: () => Date;
+    /**
+     * Invoked once the last non-relationship stage completes and before
+     * relationship detection runs, so the descriptions + embeddings reach the
+     * queryable layer even if the relationship stage is later interrupted.
+     */
+    onCheckpoint?: (checkpoint: KtxLocalScanEnrichmentResult) => Promise<void>;
 }
 export interface KtxLocalScanEnrichmentResult {
     snapshot: KtxSchemaSnapshot;
@@ -40,7 +72,10 @@ export interface KtxLocalScanEnrichmentResult {
     relationshipProfile: KtxRelationshipProfileArtifact | null;
     resolvedRelationships: KtxResolvedRelationshipDiscoveryCandidate[] | null;
     compositeRelationships: KtxCompositeRelationshipCandidate[] | null;
+    relationshipPartial: {
+        reason: KtxRelationshipDetectionStopReason;
+    } | null;
 }
 export declare function createDeterministicLocalScanEnrichmentProviders(): KtxLocalScanEnrichmentProviders;
-export declare function snapshotToKtxEnrichedSchema(snapshot: KtxSchemaSnapshot, embeddingsByColumnId?: ReadonlyMap<string, number[]>): KtxEnrichedSchema;
+export declare function snapshotToKtxEnrichedSchema(snapshot: KtxSchemaSnapshot, embeddingsByColumnId?: ReadonlyMap<string, number[]>, descriptions?: KtxLocalScanEnrichmentResult['descriptionUpdates']): KtxEnrichedSchema;
 export declare function runLocalScanEnrichment(input: KtxLocalScanEnrichmentInput): Promise<KtxLocalScanEnrichmentResult>;