@memberjunction/integration-engine 5.40.2 → 5.42.0

package/dist/KeySerialization.js

@@ -0,0 +1,29 @@
+/**
+ * Key-value serialization for record identity.
+ *
+ * `serializeKeyValue` mirrors the engine's write-side value coercion (see
+ * `IntegrationEngine` value-handling: object/array → `JSON.stringify`, NOT the JS default
+ * `"[object Object]"`). It is used to build a record's composite ExternalID / load key from
+ * its primary-key field VALUES, so the key derived at load time equals the value persisted in
+ * the column for object-valued PKs — without this, every object-valued PK would collapse to
+ * `"[object Object]"` and all such records would share one identity (the duplicate-row class
+ * of bug).
+ *
+ * Contract (pinned by call sites in `BaseRESTIntegrationConnector`, `MatchEngine`,
+ * `IntegrationEngine.extractMappedPrimaryKey`):
+ * - `null` / `undefined` → `''` (empty string). Callers treat `''` as a missing key component
+ *   (`if (s === '') return null` / `serializeKeyValue(v).length > 0`), which routes genuinely
+ *   keyless / partial-key rows to the content-hash identity fallback rather than a bogus key.
+ * - plain object / array (anything `typeof === 'object'` that is not a `Date`) → `JSON.stringify`.
+ * - everything else (string / number / boolean / Date / bigint / symbol) → `String(value)`.
+ */
+export function serializeKeyValue(value) {
+    if (value == null) {
+        return '';
+    }
+    if (typeof value === 'object' && !(value instanceof Date)) {
+        return JSON.stringify(value);
+    }
+    return String(value);
+}
+//# sourceMappingURL=KeySerialization.js.map

package/dist/KeySerialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeySerialization.js","sourceRoot":"","sources":["../src/KeySerialization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC5C,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAChB,OAAO,EAAE,CAAC;IACd,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,YAAY,IAAI,CAAC,EAAE,CAAC;QACxD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC"}

package/dist/MatchEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MatchEngine.d.ts","sourceRoot":"","sources":["../src/MatchEngine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAqB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,KAAK,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AACnG,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,YAAY,CAAC;AAEnE;;;GAGG;AACH,qBAAa,WAAW;IACpB,gFAAgF;IAChF,OAAO,CAAC,SAAS,CAAC,CAAoB;IAEtC,4FAA4F;IAC5F,SAAS,KAAK,aAAa,IAAI,iBAAiB,CAE/C;IAED;;;;;;;;;OASG;IACU,OAAO,CAChB,OAAO,EAAE,YAAY,EAAE,EACvB,SAAS,EAAE,4BAA4B,EACvC,SAAS,EAAE,2BAA2B,EAAE,EACxC,WAAW,EAAE,QAAQ,EACrB,QAAQ,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,YAAY,EAAE,CAAC;IAmB1B;;OAEG;YACW,mBAAmB;IAsBjC;;OAEG;YACW,oBAAoB;IAmBlC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;;;;;;;OAQG;YACW,kBAAkB;IAuBhC;;;;;;;;;OASG;YACW,eAAe;IAiD7B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;OAEG;YACW,kBAAkB;CA0BnC"}
+{"version":3,"file":"MatchEngine.d.ts","sourceRoot":"","sources":["../src/MatchEngine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAqB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,KAAK,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AACnG,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,YAAY,CAAC;AAGnE;;;GAGG;AACH,qBAAa,WAAW;IACpB,gFAAgF;IAChF,OAAO,CAAC,SAAS,CAAC,CAAoB;IAEtC,4FAA4F;IAC5F,SAAS,KAAK,aAAa,IAAI,iBAAiB,CAE/C;IAED;;;;;;;;;OASG;IACU,OAAO,CAChB,OAAO,EAAE,YAAY,EAAE,EACvB,SAAS,EAAE,4BAA4B,EACvC,SAAS,EAAE,2BAA2B,EAAE,EACxC,WAAW,EAAE,QAAQ,EACrB,QAAQ,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,YAAY,EAAE,CAAC;IAmB1B;;OAEG;YACW,mBAAmB;IAsBjC;;OAEG;YACW,oBAAoB;IAmBlC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;;;;;;;OAQG;YACW,kBAAkB;IAuBhC;;;;;;;;;OASG;YACW,eAAe;IAqD7B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;OAEG;YACW,kBAAkB;CA0BnC"}

package/dist/MatchEngine.js

@@ -1,4 +1,5 @@
 import { Metadata, RunView } from '@memberjunction/core';
+import { serializeKeyValue } from './KeySerialization.js';
 /**
  * Resolves mapped records against existing MJ data to determine
  * whether each record should be Created, Updated, Skipped, or Deleted.
@@ -110,8 +111,12 @@ export class MatchEngine {
                 const value = record.MappedFields[pkField.Name];
                 if (value == null)
                     continue;
-                const escaped = String(value).replace(/'/g, "''");
-                const clause = `[${pkField.Name}] = '${escaped}'`;
+                const escaped = serializeKeyValue(value).replace(/'/g, "''");
+                // ANSI double-quoted identifier — portable across SQL Server (QUOTED_IDENTIFIER ON,
+                // the driver default) and Postgres (exact-case; integration columns are lowercase).
+                // Plain identifiers break when a column name is a reserved word (e.g. a soft PK named
+                // `open`/`order`); brackets would fix SQL Server but break Postgres, so double-quote.
+                const clause = `"${pkField.Name}" = '${escaped}'`;
                 if (!filterClauses.includes(clause)) {
                     filterClauses.push(clause);
                 }
@@ -142,8 +147,11 @@ export class MatchEngine {
             const value = record.MappedFields[kf.DestinationFieldName];
             if (value == null)
                 continue;
-            const escaped = String(value).replace(/'/g, "''");
-            clauses.push(`[${kf.DestinationFieldName}] = '${escaped}'`);
+            // serializeKeyValue mirrors the write-side coercion (objects → JSON, not "[object Object]")
+            // so an object-valued key filters against the value actually stored in the column.
+            const escaped = serializeKeyValue(value).replace(/'/g, "''");
+            // ANSI double-quoted identifier — reserved-word-safe + portable; see CompositePK note above.
+            clauses.push(`"${kf.DestinationFieldName}" = '${escaped}'`);
         }
         return clauses;
     }

package/dist/MatchEngine.js.map

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

package/dist/RecordFlatten.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Generic nested-object flattening for discovery + sync record-intake.
+ *
+ * WHY (the framework bug this fixes — see memory project_connector_nested_pk_dupe):
+ * a source that returns NESTED records — e.g. PropFuel's
+ *   { checkin_question: { id, checkin_id, rating, … }, contact: {…}, question: {…}, campaign: {…} }
+ * — folds in `discoverFromStream` as ONE object-valued column per top-level key. The soft-PK
+ * picker then takes the object-valued column (`checkin_question`) as the PK, because each blob is
+ * distinct. An object-valued PK is poison:
+ *   1. Identity becomes per-OCCURRENCE/per-VERSION (the blob serialized, or a `${file}:${hash}`
+ *      fallback) instead of per-LOGICAL-RECORD, so the same record across files/versions lands as
+ *      multiple rows → DUPLICATES.
+ *   2. The persisted column is an opaque JSON blob, not queryable scalar columns.
+ *
+ * Flattening BEFORE discovery makes the scalar `checkin_question_id` a column → the PK picker chooses
+ * a real scalar key → identity is the logical id → no dupes, and the entity is flat + queryable. The
+ * SAME flatten MUST run at sync record-intake so records match the discovered (flattened) schema.
+ *
+ * Behaviour:
+ *  - Plain nested objects are flattened with `parent<sep>child` scalar keys (default sep `_`, so
+ *    `checkin_question.id` → `checkin_question_id` — a valid MJ column name).
+ *  - Arrays, Dates, and `null` are LEAF values (kept as-is) — arrays/Dates aren't column-flattenable;
+ *    the write path serializes them as it already does.
+ *  - Bounded by `maxDepth` (default 4); an object at the depth limit is kept as a leaf (blob) rather
+ *    than recursed, so pathological deep nesting can't explode the column set.
+ *  - A FLAT record passes through unchanged — so every existing flat-record connector is a NO-OP and
+ *    sees zero behaviour change.
+ *  - Key collisions (a pre-existing `a_b` colliding with a flattened `a.b`) keep the FIRST-seen value
+ *    and are reported via `opts.onCollision` so the caller can surface it; silent overwrite is avoided.
+ */
+export interface FlattenOptions {
+    /** Separator between parent and child key segments. Default `'_'`. */
+    Separator?: string;
+    /** Maximum nesting depth to flatten; objects deeper than this are kept as leaf blobs. Default 4. */
+    MaxDepth?: number;
+    /** Invoked when a flattened key collides with an existing key (first value wins). For diagnostics. */
+    onCollision?: (key: string) => void;
+}
+/**
+ * Returns true if `raw` contains at least one nested plain-object value — i.e. flattening would
+ * change it. Cheap top-level check; lets callers skip the allocation for the flat-record common case.
+ */
+export declare function hasNestedObject(raw: Record<string, unknown>): boolean;
+/**
+ * Flatten a record's nested plain-objects into `parent<sep>child` scalar keys. Pure; returns a new
+ * object. A record with no nested objects is returned shallow-copied + unchanged in shape.
+ */
+export declare function flattenRecord(raw: Record<string, unknown>, opts?: FlattenOptions): Record<string, unknown>;
+//# sourceMappingURL=RecordFlatten.d.ts.map

package/dist/RecordFlatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordFlatten.d.ts","sourceRoot":"","sources":["../src/RecordFlatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,cAAc;IAC3B,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAaD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAKrE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CACzB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,GAAE,cAAmB,GAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0BzB"}

package/dist/RecordFlatten.js

@@ -0,0 +1,50 @@
+const DEFAULT_SEPARATOR = '_';
+const DEFAULT_MAX_DEPTH = 4;
+/** A plain (non-array, non-Date) object — the only thing we recurse into. */
+function isPlainObject(value) {
+    return value !== null
+        && typeof value === 'object'
+        && !Array.isArray(value)
+        && !(value instanceof Date);
+}
+/**
+ * Returns true if `raw` contains at least one nested plain-object value — i.e. flattening would
+ * change it. Cheap top-level check; lets callers skip the allocation for the flat-record common case.
+ */
+export function hasNestedObject(raw) {
+    for (const v of Object.values(raw)) {
+        if (isPlainObject(v))
+            return true;
+    }
+    return false;
+}
+/**
+ * Flatten a record's nested plain-objects into `parent<sep>child` scalar keys. Pure; returns a new
+ * object. A record with no nested objects is returned shallow-copied + unchanged in shape.
+ */
+export function flattenRecord(raw, opts = {}) {
+    const sep = opts.Separator ?? DEFAULT_SEPARATOR;
+    const maxDepth = opts.MaxDepth ?? DEFAULT_MAX_DEPTH;
+    const out = {};
+    const put = (key, value) => {
+        if (Object.prototype.hasOwnProperty.call(out, key)) {
+            opts.onCollision?.(key);
+            return; // first value wins
+        }
+        out[key] = value;
+    };
+    const recurse = (obj, prefix, depth) => {
+        for (const [k, v] of Object.entries(obj)) {
+            const key = prefix ? `${prefix}${sep}${k}` : k;
+            if (isPlainObject(v) && depth < maxDepth) {
+                recurse(v, key, depth + 1);
+            }
+            else {
+                put(key, v);
+            }
+        }
+    };
+    recurse(raw, '', 0);
+    return out;
+}
+//# sourceMappingURL=RecordFlatten.js.map

package/dist/RecordFlatten.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordFlatten.js","sourceRoot":"","sources":["../src/RecordFlatten.ts"],"names":[],"mappings":"AAuCA,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAC9B,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B,6EAA6E;AAC7E,SAAS,aAAa,CAAC,KAAc;IACjC,OAAO,KAAK,KAAK,IAAI;WACd,OAAO,KAAK,KAAK,QAAQ;WACzB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;WACrB,CAAC,CAAC,KAAK,YAAY,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAA4B;IACxD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,IAAI,aAAa,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;IACtC,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CACzB,GAA4B,EAC5B,OAAuB,EAAE;IAEzB,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,iBAAiB,CAAC;IAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACpD,MAAM,GAAG,GAA4B,EAAE,CAAC;IAExC,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,KAAc,EAAQ,EAAE;QAC9C,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;YACjD,IAAI,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;YACxB,OAAO,CAAC,mBAAmB;QAC/B,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrB,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,GAA4B,EAAE,MAAc,EAAE,KAAa,EAAQ,EAAE;QAClF,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAC/C,IAAI,aAAa,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;gBACvC,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAC/B,CAAC;iBAAM,CAAC;gBACJ,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAChB,CAAC;QACL,CAAC;IACL,CAAC,CAAC;IAEF,OAAO,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IACpB,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/StreamingDiscovery.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Time-bounded streaming discovery (the final discovery abstraction).
+ *
+ * Stage-2 of `DiscoverFields` for sources with no describe endpoint: stream the source's actual
+ * records (read-only — no save, no ack) and, in ONE pass, accumulate two things:
+ *   1. the full COLUMN corpus (every key seen) + a bounded sample of values per key for typing, and
+ *   2. per-column UNIQUENESS / NULL statistics — the evidence a data-informed (not nominal) PK
+ *      decision is made from.
+ *
+ * It stops when the stream is exhausted OR a TIME BUDGET is hit — whichever comes first — and
+ * returns whatever it gathered. More rows → stronger claims; the budget guarantees discovery never
+ * runs away. Memory stays bounded regardless of row count: only the key-set + capped per-key
+ * sample-values + a capped distinct-set per key are retained (never the rows themselves).
+ *
+ * Pure + clock-injectable, so it's deterministically testable. Reuses {@link inferColumnTypeFromSamples}.
+ */
+import { type InferredColumnType } from './CustomColumnPromotion.js';
+export interface StreamDiscoveryOptions {
+    /** Wall-clock budget; once exceeded, stop and use what was gathered. Default 30s. */
+    TimeBudgetMs?: number;
+    /** Max sample values retained per column for type inference. Default 10. */
+    SampleValueCap?: number;
+    /**
+     * Max distinct values tracked per column before we give up proving uniqueness exactly. Beyond
+     * this the column is flagged `DistinctCapped` (uniqueness no longer provable from this scan, so
+     * it can't be a confident PK candidate). Bounds memory. Default 100000.
+     */
+    MaxDistinctTracked?: number;
+    /**
+     * Max rows whose per-cell value-hashes are retained for COMPOSITE-key discovery. Bounded memory
+     * (cap × columns) — never the raw values. Default 2000: enough for significance, cheap on CPU/RAM.
+     */
+    CompositeSampleRowCap?: number;
+    /** Injectable clock (for tests). Defaults to Date.now. */
+    Now?: () => number;
+}
+/** Per-column evidence gathered from the stream. */
+export interface DiscoveredColumnStat {
+    Key: string;
+    /** Rows where the key was present + non-null. */
+    Occurrences: number;
+    /** Total rows scanned. */
+    TotalRows: number;
+    /** Distinct non-null values seen (exact, up to the cap). */
+    DistinctNonNull: number;
+    /** True if the distinct-cap was hit → uniqueness NOT provable from this scan. */
+    DistinctCapped: boolean;
+    /** Bounded sample of observed values (for type inference). */
+    SampleValues: unknown[];
+    /** Generously-bounded inferred type (both dialects). */
+    Inferred: InferredColumnType;
+}
+export interface StreamDiscoveryResult {
+    Columns: DiscoveredColumnStat[];
+    RowsScanned: number;
+    /** Why the scan ended — surfaced so a time-capped (partial) corpus is never silently treated as complete. */
+    StoppedReason: 'exhausted' | 'time-budget';
+    /**
+     * Bounded per-row cell-hash sample (column → stable value-hash for the row's non-null cells),
+     * capped at {@link StreamDiscoveryOptions.CompositeSampleRowCap}. Feeds composite-key discovery
+     * ({@link pickCompositeKeyFromStats}) without retaining raw values or every row.
+     */
+    RowSamples: Array<Record<string, string>>;
+}
+/**
+ * Streams records (sync or async iterable), accumulating the column corpus + uniqueness/null stats
+ * until exhaustion or the time budget. Read-only; the caller supplies whatever read-only fetch
+ * yields the records (no save, no ack happens here).
+ */
+export declare function discoverFromStream(records: AsyncIterable<Record<string, unknown>> | Iterable<Record<string, unknown>>, opts?: StreamDiscoveryOptions): Promise<StreamDiscoveryResult>;
+/** Options for the data-informed PK pick. */
+export interface PkPickOptions {
+    /**
+     * Minimum rows scanned before a unique+non-null column is trusted as a PK (statistical
+     * significance — uniqueness over a tiny sample is not evidence). Default 50.
+     */
+    MinRowsForSignificance?: number;
+    /** A naming-rank tiebreaker, used ONLY to choose among multiple equally-unique columns. */
+    NameRank?: (columnName: string) => number;
+    /**
+     * Whether the scan that produced these stats SAW THE WHOLE STREAM (#A4). Default true. When false
+     * (the scan was time-budget-truncated), "non-null on every row + near-unique" was observed over only a
+     * PARTIAL prefix — a column null/duplicated solely in the unscanned tail would look like a clean key.
+     * So on a truncated scan the SOFT best-available fallback demands FULL prefix-uniqueness (not merely
+     * near-unique) and annotates the verdict that it must be re-verified on full data.
+     */
+    ScanComplete?: boolean;
+}
+/** The data-informed PK verdict (statistics-first). */
+export interface PkStatVerdict {
+    /** The chosen PK column, or null when no column clears the bar. */
+    Field: string | null;
+    /** All columns that are provably unique + non-null over enough rows (the candidate set). */
+    UniqueCandidates: string[];
+    /** True when there were ≥2 unique candidates and naming couldn't break the tie → defer to the LLM tiebreaker. */
+    AmbiguousForLLM: boolean;
+    Reason: string;
+}
+/**
+ * Statistics-first PK pick from streamed evidence. A column is a candidate ONLY if it is, over a
+ * statistically meaningful number of rows, **non-null on every row** AND **all-distinct** (and its
+ * uniqueness was provable — the distinct-cap wasn't hit). One candidate → that's the PK (p<0.05:
+ * all-distinct over a large N is not chance). Several candidates → naming breaks the tie if it can;
+ * otherwise it's flagged ambiguous for the LLM tiebreaker. Zero candidates → no PK (no fabrication).
+ */
+export declare function pickPrimaryKeyFromStats(columns: DiscoveredColumnStat[], opts?: PkPickOptions): PkStatVerdict;
+/** The composite-key verdict — a provable multi-column identity, or null when none exists in the sample. */
+export interface CompositePkVerdict {
+    /** The composite key column set (≥2 columns), or null when no provable combination was found. */
+    Fields: string[] | null;
+    Reason: string;
+}
+/**
+ * COMPOSITE PK pick from streamed evidence — for objects whose identity is a multi-column combination
+ * (no single column is unique). Statistics-first + provable-only, same philosophy as the single-column
+ * pick: it emits a column set ONLY when that set is provably unique + fully-non-null over a significant
+ * sample; otherwise null (→ the caller uses the content-hash identity floor). No naming guesses.
+ *
+ * Cost is GREEDY, not combinatorial — O(R·C), never the 2^C subset blow-up:
+ *   1. Candidate columns = those non-null on EVERY row (a null component can't be part of a stable key),
+ *      sorted by cardinality desc (so uniqueness is reached in the fewest columns).
+ *   2. Greedily add the next-highest-cardinality candidate and test combined-tuple uniqueness over the
+ *      cached per-row cell-hashes. First column set whose tuples are all-distinct over the sample wins.
+ * Greedy finds *a* provable unique combination (sufficient for identity/dedup), not necessarily the
+ * globally-minimal one — minimality is a nice-to-have the identity path doesn't need. A significance
+ * gate (MinRowsForSignificance) keeps a small-sample "uniqueness" from being a fluke.
+ */
+export declare function pickCompositeKeyFromStats(columns: DiscoveredColumnStat[], rowSamples: Array<Record<string, string>>, opts?: PkPickOptions): CompositePkVerdict;
+/** The unified key verdict — the chosen identity columns (1 = single PK, ≥2 = composite), or null. */
+export interface KeyVerdict {
+    Fields: string[] | null;
+    Reason: string;
+}
+/**
+ * Provable-only key pick — single OR composite, in ONE pass. Picks the BEST contender at each subset
+ * size (1, 2, 3 …), then takes the SMALLEST size whose best contender is a provable key (minimality:
+ * a 1-col key beats a 2-col beats a 3-col). "Best" + "is it a key" are the same Chao1 saturation test
+ * ({@link subsetKeyness}) applied to the subset's combined tuple — no arbitrary distinct-ratio. If NO
+ * size yields a provable key, returns null (the object is honestly keyless — never a fabricated key).
+ */
+export declare function pickKeyFromStats(columns: DiscoveredColumnStat[], rowSamples: Array<Record<string, string>>, opts?: PkPickOptions & {
+    MaxKeyColumns?: number;
+    MaxCandidates?: number;
+}): KeyVerdict;
+//# sourceMappingURL=StreamingDiscovery.d.ts.map

package/dist/StreamingDiscovery.d.ts.map

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