@memberjunction/db-auto-doc 5.36.0 → 5.38.0

package/dist/discovery/EmbeddingProvider.js

@@ -0,0 +1,87 @@
+/**
+ * EmbeddingProvider — thin wrapper over MemberJunction's `BaseEmbeddings` infrastructure.
+ *
+ * Embeddings are produced through the same MJ ClassFactory + driver pattern that
+ * `llm-factory` uses for LLMs (so DBAutoDoc stays coupled to MJ's AI stack rather
+ * than talking to provider REST endpoints directly). The concrete driver class is
+ * resolved from the provider name and instantiated with the supplied API key.
+ *
+ * Vectors are unit-normalized so the clustering step can use cosine distance
+ * directly regardless of whether the underlying model returns normalized output.
+ */
+import { BaseEmbeddings } from '@memberjunction/ai';
+import { MJGlobal } from '@memberjunction/global';
+/** Provider name → registered MJ embedding driver class (see `@RegisterClass(BaseEmbeddings, ...)`). */
+const PROVIDER_TO_DRIVER_CLASS = {
+    openai: 'OpenAIEmbedding',
+    mistral: 'MistralEmbedding',
+    azure: 'AzureEmbedding',
+    bedrock: 'BedrockEmbedding',
+    ollama: 'OllamaEmbedding',
+    local: 'LocalEmbedding',
+};
+/**
+ * Sensible default embedding model per provider when the config doesn't specify one.
+ * `local` uses a small HuggingFace sentence-transformer (downloaded on first use) so
+ * organic-key clustering can run with no API key. `azure`/`bedrock` are intentionally
+ * absent — their models are deployment-specific and must be set explicitly.
+ */
+const PROVIDER_DEFAULT_MODEL = {
+    openai: 'text-embedding-3-small',
+    mistral: 'mistral-embed',
+    local: 'Xenova/all-MiniLM-L6-v2',
+    ollama: 'nomic-embed-text',
+};
+export function createEmbeddingProvider(config) {
+    const driverClass = PROVIDER_TO_DRIVER_CLASS[config.provider];
+    if (!driverClass) {
+        const supported = Object.keys(PROVIDER_TO_DRIVER_CLASS).join(', ');
+        throw new Error(`Embedding provider not supported: ${config.provider}. Supported: ${supported}`);
+    }
+    return new MJEmbeddingProvider(config, driverClass);
+}
+/** Wraps a registered `BaseEmbeddings` driver behind the simple `embed(texts)` contract. */
+class MJEmbeddingProvider {
+    constructor(config, driverClass) {
+        this.provider = config.provider;
+        this.model = config.model || PROVIDER_DEFAULT_MODEL[config.provider] || '';
+        this.batchSize = config.batchSize ?? 100;
+        const instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseEmbeddings, driverClass, config.apiKey);
+        if (!instance) {
+            throw new Error(`Failed to create embedding instance for provider '${config.provider}' (driver class: ${driverClass}). ` +
+                `Check that the provider package is installed and registered via server-bootstrap.`);
+        }
+        this.embeddings = instance;
+    }
+    async embed(texts) {
+        const out = new Array(texts.length);
+        for (let i = 0; i < texts.length; i += this.batchSize) {
+            const batch = texts.slice(i, i + this.batchSize);
+            const vectors = await this.embedBatch(batch);
+            for (let j = 0; j < vectors.length; j++)
+                out[i + j] = vectors[j];
+        }
+        return out;
+    }
+    async embedBatch(texts) {
+        const result = await this.embeddings.EmbedTexts({ texts, model: this.model });
+        const vectors = result?.vectors;
+        if (!vectors || vectors.length !== texts.length) {
+            throw new Error(`Embedding driver returned ${vectors?.length ?? 0} vectors for ${texts.length} inputs (provider: ${this.provider}).`);
+        }
+        return vectors.map((v) => normalizeVec(Float32Array.from(v)));
+    }
+}
+/** Unit-normalize a vector in place so the clustering step can use cosine distance. */
+function normalizeVec(v) {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++)
+        sum += v[i] * v[i];
+    const norm = Math.sqrt(sum);
+    if (norm === 0)
+        return v;
+    for (let i = 0; i < v.length; i++)
+        v[i] = v[i] / norm;
+    return v;
+}
+//# sourceMappingURL=EmbeddingProvider.js.map

package/dist/discovery/EmbeddingProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddingProvider.js","sourceRoot":"","sources":["../../src/discovery/EmbeddingProvider.ts"],"names":[],"mappings":"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"}

package/dist/discovery/FKGraphWalker.d.ts

@@ -0,0 +1,108 @@
+/**
+ * FKGraphWalker — Pattern 3 graph traversal.
+ *
+ * Given the foreign-key relationships of a database (hard declared + DBAutoDoc-
+ * discovered soft FKs), build an undirected join graph and find all paths of
+ * length ≤ maxHops from each "spoke" table to each "hub" table carrying an
+ * organic key. A path of length 2-3 means the spoke can reach the hub through
+ * intermediate tables — that's a transitive bridge candidate.
+ *
+ * Why a graph, not just FK chains:
+ *   Many natural bridges traverse FKs in both directions. Example:
+ *     Subscriber ←─ CampaignSend           (CampaignSend.SubscriberID → Subscriber.ID)
+ *     Contact (hub) — Email column
+ *   To reach CampaignSend from Contact via "email", the path goes:
+ *     Contact.Email ↔ Subscriber.Email (organic key match)
+ *     Subscriber.ID ← CampaignSend.SubscriberID (FK navigation, reverse direction)
+ *
+ *   The FK arrow points CampaignSend → Subscriber, but the bridge traversal
+ *   goes Subscriber → CampaignSend. Modeling the graph as undirected handles
+ *   this naturally; the edge metadata still tells us which side is the FK
+ *   source vs target.
+ *
+ * Output: structural paths the BridgeViewSQLGenerator turns into CREATE VIEW
+ * SQL conformant with PR #2193's TransitiveView contract.
+ */
+/** One foreign-key relationship between two tables. */
+export interface FKEdge {
+    sourceSchema: string;
+    sourceTable: string;
+    sourceColumn: string;
+    targetSchema: string;
+    targetTable: string;
+    targetColumn: string;
+    /** Hard (declared) vs soft (DBAutoDoc-detected). Affects ranking only. */
+    kind: 'hard' | 'soft';
+    /** Soft-FK confidence (0-1). Hard FKs are always 1. */
+    confidence: number;
+}
+/** A discovered transitive path from spoke to hub. */
+export interface BridgePath {
+    /** The table reachable through the chain (the "spoke" in organic-key terms). */
+    spokeSchema: string;
+    spokeTable: string;
+    /** The table carrying the organic key (the "hub"). */
+    hubSchema: string;
+    hubTable: string;
+    /** Field name on the hub being projected (the organic-key match field). */
+    hubKeyField: string;
+    /**
+     * Ordered list of join hops. hops[0].fromTable === spokeTable;
+     * hops[last].toTable === hubTable. For a length-2 path:
+     *   hops = [ { fromTable: spoke, toTable: intermediate, ... },
+     *            { fromTable: intermediate, toTable: hub, ... } ]
+     */
+    hops: BridgeHop[];
+    /** Total path length (number of FK joins). */
+    pathLength: number;
+    /**
+     * Path confidence = product of edge confidences. Hard-only paths = 1.
+     * Soft FKs on the path drag the confidence down (1 × 0.85 = 0.85).
+     */
+    pathConfidence: number;
+}
+/** One join hop in a bridge path. */
+export interface BridgeHop {
+    fromSchema: string;
+    fromTable: string;
+    fromColumn: string;
+    toSchema: string;
+    toTable: string;
+    toColumn: string;
+    /** Edge kind for ranking; same as FKEdge.kind. */
+    kind: 'hard' | 'soft';
+}
+export interface FKGraphWalkerOptions {
+    /** Maximum path length to explore. PR #2193 examples cap at 3. Default 3. */
+    maxHops?: number;
+    /**
+     * Minimum confidence threshold for soft FKs to be included in the graph.
+     * Hard FKs are always included. Default 0.6.
+     */
+    minSoftFKConfidence?: number;
+    /**
+     * When true, paths through the same table twice are pruned (no cycles).
+     * Default true.
+     */
+    pruneCycles?: boolean;
+}
+/**
+ * Build the join graph and find all bridge paths from each spoke candidate to
+ * each hub candidate.
+ *
+ * @param edges - all FK relationships in the database (hard + soft).
+ * @param hubs  - tables that carry an organic key (output of Pattern 1/2). Each
+ *                entry names the hub's match field — this becomes the projected
+ *                column in the bridge view.
+ * @param spokes - tables to attempt to reach from each hub. Typically every
+ *                 table in the database except the hub itself.
+ */
+export declare function findBridgePaths(edges: FKEdge[], hubs: Array<{
+    schema: string;
+    table: string;
+    keyField: string;
+}>, spokes: Array<{
+    schema: string;
+    table: string;
+}>, opts?: FKGraphWalkerOptions): BridgePath[];
+//# sourceMappingURL=FKGraphWalker.d.ts.map

package/dist/discovery/FKGraphWalker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FKGraphWalker.d.ts","sourceRoot":"","sources":["../../src/discovery/FKGraphWalker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,uDAAuD;AACvD,MAAM,WAAW,MAAM;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,sDAAsD;AACtD,MAAM,WAAW,UAAU;IACvB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,qCAAqC;AACrC,MAAM,WAAW,SAAS;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACjC,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC3B,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,EAAE,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,EAChE,MAAM,EAAE,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EAChD,IAAI,GAAE,oBAAyB,GAChC,UAAU,EAAE,CA2Bd"}

package/dist/discovery/FKGraphWalker.js

@@ -0,0 +1,169 @@
+/**
+ * FKGraphWalker — Pattern 3 graph traversal.
+ *
+ * Given the foreign-key relationships of a database (hard declared + DBAutoDoc-
+ * discovered soft FKs), build an undirected join graph and find all paths of
+ * length ≤ maxHops from each "spoke" table to each "hub" table carrying an
+ * organic key. A path of length 2-3 means the spoke can reach the hub through
+ * intermediate tables — that's a transitive bridge candidate.
+ *
+ * Why a graph, not just FK chains:
+ *   Many natural bridges traverse FKs in both directions. Example:
+ *     Subscriber ←─ CampaignSend           (CampaignSend.SubscriberID → Subscriber.ID)
+ *     Contact (hub) — Email column
+ *   To reach CampaignSend from Contact via "email", the path goes:
+ *     Contact.Email ↔ Subscriber.Email (organic key match)
+ *     Subscriber.ID ← CampaignSend.SubscriberID (FK navigation, reverse direction)
+ *
+ *   The FK arrow points CampaignSend → Subscriber, but the bridge traversal
+ *   goes Subscriber → CampaignSend. Modeling the graph as undirected handles
+ *   this naturally; the edge metadata still tells us which side is the FK
+ *   source vs target.
+ *
+ * Output: structural paths the BridgeViewSQLGenerator turns into CREATE VIEW
+ * SQL conformant with PR #2193's TransitiveView contract.
+ */
+const DEFAULTS = {
+    maxHops: 3,
+    minSoftFKConfidence: 0.6,
+    pruneCycles: true,
+};
+/**
+ * Build the join graph and find all bridge paths from each spoke candidate to
+ * each hub candidate.
+ *
+ * @param edges - all FK relationships in the database (hard + soft).
+ * @param hubs  - tables that carry an organic key (output of Pattern 1/2). Each
+ *                entry names the hub's match field — this becomes the projected
+ *                column in the bridge view.
+ * @param spokes - tables to attempt to reach from each hub. Typically every
+ *                 table in the database except the hub itself.
+ */
+export function findBridgePaths(edges, hubs, spokes, opts = {}) {
+    const o = { ...DEFAULTS, ...opts };
+    // Build the adjacency map keyed by "schema.table".
+    const adjacency = buildAdjacency(edges, o.minSoftFKConfidence);
+    const out = [];
+    for (const hub of hubs) {
+        const hubKey = `${hub.schema}.${hub.table}`;
+        for (const spoke of spokes) {
+            const spokeKey = `${spoke.schema}.${spoke.table}`;
+            if (spokeKey === hubKey)
+                continue;
+            // BFS from spoke → hub.
+            const paths = bfsPaths(adjacency, spokeKey, hubKey, o.maxHops, o.pruneCycles);
+            for (const p of paths) {
+                if (p.length === 0)
+                    continue; // self
+                if (p.length === 1)
+                    continue; // direct FK already handled by existing relationship system
+                out.push(materializeBridgePath(p, hub, spoke));
+            }
+        }
+    }
+    // Sort: shortest paths first, then highest confidence.
+    out.sort((a, b) => {
+        if (a.pathLength !== b.pathLength)
+            return a.pathLength - b.pathLength;
+        return b.pathConfidence - a.pathConfidence;
+    });
+    return out;
+}
+function buildAdjacency(edges, minSoftFKConfidence) {
+    const out = new Map();
+    for (const e of edges) {
+        if (e.kind === 'soft' && e.confidence < minSoftFKConfidence)
+            continue;
+        const aKey = `${e.sourceSchema}.${e.sourceTable}`;
+        const bKey = `${e.targetSchema}.${e.targetTable}`;
+        const forward = {
+            fromKey: aKey,
+            toKey: bKey,
+            fkSourceKey: aKey,
+            fkSourceColumn: e.sourceColumn,
+            fkTargetColumn: e.targetColumn,
+            kind: e.kind,
+            confidence: e.confidence,
+        };
+        const reverse = {
+            fromKey: bKey,
+            toKey: aKey,
+            fkSourceKey: aKey,
+            fkSourceColumn: e.sourceColumn,
+            fkTargetColumn: e.targetColumn,
+            kind: e.kind,
+            confidence: e.confidence,
+        };
+        push(out, aKey, forward);
+        push(out, bKey, reverse);
+    }
+    return out;
+}
+function push(map, key, value) {
+    const list = map.get(key);
+    if (list)
+        list.push(value);
+    else
+        map.set(key, [value]);
+}
+// ─── BFS ────────────────────────────────────────────────────────────────────
+/** Path of adjacency edges from `start` to `goal`. Returns empty if none found. */
+function bfsPaths(adjacency, start, goal, maxHops, pruneCycles) {
+    if (start === goal)
+        return [[]];
+    const queue = [
+        { node: start, pathEdges: [], visited: new Set([start]) },
+    ];
+    const found = [];
+    while (queue.length > 0) {
+        const { node, pathEdges, visited } = queue.shift();
+        if (pathEdges.length >= maxHops)
+            continue;
+        const neighbors = adjacency.get(node) ?? [];
+        for (const edge of neighbors) {
+            const nextNode = edge.toKey;
+            if (pruneCycles && visited.has(nextNode))
+                continue;
+            const newPath = [...pathEdges, edge];
+            if (nextNode === goal) {
+                found.push(newPath);
+                continue; // don't extend past the goal
+            }
+            const nextVisited = new Set(visited);
+            nextVisited.add(nextNode);
+            queue.push({ node: nextNode, pathEdges: newPath, visited: nextVisited });
+        }
+    }
+    return found;
+}
+// ─── Bridge path materialization ────────────────────────────────────────────
+function materializeBridgePath(edgePath, hub, spoke) {
+    const hops = edgePath.map((e) => {
+        const [fromSchema, fromTable] = e.fromKey.split('.');
+        const [toSchema, toTable] = e.toKey.split('.');
+        // The column on the "from" side is the FK-source column if from is the FK source;
+        // otherwise it's the FK-target column.
+        const fromIsFKSource = e.fromKey === e.fkSourceKey;
+        return {
+            fromSchema,
+            fromTable,
+            fromColumn: fromIsFKSource ? e.fkSourceColumn : e.fkTargetColumn,
+            toSchema,
+            toTable,
+            toColumn: fromIsFKSource ? e.fkTargetColumn : e.fkSourceColumn,
+            kind: e.kind,
+        };
+    });
+    const pathConfidence = edgePath.reduce((acc, e) => acc * e.confidence, 1);
+    return {
+        spokeSchema: spoke.schema,
+        spokeTable: spoke.table,
+        hubSchema: hub.schema,
+        hubTable: hub.table,
+        hubKeyField: hub.keyField,
+        hops,
+        pathLength: edgePath.length,
+        pathConfidence,
+    };
+}
+//# sourceMappingURL=FKGraphWalker.js.map

package/dist/discovery/FKGraphWalker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FKGraphWalker.js","sourceRoot":"","sources":["../../src/discovery/FKGraphWalker.ts"],"names":[],"mappings":"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"}

package/dist/discovery/OrganicKeyDetector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OrganicKeyDetector — the thin orchestrator.
+ *
+ *   1. SemanticPhase    LLM identifies organic-key concept per column,
+ *                       groups columns by canonical concept name into clusters
+ *                       spanning ≥2 distinct tables.
+ *
+ *   2. StructuralPhase  Walks the FK graph from each cluster's hubs to find
+ *                       reachable tables 2-3 hops away → bridge view SQL.
+ *
+ *   3. Composer         Drops fk-redundant clusters (already navigable via
+ *                       declared FK per PR #2193), attaches matching bridges,
+ *                       emits PR #2193 JSON.
+ *
+ * No knobs. The LLM is the algorithm; the graph is deterministic; the filter
+ * is the one PR #2193 explicitly defines.
+ */
+import { AIConfig, OrganicKeyDetectionConfig } from '../types/config.js';
+import { DatabaseDocumentation } from '../types/state.js';
+import { OrganicKeyCluster, OrganicKeyDetectionPhase } from '../types/organic-keys.js';
+import { ProgressCallback } from './SemanticPhase.js';
+import { DetectedOrganicKeysOutput } from './OrganicKeyTranslator.js';
+export interface OrganicKeyDetectionResult {
+    clusters: OrganicKeyCluster[];
+    output: DetectedOrganicKeysOutput;
+    phase: OrganicKeyDetectionPhase;
+    summary: {
+        columnsInScope: number;
+        columnsNormalized: number;
+        columnsRejectedByNormalizer: number;
+        clustersFound: number;
+        clustersEmitted: number;
+        clustersDropped: number;
+        outputSchemas: number;
+        outputTables: number;
+        outputKeys: number;
+        outputSpokes: number;
+        transitiveBridges: number;
+    };
+}
+export interface DetectorRunOptions {
+    onProgress?: ProgressCallback;
+}
+export declare class OrganicKeyDetector {
+    private readonly config;
+    private readonly aiConfig;
+    constructor(config: OrganicKeyDetectionConfig, aiConfig: AIConfig);
+    detect(state: DatabaseDocumentation, opts?: DetectorRunOptions): Promise<OrganicKeyDetectionResult>;
+    private estimateCost;
+}
+//# sourceMappingURL=OrganicKeyDetector.d.ts.map

package/dist/discovery/OrganicKeyDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OrganicKeyDetector.d.ts","sourceRoot":"","sources":["../../src/discovery/OrganicKeyDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAoB,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGxE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,MAAM,WAAW,yBAAyB;IACtC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,MAAM,EAAE,yBAAyB,CAAC;IAClC,KAAK,EAAE,wBAAwB,CAAC;IAChC,OAAO,EAAE;QACL,cAAc,EAAE,MAAM,CAAC;QACvB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,2BAA2B,EAAE,MAAM,CAAC;QACpC,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;QACxB,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;KAC7B,CAAC;CACL;AAED,MAAM,WAAW,kBAAkB;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAED,qBAAa,kBAAkB;IAEvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,MAAM,EAAE,yBAAyB,EACjC,QAAQ,EAAE,QAAQ;IAG1B,MAAM,CACf,KAAK,EAAE,qBAAqB,EAC5B,IAAI,GAAE,kBAAuB,GAC9B,OAAO,CAAC,yBAAyB,CAAC;IAmDrC,OAAO,CAAC,YAAY;CAMvB"}

package/dist/discovery/OrganicKeyDetector.js

@@ -0,0 +1,78 @@
+/**
+ * OrganicKeyDetector — the thin orchestrator.
+ *
+ *   1. SemanticPhase    LLM identifies organic-key concept per column,
+ *                       groups columns by canonical concept name into clusters
+ *                       spanning ≥2 distinct tables.
+ *
+ *   2. StructuralPhase  Walks the FK graph from each cluster's hubs to find
+ *                       reachable tables 2-3 hops away → bridge view SQL.
+ *
+ *   3. Composer         Drops fk-redundant clusters (already navigable via
+ *                       declared FK per PR #2193), attaches matching bridges,
+ *                       emits PR #2193 JSON.
+ *
+ * No knobs. The LLM is the algorithm; the graph is deterministic; the filter
+ * is the one PR #2193 explicitly defines.
+ */
+import { runSemanticPhase } from './SemanticPhase.js';
+import { runStructuralPhase } from './StructuralPhase.js';
+import { compose } from './Composer.js';
+export class OrganicKeyDetector {
+    constructor(config, aiConfig) {
+        this.config = config;
+        this.aiConfig = aiConfig;
+    }
+    async detect(state, opts = {}) {
+        const progress = opts.onProgress ?? (() => { });
+        const startedAt = new Date().toISOString();
+        const a = await runSemanticPhase(state, this.config, this.aiConfig, progress);
+        const b = runStructuralPhase(state, a.clusters);
+        progress(`structural: ${b.summary.transitiveBridgesFound} bridges`);
+        const c = compose(a.clusters, b.bridges);
+        progress(`compose: emitted ${c.emitted}/${a.clusters.length} clusters (${c.summary.outputKeys} keys, ${c.summary.outputSpokes} spokes)`);
+        // Net additional clusters produced by the concept-name split (sub-clusters created
+        // beyond the raw clusterer output, counting both kept and dropped sub-clusters).
+        const splitClusterCount = Math.max(0, a.summary.clustersFound + a.summary.clustersDropped - a.summary.clustersBeforeSplit);
+        return {
+            clusters: c.annotatedClusters,
+            output: c.output,
+            phase: {
+                triggered: true,
+                startedAt,
+                completedAt: new Date().toISOString(),
+                status: 'completed',
+                candidateClusterCount: a.clusters.length,
+                confirmedClusterCount: c.emitted,
+                rejectedClusterCount: a.summary.columnsRejectedByNormalizer,
+                splitClusterCount,
+                tokensUsed: a.tokens.total,
+                inputTokens: a.tokens.input,
+                outputTokens: a.tokens.output,
+                estimatedCost: this.estimateCost(a.tokens.input, a.tokens.output),
+                refinementModelUsed: this.aiConfig.model,
+            },
+            summary: {
+                columnsInScope: a.summary.columnsInScope,
+                columnsNormalized: a.summary.columnsNormalized,
+                columnsRejectedByNormalizer: a.summary.columnsRejectedByNormalizer,
+                clustersFound: a.clusters.length,
+                clustersEmitted: c.emitted,
+                clustersDropped: a.summary.clustersDropped,
+                outputSchemas: c.summary.outputSchemas,
+                outputTables: c.summary.outputTables,
+                outputKeys: c.summary.outputKeys,
+                outputSpokes: c.summary.outputSpokes,
+                transitiveBridges: b.summary.transitiveBridgesFound,
+            },
+        };
+    }
+    estimateCost(inputTokens, outputTokens) {
+        const pricing = this.aiConfig.pricing;
+        if (!pricing)
+            return 0;
+        return (inputTokens / 1_000_000) * (pricing.inputCostPer1MTokens ?? 0)
+            + (outputTokens / 1_000_000) * (pricing.outputCostPer1MTokens ?? 0);
+    }
+}
+//# sourceMappingURL=OrganicKeyDetector.js.map

package/dist/discovery/OrganicKeyDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OrganicKeyDetector.js","sourceRoot":"","sources":["../../src/discovery/OrganicKeyDetector.ts"],"names":[],"mappings":"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"}

package/dist/discovery/OrganicKeyTranslator.d.ts

@@ -0,0 +1,78 @@
+/**
+ * OrganicKeyTranslator — PURE EMISSION.
+ *
+ * Takes a list of clusters that have ALREADY been gated by the Composer, plus
+ * the transitive spokes for those that survived, and fans them out into PR
+ * #2193's per-schema/per-table JSON.
+ *
+ * No filtering, no thresholds, no scoring logic in here. The Composer is the
+ * single emission gate; this file is its render-to-JSON helper.
+ *
+ * Same-concept consolidation: clusters that the LLM normalizer assigned the
+ * same canonical concept name (e.g. four separate geometric clusters all
+ * named `product_id`) are MERGED here into a single conceptual cluster before
+ * fan-out — deterministic equivalent of an LLM concept-merge pass.
+ */
+import { OrganicKeyCluster, OrganicKeyNormalizationStrategy } from '../types/organic-keys.js';
+/** A generated SQL bridge view backing a transitive (multi-hop) spoke. */
+export interface TransitiveViewConfig {
+    Name: string;
+    SchemaName?: string;
+    SQL: string;
+}
+/** One related entity (spoke) reachable from an organic key — either a direct field match or a transitive (bridge-view) match. */
+export interface OrganicKeyRelatedEntityConfig {
+    SchemaName: string;
+    TableName: string;
+    RelatedFieldNames?: string[];
+    TransitiveView?: TransitiveViewConfig;
+    TransitiveMatchFieldNames?: string[];
+    TransitiveOutputFieldName?: string;
+    RelatedEntityJoinFieldName?: string;
+    DisplayName?: string;
+}
+/** A single organic key anchored on one table's column(s), with its own normalization and its spokes. */
+export interface OrganicKeyConfig {
+    Name: string;
+    Description?: string;
+    MatchFieldNames: string[];
+    NormalizationStrategy: OrganicKeyNormalizationStrategy;
+    CustomNormalizationExpression?: string;
+    AutoCreateRelatedViewOnForm?: boolean;
+    RelatedEntities: OrganicKeyRelatedEntityConfig[];
+}
+/** All organic keys anchored on a given table. */
+export interface TableOrganicKeyConfig {
+    TableName: string;
+    OrganicKeys: OrganicKeyConfig[];
+}
+/** The full emit payload: schema name → its tables' organic-key configs. */
+export type DetectedOrganicKeysOutput = Record<string, TableOrganicKeyConfig[]>;
+export interface TransitiveSpokeInput {
+    hubSchema: string;
+    hubTable: string;
+    hubKeyFields: string[];
+    spokeSchema: string;
+    spokeTable: string;
+    transitiveView: TransitiveViewConfig;
+    transitiveMatchFieldNames: string[];
+    transitiveOutputFieldName: string;
+    relatedEntityJoinFieldName: string;
+    hubConcept?: string;
+}
+/**
+ * Render gated clusters into PR #2193 JSON. Same-concept consolidation +
+ * per-table fan-out + transitive spoke attachment. No filters, no thresholds.
+ *
+ * The caller (Composer) is responsible for filtering. Anything passed in
+ * gets emitted.
+ */
+export declare function translateClusters(clusters: OrganicKeyCluster[], transitiveSpokes?: TransitiveSpokeInput[]): DetectedOrganicKeysOutput;
+/** Tally the emit payload: number of schemas, tables, organic keys, and spokes it contains. */
+export declare function countOutputEntries(out: DetectedOrganicKeysOutput): {
+    schemas: number;
+    tables: number;
+    keys: number;
+    spokes: number;
+};
+//# sourceMappingURL=OrganicKeyTranslator.d.ts.map

package/dist/discovery/OrganicKeyTranslator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OrganicKeyTranslator.d.ts","sourceRoot":"","sources":["../../src/discovery/OrganicKeyTranslator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACH,iBAAiB,EAEjB,+BAA+B,EAGlC,MAAM,0BAA0B,CAAC;AAOlC,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;CACf;AAED,kIAAkI;AAClI,MAAM,WAAW,6BAA6B;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;IACrC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,yGAAyG;AACzG,MAAM,WAAW,gBAAgB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,qBAAqB,EAAE,+BAA+B,CAAC;IACvD,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,eAAe,EAAE,6BAA6B,EAAE,CAAC;CACpD;AAED,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,gBAAgB,EAAE,CAAC;CACnC;AAED,4EAA4E;AAC5E,MAAM,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,EAAE,qBAAqB,EAAE,CAAC,CAAC;AAIhF,MAAM,WAAW,oBAAoB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,oBAAoB,CAAC;IACrC,yBAAyB,EAAE,MAAM,EAAE,CAAC;IACpC,yBAAyB,EAAE,MAAM,CAAC;IAClC,0BAA0B,EAAE,MAAM,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC7B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,gBAAgB,GAAE,oBAAoB,EAAO,GAC9C,yBAAyB,CAmG3B;AAwCD,+FAA+F;AAC/F,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,yBAAyB,GAAG;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAClB,CAaA"}