coalesce-transform-mcp 0.1.0

package/dist/services/corpus/loader.d.ts

@@ -0,0 +1,56 @@
+export type NodeTypeCorpusSupportStatus = "supported" | "partial" | "parse_error";
+export type NodeTypeCorpusOccurrence = {
+    packageName: string;
+    nodeTypeDirName: string;
+    nodeTypeDirPath: string;
+    definitionPath: string;
+    createPath: string;
+    runPath: string;
+};
+export type NodeTypeCorpusDefinitionSummary = {
+    capitalized: string | null;
+    short: string | null;
+    plural: string | null;
+    tagColor: string | null;
+    deployStrategy: string | null;
+    configGroupCount: number;
+    configItemCount: number;
+};
+export type NodeTypeCorpusVariant = {
+    variantKey: string;
+    normalizedFamily: string;
+    packageNames: string[];
+    occurrenceCount: number;
+    occurrences: NodeTypeCorpusOccurrence[];
+    definitionHash: string;
+    createHash: string;
+    runHash: string;
+    primitiveSignature: string[];
+    controlSignature: string[];
+    unsupportedPrimitives: string[];
+    supportStatus: NodeTypeCorpusSupportStatus;
+    definitionSummary: NodeTypeCorpusDefinitionSummary;
+    outerDefinition: {
+        fileVersion: unknown;
+        id: string | null;
+        isDisabled: boolean | null;
+        name: string | null;
+        type: string | null;
+    };
+    nodeMetadataSpec: string;
+    nodeDefinition: Record<string, unknown> | null;
+    parseError: string | null;
+};
+export type NodeTypeCorpusSnapshot = {
+    generatedAt: string;
+    sourceRoot: string;
+    packageCount: number;
+    definitionCount: number;
+    uniqueVariantCount: number;
+    uniqueNormalizedFamilyCount: number;
+    supportedVariantCount: number;
+    partialVariantCount: number;
+    parseErrorVariantCount: number;
+    variants: NodeTypeCorpusVariant[];
+};
+export declare function loadNodeTypeCorpusSnapshot(): NodeTypeCorpusSnapshot;

package/dist/services/corpus/loader.js

@@ -0,0 +1,25 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { isPlainObject } from "../../utils.js";
+let cachedSnapshot = null;
+function getSnapshotPath() {
+    return fileURLToPath(new URL("../../generated/node-type-corpus.json", import.meta.url));
+}
+export function loadNodeTypeCorpusSnapshot() {
+    if (cachedSnapshot) {
+        return cachedSnapshot;
+    }
+    const filePath = getSnapshotPath();
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch {
+        throw new Error(`Node type corpus snapshot not found or unreadable at ${filePath}. Run npm run import:node-type-corpus before building.`);
+    }
+    if (!isPlainObject(parsed) || !Array.isArray(parsed.variants)) {
+        throw new Error(`Node type corpus snapshot is invalid at ${filePath}.`);
+    }
+    cachedSnapshot = parsed;
+    return cachedSnapshot;
+}

package/dist/services/corpus/search.d.ts

@@ -0,0 +1,49 @@
+import type { NodeTypeCorpusSnapshot, NodeTypeCorpusVariant, NodeTypeCorpusSupportStatus } from "./loader.js";
+export declare function summarizeNodeTypeCorpus(snapshot: NodeTypeCorpusSnapshot): {
+    generatedAt: string;
+    sourceRoot: string;
+    packageCount: number;
+    definitionCount: number;
+    uniqueVariantCount: number;
+    uniqueNormalizedFamilyCount: number;
+    supportedVariantCount: number;
+    partialVariantCount: number;
+    parseErrorVariantCount: number;
+    topFamilies: {
+        normalizedFamily: string;
+        variantCount: number;
+    }[];
+};
+export declare function buildVariantSummary(variant: NodeTypeCorpusVariant): {
+    variantKey: string;
+    normalizedFamily: string;
+    packageNames: string[];
+    occurrenceCount: number;
+    supportStatus: NodeTypeCorpusSupportStatus;
+    unsupportedPrimitives: string[];
+    primitiveSignature: string[];
+    controlSignature: string[];
+    definitionSummary: import("./loader.js").NodeTypeCorpusDefinitionSummary;
+};
+export declare function searchNodeTypeCorpusVariants(snapshot: NodeTypeCorpusSnapshot, params: {
+    normalizedFamily?: string;
+    packageName?: string;
+    primitive?: string;
+    supportStatus?: NodeTypeCorpusSupportStatus;
+    limit?: number;
+}): {
+    matchedCount: number;
+    returnedCount: number;
+    matches: {
+        variantKey: string;
+        normalizedFamily: string;
+        packageNames: string[];
+        occurrenceCount: number;
+        supportStatus: NodeTypeCorpusSupportStatus;
+        unsupportedPrimitives: string[];
+        primitiveSignature: string[];
+        controlSignature: string[];
+        definitionSummary: import("./loader.js").NodeTypeCorpusDefinitionSummary;
+    }[];
+};
+export declare function getNodeTypeCorpusVariant(snapshot: NodeTypeCorpusSnapshot, variantKey: string): NodeTypeCorpusVariant;

package/dist/services/corpus/search.js

@@ -0,0 +1,69 @@
+import { filterSqlOverrideControls } from "../policies/sql-override.js";
+export function summarizeNodeTypeCorpus(snapshot) {
+    const familyCounts = new Map();
+    for (const variant of snapshot.variants) {
+        familyCounts.set(variant.normalizedFamily, (familyCounts.get(variant.normalizedFamily) ?? 0) + 1);
+    }
+    const topFamilies = Array.from(familyCounts.entries())
+        .sort((left, right) => right[1] === left[1]
+        ? left[0].localeCompare(right[0])
+        : right[1] - left[1])
+        .slice(0, 20)
+        .map(([normalizedFamily, variantCount]) => ({
+        normalizedFamily,
+        variantCount,
+    }));
+    return {
+        generatedAt: snapshot.generatedAt,
+        sourceRoot: snapshot.sourceRoot,
+        packageCount: snapshot.packageCount,
+        definitionCount: snapshot.definitionCount,
+        uniqueVariantCount: snapshot.uniqueVariantCount,
+        uniqueNormalizedFamilyCount: snapshot.uniqueNormalizedFamilyCount,
+        supportedVariantCount: snapshot.supportedVariantCount,
+        partialVariantCount: snapshot.partialVariantCount,
+        parseErrorVariantCount: snapshot.parseErrorVariantCount,
+        topFamilies,
+    };
+}
+export function buildVariantSummary(variant) {
+    return {
+        variantKey: variant.variantKey,
+        normalizedFamily: variant.normalizedFamily,
+        packageNames: variant.packageNames,
+        occurrenceCount: variant.occurrenceCount,
+        supportStatus: variant.supportStatus,
+        unsupportedPrimitives: filterSqlOverrideControls(variant.unsupportedPrimitives),
+        primitiveSignature: filterSqlOverrideControls(variant.primitiveSignature),
+        controlSignature: filterSqlOverrideControls(variant.controlSignature),
+        definitionSummary: variant.definitionSummary,
+    };
+}
+export function searchNodeTypeCorpusVariants(snapshot, params) {
+    const limit = Math.max(1, Math.min(params.limit ?? 25, 200));
+    const normalizedFamilyFilter = params.normalizedFamily?.trim().toLowerCase();
+    const packageNameFilter = params.packageName?.trim().toLowerCase();
+    const primitiveFilter = params.primitive?.trim().toLowerCase();
+    const matches = snapshot.variants.filter((variant) => {
+        const familyMatches = !normalizedFamilyFilter ||
+            variant.normalizedFamily.toLowerCase() === normalizedFamilyFilter;
+        const packageMatches = !packageNameFilter ||
+            variant.packageNames.some((packageName) => packageName.toLowerCase() === packageNameFilter);
+        const primitiveMatches = !primitiveFilter ||
+            variant.primitiveSignature.some((primitive) => primitive.toLowerCase() === primitiveFilter);
+        const supportMatches = !params.supportStatus || variant.supportStatus === params.supportStatus;
+        return familyMatches && packageMatches && primitiveMatches && supportMatches;
+    });
+    return {
+        matchedCount: matches.length,
+        returnedCount: Math.min(matches.length, limit),
+        matches: matches.slice(0, limit).map(buildVariantSummary),
+    };
+}
+export function getNodeTypeCorpusVariant(snapshot, variantKey) {
+    const variant = snapshot.variants.find((entry) => entry.variantKey === variantKey);
+    if (!variant) {
+        throw new Error(`No node type corpus variant found for variantKey ${variantKey}.`);
+    }
+    return variant;
+}

package/dist/services/corpus/templates.d.ts

@@ -0,0 +1,4 @@
+import type { NodeTypeCorpusVariant } from "./loader.js";
+export declare function validateVariantTemplateGeneration(variant: NodeTypeCorpusVariant, options?: {
+    allowPartial?: boolean;
+}): void;

package/dist/services/corpus/templates.js

@@ -0,0 +1,11 @@
+export function validateVariantTemplateGeneration(variant, options = {}) {
+    if (!variant.nodeDefinition) {
+        throw new Error(`Variant ${variant.variantKey} cannot generate a workspace template because its embedded nodeMetadataSpec could not be parsed. Parse error: ${variant.parseError ?? "unknown"}`);
+    }
+    if (variant.supportStatus === "partial" && !options.allowPartial) {
+        const unsupported = variant.unsupportedPrimitives.length > 0
+            ? variant.unsupportedPrimitives.join(", ")
+            : "unknown unsupported controls";
+        throw new Error(`Variant ${variant.variantKey} is only partially supported because it uses unsupported primitives: ${unsupported}. Pass allowPartial=true to generate a best-effort template.`);
+    }
+}

package/dist/services/pipelines/execution.d.ts

@@ -0,0 +1,20 @@
+import { type CoalesceClient } from "../../client.js";
+export declare function createPipelineFromPlan(client: CoalesceClient, params: {
+    workspaceID: string;
+    plan: Record<string, unknown>;
+    dryRun?: boolean;
+}): Promise<unknown>;
+export declare function createPipelineFromSql(client: CoalesceClient, params: {
+    workspaceID: string;
+    sql: string;
+    goal?: string;
+    targetName?: string;
+    targetNodeType?: string;
+    description?: string;
+    configOverrides?: Record<string, unknown>;
+    locationName?: string;
+    database?: string;
+    schema?: string;
+    repoPath?: string;
+    dryRun?: boolean;
+}): Promise<unknown>;

package/dist/services/pipelines/execution.js

@@ -0,0 +1,290 @@
+import { randomUUID } from "node:crypto";
+import { CoalesceApiError } from "../../client.js";
+import { validatePathSegment } from "../../coalesce/types.js";
+import { PipelinePlanSchema, planPipeline, DEFAULT_STAGE_CONFIG, deepClone, findMatchingBaseColumn, buildStageSourceMappingFromPlan, renameSourceMappingEntries, getColumnNamesFromNode, normalizeSqlIdentifier, normalizeWhitespace, getNodeColumnArray, getColumnSourceNodeIDs, } from "./planning.js";
+import { getWorkspaceNode, setWorkspaceNode, } from "../../coalesce/api/nodes.js";
+import { createWorkspaceNodeFromPredecessor, buildUpdatedWorkspaceNodeBody } from "../workspace/mutations.js";
+import { isPlainObject } from "../../utils.js";
+function isStageLikeNode(nodePlan) {
+    return (nodePlan.nodeTypeFamily === "stage" ||
+        nodePlan.nodeTypeFamily === "persistent-stage" ||
+        /(?:^|:::)(?:persistent)?Stage$/u.test(nodePlan.nodeType));
+}
+function buildNodeBodyFromPlan(currentNode, nodePlan) {
+    const updatedNode = deepClone(currentNode);
+    updatedNode.name = nodePlan.name;
+    if (nodePlan.description !== null) {
+        updatedNode.description = nodePlan.description;
+    }
+    if (Object.keys(nodePlan.location).length > 0) {
+        Object.assign(updatedNode, nodePlan.location);
+    }
+    const templateDefaults = isPlainObject(nodePlan.templateDefaults)
+        ? nodePlan.templateDefaults
+        : undefined;
+    const inferredTopLevelFields = templateDefaults && isPlainObject(templateDefaults.inferredTopLevelFields)
+        ? templateDefaults.inferredTopLevelFields
+        : {};
+    for (const [key, value] of Object.entries(inferredTopLevelFields)) {
+        if (updatedNode[key] === undefined) {
+            updatedNode[key] = deepClone(value);
+        }
+    }
+    updatedNode.config = {
+        ...(isStageLikeNode(nodePlan) ? DEFAULT_STAGE_CONFIG : {}),
+        ...(templateDefaults && isPlainObject(templateDefaults.inferredConfig)
+            ? deepClone(templateDefaults.inferredConfig)
+            : {}),
+        ...(isPlainObject(updatedNode.config) ? updatedNode.config : {}),
+        ...nodePlan.configOverrides,
+    };
+    const plannedColumns = [];
+    for (const selectItem of nodePlan.selectItems) {
+        const baseColumn = findMatchingBaseColumn(updatedNode, selectItem);
+        if (!baseColumn) {
+            throw new Error(`Could not map planned output column ${selectItem.outputName ?? selectItem.expression} onto the created predecessor-based node body.`);
+        }
+        baseColumn.name = selectItem.outputName ?? baseColumn.name;
+        if (isPlainObject(baseColumn.columnReference)) {
+            baseColumn.columnReference = {
+                ...baseColumn.columnReference,
+                columnCounter: randomUUID(),
+            };
+        }
+        if (typeof baseColumn.columnID === "string") {
+            baseColumn.columnID = randomUUID();
+        }
+        plannedColumns.push(baseColumn);
+    }
+    const currentMetadata = isPlainObject(updatedNode.metadata)
+        ? updatedNode.metadata
+        : {};
+    updatedNode.metadata = {
+        ...currentMetadata,
+        columns: plannedColumns,
+        sourceMapping: buildStageSourceMappingFromPlan(updatedNode, nodePlan),
+    };
+    return renameSourceMappingEntries(updatedNode, nodePlan.name);
+}
+function getSavedNodeColumnNames(node) {
+    return getColumnNamesFromNode(node);
+}
+function validateSavedNode(node, nodePlan) {
+    const savedColumnNames = getSavedNodeColumnNames(node);
+    const expectedColumnNames = nodePlan.outputColumnNames;
+    const normalizedSaved = savedColumnNames.map(normalizeSqlIdentifier);
+    const normalizedExpected = expectedColumnNames.map(normalizeSqlIdentifier);
+    const referencedPredecessorNodeIDs = new Set();
+    const metadata = isPlainObject(node.metadata) ? node.metadata : undefined;
+    const sourceMappingEntry = metadata && Array.isArray(metadata.sourceMapping)
+        ? metadata.sourceMapping.find(isPlainObject)
+        : undefined;
+    const savedDependencies = isPlainObject(sourceMappingEntry) && Array.isArray(sourceMappingEntry.dependencies)
+        ? sourceMappingEntry.dependencies
+            .filter(isPlainObject)
+            .flatMap((dependency) => typeof dependency.nodeName === "string" ? [dependency.nodeName] : [])
+        : [];
+    const savedJoinCondition = isPlainObject(sourceMappingEntry) &&
+        isPlainObject(sourceMappingEntry.join) &&
+        typeof sourceMappingEntry.join.joinCondition === "string"
+        ? normalizeWhitespace(sourceMappingEntry.join.joinCondition)
+        : "";
+    for (const column of getNodeColumnArray(node)) {
+        for (const nodeID of getColumnSourceNodeIDs(column)) {
+            referencedPredecessorNodeIDs.add(nodeID);
+        }
+    }
+    return {
+        nodeNameSatisfied: node.name === nodePlan.name,
+        expectedColumnCount: expectedColumnNames.length,
+        actualColumnCount: savedColumnNames.length,
+        outputColumnsSatisfied: normalizedExpected.length === normalizedSaved.length &&
+            normalizedExpected.every((name, index) => normalizedSaved[index] === name),
+        expectedColumnNames,
+        actualColumnNames: savedColumnNames,
+        sourceMappingDependenciesSatisfied: savedDependencies.length === nodePlan.sourceRefs.length &&
+            nodePlan.sourceRefs.every((ref) => savedDependencies.includes(ref.nodeName)),
+        expectedDependencyNodeNames: nodePlan.sourceRefs.map((ref) => ref.nodeName),
+        actualDependencyNodeNames: savedDependencies,
+        joinConditionSatisfied: (nodePlan.joinCondition === null && savedJoinCondition.length === 0) ||
+            savedJoinCondition === normalizeWhitespace(nodePlan.joinCondition ?? ""),
+        expectedJoinCondition: nodePlan.joinCondition,
+        actualJoinCondition: savedJoinCondition.length > 0 ? savedJoinCondition : null,
+        predecessorCoverageSatisfied: nodePlan.predecessorNodeIDs.every((nodeID) => referencedPredecessorNodeIDs.has(nodeID)),
+        predecessorNodeIDs: nodePlan.predecessorNodeIDs,
+        referencedPredecessorNodeIDs: Array.from(referencedPredecessorNodeIDs),
+    };
+}
+async function deleteWorkspaceNode(client, workspaceID, nodeID) {
+    await client.delete(`/api/v1/workspaces/${validatePathSegment(workspaceID, "workspaceID")}/nodes/${validatePathSegment(nodeID, "nodeID")}`);
+}
+function serializePipelineExecutionError(error) {
+    if (error instanceof CoalesceApiError) {
+        return {
+            message: error.message,
+            status: error.status,
+            ...(error.detail !== undefined ? { detail: error.detail } : {}),
+        };
+    }
+    if (error instanceof Error) {
+        return { message: error.message };
+    }
+    return { message: "Pipeline creation failed", detail: error };
+}
+async function rollbackCreatedPipelineNodes(client, workspaceID, nodeIDs) {
+    const rollbackFailures = [];
+    const uniqueNodeIDs = Array.from(new Set(nodeIDs));
+    for (const nodeID of uniqueNodeIDs.reverse()) {
+        try {
+            await deleteWorkspaceNode(client, workspaceID, nodeID);
+        }
+        catch (error) {
+            rollbackFailures.push({
+                nodeID,
+                ...serializePipelineExecutionError(error),
+            });
+        }
+    }
+    return rollbackFailures;
+}
+export async function createPipelineFromPlan(client, params) {
+    const plan = PipelinePlanSchema.parse(params.plan);
+    if (plan.workspaceID !== params.workspaceID) {
+        throw new Error(`Pipeline plan workspaceID ${plan.workspaceID} does not match requested workspaceID ${params.workspaceID}.`);
+    }
+    if (plan.status !== "ready") {
+        return {
+            created: false,
+            warning: "Pipeline plan still needs clarification. Review openQuestions and warnings before creation.",
+            plan,
+        };
+    }
+    if (params.dryRun) {
+        return {
+            created: false,
+            dryRun: true,
+            plan,
+        };
+    }
+    const createdNodes = [];
+    const createdNodeIDsByPlanNodeID = new Map();
+    const createdNodeIDsForRollback = [];
+    for (const nodePlan of plan.nodes) {
+        const predecessorNodeIDs = [
+            ...nodePlan.predecessorNodeIDs,
+            ...nodePlan.predecessorPlanNodeIDs.flatMap((planNodeID) => {
+                const createdNodeID = createdNodeIDsByPlanNodeID.get(planNodeID);
+                return createdNodeID ? [createdNodeID] : [];
+            }),
+        ];
+        if (predecessorNodeIDs.length === 0) {
+            throw new Error(`Pipeline node ${nodePlan.planNodeID} has no resolved predecessor node IDs.`);
+        }
+        let createdNodeID = null;
+        try {
+            const created = await createWorkspaceNodeFromPredecessor(client, {
+                workspaceID: params.workspaceID,
+                nodeType: nodePlan.nodeType,
+                predecessorNodeIDs,
+            });
+            if (!isPlainObject(created) || !isPlainObject(created.node)) {
+                throw new Error(`Pipeline node ${nodePlan.planNodeID} did not return a created node body.`);
+            }
+            if (typeof created.node.id === "string") {
+                createdNodeID = created.node.id;
+                createdNodeIDsForRollback.push(createdNodeID);
+            }
+            if ("warning" in created && typeof created.warning === "string") {
+                throw new Error(`Predecessor-based creation for ${nodePlan.name} did not confirm full auto-population: ${created.warning}`);
+            }
+            if (!createdNodeID) {
+                throw new Error(`Created pipeline node ${nodePlan.planNodeID} did not return a node ID.`);
+            }
+            const plannedBody = buildNodeBodyFromPlan(created.node, {
+                ...nodePlan,
+                predecessorNodeIDs,
+            });
+            // Route through the shared validation path to ensure all API-required
+            // fields (dataType, columnID, enabledColumnTestIDs, etc.) are present.
+            const finalBody = buildUpdatedWorkspaceNodeBody(created.node, plannedBody);
+            await setWorkspaceNode(client, {
+                workspaceID: params.workspaceID,
+                nodeID: createdNodeID,
+                body: finalBody,
+            });
+            const savedNode = await getWorkspaceNode(client, {
+                workspaceID: params.workspaceID,
+                nodeID: createdNodeID,
+            });
+            if (!isPlainObject(savedNode)) {
+                throw new Error(`Saved pipeline node ${nodePlan.name} did not return an object body.`);
+            }
+            const validation = validateSavedNode(savedNode, {
+                ...nodePlan,
+                predecessorNodeIDs,
+            });
+            if (!validation.nodeNameSatisfied ||
+                !validation.outputColumnsSatisfied ||
+                !validation.sourceMappingDependenciesSatisfied ||
+                !validation.joinConditionSatisfied ||
+                !validation.predecessorCoverageSatisfied) {
+                throw new Error(`Saved pipeline node ${nodePlan.name} did not match the planned body after set-workspace-node.`);
+            }
+            createdNodeIDsByPlanNodeID.set(nodePlan.planNodeID, createdNodeID);
+            createdNodes.push({
+                planNodeID: nodePlan.planNodeID,
+                nodeID: createdNodeID,
+                name: nodePlan.name,
+                nodeType: nodePlan.nodeType,
+                validation,
+            });
+        }
+        catch (error) {
+            const rollbackFailures = await rollbackCreatedPipelineNodes(client, params.workspaceID, createdNodeIDsForRollback);
+            if (rollbackFailures.length > 0) {
+                return {
+                    created: false,
+                    incomplete: true,
+                    failedPlanNodeID: nodePlan.planNodeID,
+                    createdNodes,
+                    cleanupFailedNodeIDs: rollbackFailures.map((failure) => failure.nodeID),
+                    cleanupFailures: rollbackFailures,
+                    warning: "Pipeline creation failed after nodes were created, and automatic cleanup did not fully succeed. Review the workspace manually before continuing.",
+                    error: serializePipelineExecutionError(error),
+                };
+            }
+            throw error;
+        }
+    }
+    return {
+        created: true,
+        workspaceID: params.workspaceID,
+        nodeCount: createdNodes.length,
+        createdNodes,
+    };
+}
+export async function createPipelineFromSql(client, params) {
+    const plan = await planPipeline(client, params);
+    if (plan.status !== "ready" || params.dryRun) {
+        return {
+            created: false,
+            STOP_AND_CONFIRM: "STOP. Present the pipeline summary to the user in a table format and ask for confirmation BEFORE creating any nodes. For EACH node, display: name, the EXACT nodeType string (e.g. 'Coalesce-Base-Node-Types:::Stage'), transforms, and filters. Use the cteNodeSummary or nodes array — do NOT paraphrase or simplify the nodeType values. Do NOT proceed until the user explicitly approves.",
+            ...(params.dryRun ? { dryRun: true } : {}),
+            plan,
+            ...(plan.status !== "ready"
+                ? {
+                    warning: "SQL was planned but still needs clarification before creation. Review openQuestions and warnings. Present the plan to the user and wait for approval.",
+                }
+                : {}),
+        };
+    }
+    const execution = await createPipelineFromPlan(client, {
+        workspaceID: params.workspaceID,
+        plan,
+        dryRun: params.dryRun,
+    });
+    return {
+        plan,
+        ...(isPlainObject(execution) ? execution : { execution }),
+    };
+}

package/dist/services/pipelines/node-type-intent.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Node Type Intent Corpus
+ *
+ * Authoritative reference for what each Coalesce node type family is designed for,
+ * derived from official Coalesce node type package READMEs.
+ *
+ * Used by the scoring logic to make informed decisions about which node type
+ * fits a given use case — instead of relying on name heuristics alone.
+ */
+import type { PipelineNodeTypeFamily } from "./node-type-selection.js";
+export type NodeTypeIntent = {
+    family: PipelineNodeTypeFamily;
+    /** What this node type is designed for */
+    purpose: string;
+    /** What materialization it creates */
+    materialization: string[];
+    /** When to use this type — positive signals */
+    useWhen: string[];
+    /** When NOT to use this type — anti-patterns */
+    doNotUseWhen: string[];
+    /** Whether it requires semantic config (business keys, SCD, etc.) */
+    requiresSemanticConfig: boolean;
+    /** Whether it handles multi-source (joins, unions) */
+    supportsMultiSource: boolean;
+    /** Keywords in goal/name that strongly indicate this type */
+    strongSignals: RegExp;
+    /** Keywords that should NOT trigger this type */
+    antiSignals: RegExp | null;
+};
+/**
+ * Specialized materialization patterns that exist across families.
+ * These are NOT families — they modify how a family-level node is materialized.
+ * Scoring penalizes these when the context doesn't explicitly request them.
+ */
+export type SpecializedPattern = {
+    name: string;
+    /** Regex to detect this pattern in candidate name/displayName */
+    detect: RegExp;
+    /** Regex the context must match to avoid penalty */
+    contextRequired: RegExp;
+    /** Scoring penalty when context doesn't match */
+    penalty: number;
+    /** Why this pattern exists and when to use it */
+    purpose: string;
+    /** When NOT to use this pattern */
+    doNotUseWhen: string[];
+};
+/**
+ * Intent corpus indexed by family.
+ *
+ * Source: Coalesce node type package READMEs
+ * - Coalesce-Base-Node-Types
+ * - Coalesce-Base-Node-Types---Advanced-Deploy
+ * - Dynamic-Table-Nodes
+ * - Incremental-Nodes
+ * - Materialized-View-Node
+ * - functional-node-types
+ * - create-alter-node-types
+ */
+export declare const NODE_TYPE_INTENT: Record<PipelineNodeTypeFamily, NodeTypeIntent>;
+/**
+ * Specialized materialization patterns that cross-cut families.
+ *
+ * These detect node types with specialized materialization behavior
+ * (Dynamic Tables, Incremental Loads, Materialized Views, etc.)
+ * and penalize them when the context doesn't explicitly call for that pattern.
+ *
+ * Source: Coalesce node type package READMEs
+ */
+export declare const SPECIALIZED_PATTERNS: SpecializedPattern[];
+/**
+ * Check whether a use case matches a family's anti-signals.
+ * Anti-signals indicate the family should NOT be used for this context.
+ */
+export declare function hasAntiSignal(family: PipelineNodeTypeFamily, text: string): boolean;
+/**
+ * Check whether a use case matches a family's strong signals.
+ */
+export declare function hasStrongSignal(family: PipelineNodeTypeFamily, text: string): boolean;
+/**
+ * Detect specialized materialization patterns in a candidate and return
+ * the penalty to apply if the context doesn't explicitly request it.
+ */
+/**
+ * Detect if a candidate matches a specialized pattern where the context
+ * does NOT request it. Returns the pattern info if the type should not be used.
+ */
+export declare function detectSpecializedPatternPenalty(candidateSignals: string, contextText: string): {
+    penalty: number;
+    reason: string;
+} | null;
+/**
+ * Detect if a candidate matches a specialized pattern AND the context
+ * explicitly requests it. Returns the pattern name if it's a positive match.
+ */
+export declare function detectSpecializedPatternMatch(candidateSignals: string, contextText: string): string | null;