goldenpipe 0.1.0

package/dist/core/index.js

@@ -0,0 +1,861 @@
+import { TabularData, scanData, severityLabel } from 'goldencheck/core';
+import { TransformEngine } from 'goldenflow/core';
+import { makeConfig, dedupe, makeMatchkeyConfig, makeMatchkeyField, makeBlockingConfig } from 'goldenmatch/core';
+
+// src/core/models.ts
+var StageStatus = {
+  SUCCESS: "success",
+  SKIPPED: "skipped",
+  FAILED: "failed"
+};
+var PipeStatus = {
+  SUCCESS: "success",
+  PARTIAL: "partial",
+  FAILED: "failed"
+};
+function makeDecision(input) {
+  return {
+    skip: input?.skip ?? [],
+    abort: input?.abort ?? false,
+    insert: input?.insert ?? [],
+    reason: input?.reason ?? ""
+  };
+}
+function makePipeContext(input) {
+  return {
+    df: input?.df ?? null,
+    artifacts: input?.artifacts ?? {},
+    metadata: input?.metadata ?? {},
+    timing: input?.timing ?? {},
+    reasoning: input?.reasoning ?? {},
+    stageConfig: input?.stageConfig ?? {}
+  };
+}
+function makeStageSpec(input) {
+  if (typeof input === "string") {
+    return { use: input, needs: [], onError: "continue", config: {} };
+  }
+  return {
+    ...input.name !== void 0 ? { name: input.name } : {},
+    use: input.use,
+    needs: input.needs ?? [],
+    ...input.skipIf !== void 0 ? { skipIf: input.skipIf } : {},
+    onError: input.onError ?? "continue",
+    config: input.config ?? {}
+  };
+}
+function makePipelineConfig(input) {
+  return {
+    pipeline: input.pipeline,
+    ...input.source !== void 0 ? { source: input.source } : {},
+    ...input.output !== void 0 ? { output: input.output } : {},
+    stages: input.stages,
+    decisions: input.decisions ?? []
+  };
+}
+function stage(info, fn) {
+  return {
+    info,
+    validate(_ctx) {
+    },
+    async run(ctx) {
+      return fn(ctx);
+    },
+    rollback: null
+  };
+}
+
+// src/core/columnContext.ts
+var ColumnType = {
+  NAME: "name",
+  EMAIL: "email",
+  PHONE: "phone",
+  DATE: "date",
+  GEO: "geo",
+  ADDRESS: "address",
+  ZIP: "zip",
+  IDENTIFIER: "identifier",
+  NUMERIC: "numeric",
+  STRING: "string",
+  DESCRIPTION: "description"
+};
+var CardinalityBand = {
+  UNSET: "",
+  LOW: "low",
+  MID: "mid",
+  HIGH: "high",
+  SKIP: "skip"
+};
+var MIN_CONFIDENCE = 0.3;
+var IDENTIFIER_TYPES = /* @__PURE__ */ new Set([
+  ColumnType.NAME,
+  ColumnType.EMAIL,
+  ColumnType.PHONE
+]);
+var NEVER_IDENTIFIER_TYPES = /* @__PURE__ */ new Set([
+  ColumnType.DATE,
+  ColumnType.NUMERIC,
+  ColumnType.IDENTIFIER
+]);
+function makeColumnContext(input) {
+  const ctx = {
+    name: input.name,
+    inferredType: input.inferredType ?? ColumnType.STRING,
+    nullRate: input.nullRate ?? 0,
+    cardinality: input.cardinality ?? 0,
+    isIdentifier: input.isIdentifier ?? false,
+    transformsApplied: input.transformsApplied ?? [],
+    findings: input.findings ?? [],
+    confidence: input.confidence ?? 0.5,
+    cardinalityBand: input.cardinalityBand ?? CardinalityBand.UNSET
+  };
+  if (!ctx.name) {
+    throw new Error("ColumnContext.name must be non-empty");
+  }
+  if (!(ctx.nullRate >= 0 && ctx.nullRate <= 1)) {
+    throw new Error(`nullRate must be in [0, 1], got ${ctx.nullRate}`);
+  }
+  if (ctx.cardinality < 0) {
+    throw new Error(`cardinality must be >= 0, got ${ctx.cardinality}`);
+  }
+  if (!(ctx.confidence >= 0 && ctx.confidence <= 1)) {
+    throw new Error(`confidence must be in [0, 1], got ${ctx.confidence}`);
+  }
+  return ctx;
+}
+var NAME_PATTERNS = /(^name$|first.?name|last.?name|full.?name|fname|lname|surname|given.?name|middle)/i;
+var EMAIL_PATTERNS = /(email|e.?mail|email.?addr)/i;
+var PHONE_PATTERNS = /(phone|tel|mobile|fax|cell)/i;
+var ZIP_PATTERNS = /(zip|postal|postcode|zip.?code)/i;
+var ADDRESS_PATTERNS = /(address|street|addr|line.?1|line.?2)/i;
+var GEO_PATTERNS = /(city|^state$|state.?cd|^country$|province|region|county)/i;
+var DATE_PATTERNS = /(date|_dt$|_date$|registr|created|updated|birth.?d|dob)/i;
+var ID_PATTERNS = /(^id$|^key$|^code$|^sku$|_id$|_key$)/i;
+function classifyByName(colName) {
+  if (DATE_PATTERNS.test(colName)) return ColumnType.DATE;
+  if (EMAIL_PATTERNS.test(colName)) return ColumnType.EMAIL;
+  if (ZIP_PATTERNS.test(colName)) return ColumnType.ZIP;
+  if (GEO_PATTERNS.test(colName)) return ColumnType.GEO;
+  if (ADDRESS_PATTERNS.test(colName)) return ColumnType.ADDRESS;
+  if (PHONE_PATTERNS.test(colName)) return ColumnType.PHONE;
+  if (NAME_PATTERNS.test(colName)) return ColumnType.NAME;
+  if (ID_PATTERNS.test(colName)) return ColumnType.IDENTIFIER;
+  return null;
+}
+function normalizeDtype(rawType) {
+  const t = rawType.toLowerCase().trim();
+  if (t.includes("int") || t.includes("float")) return ColumnType.NUMERIC;
+  if (t.includes("date") || t.includes("time")) return ColumnType.DATE;
+  if (t.includes("bool")) return ColumnType.STRING;
+  return ColumnType.STRING;
+}
+function computeCardinalityBands(contexts) {
+  const stringContexts = contexts.filter(
+    (c) => c.inferredType !== ColumnType.NUMERIC && c.inferredType !== ColumnType.DATE
+  );
+  if (stringContexts.length < 3) {
+    return;
+  }
+  const cardinalities = stringContexts.map((c) => c.cardinality).sort((a, b) => a - b);
+  const n = cardinalities.length;
+  const q1 = cardinalities[Math.floor(n / 4)];
+  const q3 = cardinalities[Math.floor(3 * n / 4)];
+  for (const ctx of contexts) {
+    if (ctx.inferredType === ColumnType.NUMERIC || ctx.inferredType === ColumnType.DATE) {
+      ctx.cardinalityBand = CardinalityBand.SKIP;
+      continue;
+    }
+    if (ctx.cardinality <= q1) {
+      ctx.cardinalityBand = CardinalityBand.LOW;
+    } else if (ctx.cardinality >= q3) {
+      ctx.cardinalityBand = CardinalityBand.HIGH;
+    } else {
+      ctx.cardinalityBand = CardinalityBand.MID;
+    }
+  }
+}
+function applyCardinalitySignal(contexts) {
+  for (const ctx of contexts) {
+    if (NEVER_IDENTIFIER_TYPES.has(ctx.inferredType)) {
+      ctx.isIdentifier = false;
+      continue;
+    }
+    const hasNameSignal = IDENTIFIER_TYPES.has(ctx.inferredType);
+    const band = ctx.cardinalityBand;
+    if (hasNameSignal && band === CardinalityBand.MID) {
+      ctx.isIdentifier = true;
+      ctx.confidence = Math.min(ctx.confidence + 0.15, 1);
+    } else if (hasNameSignal && band === CardinalityBand.LOW) {
+      ctx.isIdentifier = false;
+      ctx.confidence = Math.max(ctx.confidence - 0.2, MIN_CONFIDENCE);
+    } else if (hasNameSignal && band === CardinalityBand.HIGH) {
+      ctx.isIdentifier = true;
+      ctx.confidence = Math.min(ctx.confidence + 0.05, 1);
+    } else if (!hasNameSignal && band === CardinalityBand.MID) {
+      if (ctx.inferredType === ColumnType.STRING) {
+        ctx.isIdentifier = true;
+        ctx.confidence = 0.5;
+      }
+    } else if (!hasNameSignal && band === CardinalityBand.LOW) {
+      ctx.isIdentifier = false;
+    } else if (!hasNameSignal && band === CardinalityBand.HIGH) {
+      ctx.isIdentifier = false;
+    }
+    if (ctx.nullRate > 0.3 && ctx.isIdentifier) {
+      ctx.confidence = Math.max(ctx.confidence - 0.1, MIN_CONFIDENCE);
+    }
+  }
+}
+function buildContextsFromCheck(findings, columnProfiles) {
+  if (!columnProfiles || columnProfiles.length === 0) {
+    return [];
+  }
+  const contexts = /* @__PURE__ */ new Map();
+  for (const cp of columnProfiles) {
+    let semanticType = classifyByName(cp.name);
+    if (!semanticType) {
+      semanticType = normalizeDtype(cp.inferredType ?? "string");
+    }
+    const ctx = makeColumnContext({
+      name: cp.name,
+      inferredType: semanticType,
+      nullRate: cp.nullPct ?? 0,
+      cardinality: cp.uniqueCount ?? 0,
+      isIdentifier: IDENTIFIER_TYPES.has(semanticType),
+      confidence: semanticType !== ColumnType.STRING ? 0.8 : 0.4
+    });
+    contexts.set(cp.name, ctx);
+  }
+  const contextList = [...contexts.values()];
+  computeCardinalityBands(contextList);
+  applyCardinalitySignal(contextList);
+  for (const f of findings) {
+    const colName = f.column;
+    if (!colName || !contexts.has(colName)) continue;
+    const ctx = contexts.get(colName);
+    const check = f.check ?? "";
+    const message = String(f.message ?? "").slice(0, 80);
+    ctx.findings.push(`${check}: ${message}`);
+  }
+  return contextList;
+}
+function enrichContextsFromFlow(contexts, records) {
+  if (!records) return;
+  const lookup = new Map(contexts.map((c) => [c.name, c]));
+  for (const record of records) {
+    const colName = record.column;
+    const transform = record.transform;
+    const affected = record.affectedRows ?? 0;
+    if (!colName || !lookup.has(colName)) continue;
+    const ctx = lookup.get(colName);
+    if (affected > 0 && transform) {
+      ctx.transformsApplied.push(transform);
+    }
+    if (transform && transform.toLowerCase().includes("date")) {
+      ctx.inferredType = ColumnType.DATE;
+      ctx.isIdentifier = false;
+      ctx.confidence = 0.95;
+    }
+  }
+}
+function distinctNonNull(rows, col) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    const v = row[col];
+    if (v === null || v === void 0 || v === "") continue;
+    seen.add(v);
+  }
+  return seen.size;
+}
+function nullRateOf(rows, col) {
+  if (rows.length === 0) return 1;
+  let nulls = 0;
+  for (const row of rows) {
+    const v = row[col];
+    if (v === null || v === void 0 || v === "") nulls += 1;
+  }
+  return nulls / rows.length;
+}
+
+// src/core/engine/registry.ts
+var StageRegistry = class {
+  stages = /* @__PURE__ */ new Map();
+  /** Register a stage under its `info.name`. */
+  register(stage2) {
+    this.stages.set(stage2.info.name, stage2);
+  }
+  /** Retrieve a stage by name. Throws if not found. */
+  get(name) {
+    const stage2 = this.stages.get(name);
+    if (stage2 === void 0) {
+      throw new Error(`Stage '${name}' not found in registry`);
+    }
+    return stage2;
+  }
+  /** True when a stage with this name is registered. */
+  has(name) {
+    return this.stages.has(name);
+  }
+  /** Return `{ name: StageInfo }` for all registered stages. */
+  listAll() {
+    const out = {};
+    for (const [name, s] of this.stages) {
+      out[name] = s.info;
+    }
+    return out;
+  }
+};
+function defaultRegistry() {
+  const registry = new StageRegistry();
+  return registry;
+}
+
+// src/core/engine/resolver.ts
+var WiringError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WiringError";
+  }
+};
+var Resolver = {
+  /**
+   * Resolve a config + registry into an ordered ExecutionPlan. Auto-prepends
+   * the built-in `load` stage when available and validates that every stage's
+   * `consumes` is produced by an earlier stage.
+   */
+  resolve(config, registry) {
+    const plan = { stages: [] };
+    const availableArtifacts = /* @__PURE__ */ new Set();
+    if (registry.has("load")) {
+      const load = registry.get("load");
+      plan.stages.push({
+        name: "load",
+        stage: load,
+        spec: makeStageSpec("load"),
+        config: {}
+      });
+      for (const p of load.info.produces) availableArtifacts.add(p);
+    } else {
+      availableArtifacts.add("df");
+    }
+    for (const rawSpec of config.stages) {
+      const spec = makeStageSpec(rawSpec);
+      const stageObj = registry.get(spec.use);
+      const name = spec.name ?? stageObj.info.name;
+      for (const dep of stageObj.info.consumes) {
+        if (!availableArtifacts.has(dep)) {
+          throw new WiringError(
+            `Stage '${name}' consumes '${dep}' but no prior stage produces it. Available: ${[...availableArtifacts].sort().join(", ")}`
+          );
+        }
+      }
+      plan.stages.push({ name, stage: stageObj, spec, config: spec.config });
+      for (const p of stageObj.info.produces) availableArtifacts.add(p);
+    }
+    return plan;
+  }
+};
+
+// src/core/engine/router.ts
+var Router = {
+  /**
+   * Apply a Decision (skip / abort / insert) to the remaining stages and
+   * return the new remaining list. Records `decision.reason` in
+   * `ctx.reasoning._router`.
+   */
+  apply(decision, remaining, ctx, registry) {
+    if (decision.reason) {
+      ctx.reasoning["_router"] = decision.reason;
+    }
+    if (decision.abort) {
+      ctx.reasoning["_router"] = `ABORT: ${decision.reason}`;
+      return [];
+    }
+    let next = remaining;
+    if (decision.skip.length > 0) {
+      const skipSet = new Set(decision.skip);
+      next = next.filter((s) => !skipSet.has(s.name));
+    }
+    if (decision.insert.length > 0) {
+      const inserted = [];
+      for (const name of decision.insert) {
+        const stageObj = registry.get(name);
+        inserted.push({
+          name,
+          stage: stageObj,
+          spec: makeStageSpec(name),
+          config: {}
+        });
+      }
+      next = [...inserted, ...next];
+    }
+    return next;
+  }
+};
+
+// src/core/engine/runner.ts
+function isFalsy(value) {
+  if (value === null || value === void 0) return true;
+  if (value === false || value === 0 || value === "") return true;
+  if (Array.isArray(value)) return value.length === 0;
+  if (value instanceof Map || value instanceof Set) return value.size === 0;
+  if (typeof value === "object") return Object.keys(value).length === 0;
+  return false;
+}
+var Runner = class {
+  constructor(registry) {
+    this.registry = registry;
+  }
+  registry;
+  /** Execute an ExecutionPlan against a PipeContext, returning per-stage results. */
+  async run(plan, ctx) {
+    const results = {};
+    let remaining = [...plan.stages];
+    while (remaining.length > 0) {
+      const planned = remaining.shift();
+      if (planned.spec.skipIf) {
+        const artifact = ctx.artifacts[planned.spec.skipIf];
+        if (isFalsy(artifact)) {
+          results[planned.name] = { status: StageStatus.SKIPPED };
+          ctx.reasoning[planned.name] = `Skipped: artifact '${planned.spec.skipIf}' is missing/falsy`;
+          continue;
+        }
+      }
+      const start = performance.now();
+      try {
+        ctx.stageConfig = planned.config;
+        await planned.stage.validate(ctx);
+        const result = await planned.stage.run(ctx);
+        ctx.timing[planned.name] = (performance.now() - start) / 1e3;
+        results[planned.name] = result;
+        if (result.decision != null) {
+          remaining = Router.apply(result.decision, remaining, ctx, this.registry);
+        }
+      } catch (e) {
+        ctx.timing[planned.name] = (performance.now() - start) / 1e3;
+        const message = e instanceof Error ? e.message : String(e);
+        results[planned.name] = { status: StageStatus.FAILED, error: message };
+        ctx.reasoning[planned.name] = `Failed: ${message}`;
+        if (planned.spec.onError === "abort") {
+          break;
+        }
+      }
+    }
+    return results;
+  }
+};
+
+// src/core/engine/reporter.ts
+var Reporter = {
+  build(ctx, stages) {
+    const entries = Object.entries(stages);
+    const errors = entries.filter(([, r]) => r.status === StageStatus.FAILED && r.error).map(([name, r]) => `${name}: ${r.error}`);
+    const skipped = entries.filter(([, r]) => r.status === StageStatus.SKIPPED).map(([name]) => name);
+    const nonSkip = entries.map(([, r]) => r.status).filter((s) => s !== StageStatus.SKIPPED);
+    let status;
+    if (nonSkip.length === 0) {
+      status = PipeStatus.SUCCESS;
+    } else if (nonSkip.every((s) => s === StageStatus.FAILED)) {
+      status = PipeStatus.FAILED;
+    } else if (nonSkip.every((s) => s === StageStatus.SUCCESS)) {
+      status = PipeStatus.SUCCESS;
+    } else {
+      status = PipeStatus.PARTIAL;
+    }
+    return {
+      status,
+      source: typeof ctx.metadata["source"] === "string" ? ctx.metadata["source"] : "",
+      inputRows: typeof ctx.metadata["input_rows"] === "number" ? ctx.metadata["input_rows"] : 0,
+      stages,
+      artifacts: { ...ctx.artifacts },
+      skipped,
+      errors,
+      reasoning: { ...ctx.reasoning },
+      timing: { ...ctx.timing }
+    };
+  }
+};
+
+// src/core/decisions.ts
+function findingsOf(ctx) {
+  const findings = ctx.artifacts["findings"];
+  if (!Array.isArray(findings) || findings.length === 0) return null;
+  return findings;
+}
+function severityGate(ctx) {
+  const findings = findingsOf(ctx);
+  if (!findings) return null;
+  const hasCritical = findings.some((f) => f.severity === "critical");
+  if (hasCritical) {
+    return makeDecision({ abort: true, reason: "Critical findings detected" });
+  }
+  return null;
+}
+function piiRouter(ctx) {
+  const findings = findingsOf(ctx);
+  if (!findings) return null;
+  const hasPii = findings.some((f) => f.check === "pii_detection");
+  if (hasPii) {
+    return makeDecision({
+      skip: ["goldenmatch.dedupe"],
+      insert: ["goldenmatch.dedupe_pprl"],
+      reason: "PII detected, routing to PPRL matching"
+    });
+  }
+  return null;
+}
+function rowCountGate(ctx) {
+  const rowCount = typeof ctx.metadata["input_rows"] === "number" ? ctx.metadata["input_rows"] : 0;
+  if (rowCount < 2) {
+    return makeDecision({
+      skip: ["goldenmatch.dedupe"],
+      reason: `Only ${rowCount} row(s), skipping deduplication`
+    });
+  }
+  return null;
+}
+
+// src/core/adapters/load.ts
+var LoadStage = {
+  info: { name: "load", produces: ["df"], consumes: [] },
+  validate(_ctx) {
+  },
+  async run(_ctx) {
+    return { status: StageStatus.SUCCESS };
+  },
+  rollback: null
+};
+function normalizeFinding(f) {
+  return {
+    severity: severityLabel(f.severity).toLowerCase(),
+    check: f.check,
+    column: f.column,
+    message: f.message
+  };
+}
+function toColumnProfileLike(cp) {
+  return {
+    name: cp.name,
+    inferredType: cp.inferredType,
+    nullPct: cp.nullPct,
+    uniqueCount: cp.uniqueCount
+  };
+}
+var ScanStage = {
+  info: { name: "goldencheck.scan", produces: ["findings", "profile"], consumes: ["df"] },
+  validate(ctx) {
+    if (ctx.df === null) {
+      throw new Error("ScanStage: no df in context");
+    }
+  },
+  async run(ctx) {
+    const rows = ctx.df ?? [];
+    const data = new TabularData(rows);
+    const stageCfg = ctx.stageConfig;
+    const opts = stageCfg && Object.keys(stageCfg).length > 0 ? stageCfg : void 0;
+    const result = scanData(data, opts);
+    const findings = result.findings.map(normalizeFinding);
+    const columnProfiles = result.profile.columns;
+    ctx.artifacts["findings"] = findings;
+    ctx.artifacts["profile"] = result.profile;
+    try {
+      const profileLikes = columnProfiles.map(toColumnProfileLike);
+      const findingLikes = findings.map((f) => ({
+        column: f.column,
+        check: f.check,
+        message: f.message
+      }));
+      ctx.artifacts["column_contexts"] = buildContextsFromCheck(findingLikes, profileLikes);
+    } catch {
+      ctx.artifacts["column_contexts"] = [];
+    }
+    return { status: StageStatus.SUCCESS };
+  },
+  rollback: null
+};
+var TransformStage = {
+  info: { name: "goldenflow.transform", produces: ["df", "manifest"], consumes: ["df"] },
+  validate(ctx) {
+    if (ctx.df === null) {
+      throw new Error("TransformStage: no df in context");
+    }
+  },
+  async run(ctx) {
+    const rows = ctx.df ?? [];
+    const stageCfg = ctx.stageConfig;
+    const config = stageCfg && Object.keys(stageCfg).length > 0 ? stageCfg : void 0;
+    const engine = new TransformEngine(config);
+    const result = engine.transformDf(rows);
+    ctx.df = [...result.rows];
+    ctx.artifacts["manifest"] = result.manifest;
+    const contexts = ctx.artifacts["column_contexts"];
+    if (Array.isArray(contexts)) {
+      try {
+        const records = result.manifest.records.map((r) => ({
+          column: r.column,
+          transform: r.transform,
+          affectedRows: r.affectedRows
+        }));
+        enrichContextsFromFlow(contexts, records);
+      } catch {
+      }
+    }
+    return { status: StageStatus.SUCCESS };
+  },
+  rollback: null
+};
+function castRowsToString(rows) {
+  return rows.map((row) => {
+    const out = {};
+    for (const [k, v] of Object.entries(row)) {
+      out[k] = v === null || v === void 0 ? "" : String(v);
+    }
+    return out;
+  });
+}
+var DedupeStage = {
+  info: { name: "goldenmatch.dedupe", produces: ["clusters", "golden"], consumes: ["df"] },
+  validate(ctx) {
+    if (ctx.df === null) {
+      throw new Error("DedupeStage: no df in context");
+    }
+  },
+  async run(ctx) {
+    const rows = castRowsToString(ctx.df ?? []);
+    ctx.df = rows;
+    const stageCfg = ctx.stageConfig;
+    let config = null;
+    if (stageCfg && Object.keys(stageCfg).length > 0) {
+      config = makeConfig(stageCfg);
+    } else {
+      const contexts = ctx.artifacts["column_contexts"];
+      if (Array.isArray(contexts) && contexts.length > 0) {
+        config = buildConfigFromContexts(contexts, rows);
+      }
+    }
+    const result = config !== null ? await dedupe(rows, { config }) : await dedupe(rows);
+    ctx.artifacts["clusters"] = result.clusters;
+    ctx.artifacts["golden"] = result.goldenRecords;
+    ctx.artifacts["unique"] = result.unique;
+    ctx.artifacts["dupes"] = result.dupes;
+    ctx.artifacts["match_stats"] = result.stats;
+    ctx.artifacts["scored_pairs"] = result.scoredPairs;
+    const mks = config?.matchkeys;
+    if (mks && mks.length > 0) {
+      ctx.artifacts["matchkey_used"] = mks[0].name;
+    }
+    return { status: StageStatus.SUCCESS };
+  },
+  rollback: null
+};
+function buildConfigFromContexts(contexts, rows) {
+  const nameCols = contexts.filter(
+    (c) => c.inferredType === ColumnType.NAME && c.isIdentifier
+  );
+  const emailCols = contexts.filter((c) => c.inferredType === ColumnType.EMAIL);
+  const geoCols = contexts.filter((c) => c.inferredType === ColumnType.GEO);
+  const matchkeys = [];
+  for (const col of emailCols) {
+    matchkeys.push(
+      makeMatchkeyConfig({
+        name: `exact_${col.name}`,
+        type: "exact",
+        fields: [makeMatchkeyField({ field: col.name, transforms: ["lowercase", "strip"], scorer: "exact" })]
+      })
+    );
+  }
+  if (nameCols.length > 0) {
+    const fuzzyFields = nameCols.map(
+      (col) => makeMatchkeyField({
+        field: col.name,
+        scorer: "jaro_winkler",
+        weight: 1,
+        transforms: ["lowercase", "strip"]
+      })
+    );
+    matchkeys.push(
+      makeMatchkeyConfig({
+        name: "fuzzy_names",
+        type: "weighted",
+        threshold: 0.85,
+        fields: fuzzyFields
+      })
+    );
+  }
+  if (matchkeys.length === 0) {
+    let stringCols = contexts.filter(
+      (c) => c.inferredType === ColumnType.STRING || c.inferredType === ColumnType.NAME
+    );
+    if (rows.length > 0) {
+      const minCardinality = Math.max(10, Math.floor(rows.length * 0.05));
+      stringCols = stringCols.filter((c) => distinctNonNull(rows, c.name) >= minCardinality);
+    }
+    const fallbackFields = stringCols.slice(0, 3).map(
+      (col) => makeMatchkeyField({
+        field: col.name,
+        scorer: "jaro_winkler",
+        weight: 1,
+        transforms: ["lowercase", "strip"]
+      })
+    );
+    if (fallbackFields.length > 0) {
+      matchkeys.push(
+        makeMatchkeyConfig({
+          name: "fuzzy_fallback",
+          type: "weighted",
+          threshold: 0.85,
+          fields: fallbackFields
+        })
+      );
+    }
+  }
+  if (matchkeys.length === 0) {
+    return null;
+  }
+  let bestGeo = null;
+  if (geoCols.length > 0 && rows.length > 0) {
+    const maxNullRate = 0.2;
+    const geoCandidates = [];
+    for (const g of geoCols) {
+      if (nullRateOf(rows, g.name) <= maxNullRate) {
+        geoCandidates.push([g.name, distinctNonNull(rows, g.name)]);
+      }
+    }
+    if (geoCandidates.length > 0) {
+      geoCandidates.sort((a, b) => a[1] - b[1]);
+      bestGeo = geoCandidates[0][0];
+    }
+  }
+  const makeBlocking = (primaryFields, recallName, withGeo = false) => {
+    const passes = [
+      { fields: primaryFields, transforms: ["lowercase", "strip"] }
+    ];
+    if (withGeo) {
+      passes.push({ fields: primaryFields, transforms: ["lowercase", "substring:0:3"] });
+    }
+    passes.push({ fields: [recallName], transforms: ["lowercase", "soundex"] });
+    return makeBlockingConfig({
+      strategy: "multi_pass",
+      keys: [passes[0]],
+      passes,
+      maxBlockSize: 500,
+      skipOversized: true
+    });
+  };
+  let blocking = null;
+  const lastNameCols = nameCols.filter((c) => c.name.toLowerCase().includes("last"));
+  if (lastNameCols.length > 0) {
+    const bestName = lastNameCols[0].name;
+    blocking = bestGeo ? makeBlocking([bestGeo, bestName], bestName, true) : makeBlocking([bestName], bestName);
+  } else if (nameCols.length > 0) {
+    const bestName = nameCols[0].name;
+    if (bestGeo) {
+      blocking = makeBlocking([bestGeo, bestName], bestName, true);
+    } else {
+      blocking = makeBlockingConfig({
+        strategy: "static",
+        keys: [{ fields: [bestName], transforms: ["lowercase", "soundex"] }],
+        maxBlockSize: 500,
+        skipOversized: true
+      });
+    }
+  }
+  if (!blocking && bestGeo && matchkeys.length > 0) {
+    const fuzzyMks = matchkeys.filter((mk) => mk.type === "weighted");
+    const first = fuzzyMks[0];
+    if (first && first.fields.length > 0) {
+      const anchor = first.fields[0].field;
+      blocking = makeBlocking([bestGeo, anchor], anchor, true);
+    }
+  }
+  if (!blocking) {
+    blocking = makeBlockingConfig({ keys: [], autoSuggest: true });
+  }
+  return makeConfig({ matchkeys, blocking });
+}
+
+// src/core/adapters/index.ts
+function buildDefaultRegistry() {
+  const registry = new StageRegistry();
+  registry.register(LoadStage);
+  registry.register(ScanStage);
+  registry.register(TransformStage);
+  registry.register(DedupeStage);
+  return registry;
+}
+
+// src/core/pipeline.ts
+var DEFAULT_STAGE_ORDER = [
+  "goldencheck.scan",
+  "goldenflow.transform",
+  "goldenmatch.dedupe"
+];
+var Pipeline = class {
+  config;
+  registry;
+  constructor(options) {
+    this.config = options?.config;
+    this.registry = options?.registry ?? buildDefaultRegistry();
+  }
+  /** Run the pipeline on an array of rows. */
+  async run(rows, source = "<rows>") {
+    const ctx = makePipeContext({
+      df: [...rows],
+      metadata: { source, input_rows: rows.length }
+    });
+    const config = this.config ?? this.autoConfig();
+    let plan;
+    try {
+      plan = Resolver.resolve(config, this.registry);
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return {
+        status: PipeStatus.FAILED,
+        source,
+        inputRows: rows.length,
+        stages: {},
+        artifacts: {},
+        skipped: [],
+        errors: [`Pipeline resolution failed: ${message}`],
+        reasoning: {},
+        timing: {}
+      };
+    }
+    const runner = new Runner(this.registry);
+    const stages = await runner.run(plan, ctx);
+    return Reporter.build(ctx, stages);
+  }
+  /** Build the default check→flow→dedupe config from the available stages. */
+  autoConfig() {
+    const available = this.registry.listAll();
+    const stages = DEFAULT_STAGE_ORDER.filter((name) => name in available).map(
+      (name) => makeStageSpec(name)
+    );
+    return makePipelineConfig({ pipeline: "auto", stages });
+  }
+};
+async function runDf(rows, config, source = "<rows>") {
+  const pipe = new Pipeline(config !== void 0 ? { config } : {});
+  return pipe.run(rows, source);
+}
+async function runStages(stages, rows) {
+  const registry = new StageRegistry();
+  for (const s of stages) registry.register(s);
+  const config = makePipelineConfig({
+    pipeline: "programmatic",
+    stages: stages.map((s) => makeStageSpec(s.info.name))
+  });
+  const ctx = makePipeContext({
+    df: [...rows],
+    metadata: { source: "<programmatic>", input_rows: rows.length }
+  });
+  const plan = Resolver.resolve(config, registry);
+  plan.stages = plan.stages.filter((s) => s.name !== "load");
+  const runner = new Runner(registry);
+  const results = await runner.run(plan, ctx);
+  return Reporter.build(ctx, results);
+}
+
+export { CardinalityBand, ColumnType, DedupeStage, LoadStage, MIN_CONFIDENCE, PipeStatus, Pipeline, Reporter, Resolver, Router, Runner, ScanStage, StageRegistry, StageStatus, TransformStage, WiringError, buildConfigFromContexts, buildContextsFromCheck, buildDefaultRegistry, classifyByName, defaultRegistry, distinctNonNull, enrichContextsFromFlow, makeColumnContext, makeDecision, makePipeContext, makePipelineConfig, makeStageSpec, normalizeDtype, nullRateOf, piiRouter, rowCountGate, runDf, runStages, severityGate, stage };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map