@ai-sdlc/orchestrator 0.10.0 → 0.14.0

package/dist/signal-ingestion/clustering.d.ts

@@ -0,0 +1,200 @@
+/**
+ * RFC-0030 Phase 3 — Signal clustering.
+ *
+ * Clusters classified signals into demand themes using one of two algorithms:
+ *
+ *   1. **BM25 (default)** — pairwise BM25 similarity over signal payloads with
+ *      greedy single-linkage agglomerative clustering at `similarityThreshold`.
+ *      Deterministic, model-independent, interpretable. Matches PPA v1.2 Sα₁
+ *      Layer 2 structural-scoring convention. Requires zero embedding
+ *      infrastructure — AC #6 graceful-degradation contract.
+ *
+ *   2. **Embedding (optional)** — when `clustering.algorithm === 'embedding'`
+ *      AND an `EmbeddingAdapter` (RFC-0019) is supplied via
+ *      `ClusterSignalsOptions.embeddingAdapter`, the clusterer embeds each
+ *      signal payload via the adapter and clusters using cosine similarity.
+ *      Falls back to BM25 with a logged warning when the algorithm is
+ *      `'embedding'` but no adapter is wired — never silently swaps semantics.
+ *
+ * **Cluster IDs are deterministic**: SHA-256 of the sorted set of member
+ * `sourceId`s, prefixed with `cluster:`. Re-running clustering on the same
+ * input produces the same IDs — auditable by construction.
+ *
+ * **Aggregated cluster metadata** per RFC-0030 §7:
+ *   - `signalCount`, `uniqueSources`, `oldestSignalAt`, `newestSignalAt`
+ *   - `icpMatchRate` — fraction of `strong`-resonance member signals
+ *   - `churnCorrelation` — fraction of `churned`-tier member signals
+ *   - `tier1SignalCount` / `tier2SignalCount` — counts by adapter tier, for
+ *     Phase 4's Tier 2 significance threshold consumer
+ *   - `aggregateRecencyDecay` — mean recency decay across members
+ *
+ * **Out of scope for Phase 3** (intentional):
+ *   - `saResonance` — left undefined; computed in Phase 4 against the Soul DID
+ *   - `topSummary` — left undefined; cluster summarisation is post-MVP
+ *
+ * @module signal-ingestion/clustering
+ */
+import type { EmbeddingAdapter } from '../embedding/types.js';
+import type { ClusteredSignalInput } from './clustering-types.js';
+import type { SignalIngestionConfig } from './config.js';
+import type { CustomerTier, RawSignal, SignalTier } from './types.js';
+export type { ClusteredSignalInput } from './clustering-types.js';
+/**
+ * Algorithm that was actually used to produce a clustering result.
+ * Exposed for observability — operators can audit whether embedding was
+ * configured but fell back to BM25 because no adapter was wired.
+ */
+export type ClusteringAlgorithmUsed = 'bm25' | 'embedding';
+/**
+ * Aggregated demand cluster output per RFC-0030 §7.
+ *
+ * Member signals are stored as `ClusteredSignalInput` (the same shape the
+ * clusterer receives) so downstream Phase 4/5 consumers retain access to the
+ * classification axes (tier, ICP resonance, recency decay) without re-running
+ * the classifier.
+ */
+export interface DemandCluster {
+    /** Deterministic SHA-256-derived ID; prefixed with `cluster:`. */
+    clusterId: string;
+    /** Member signals in input order. */
+    members: ClusteredSignalInput[];
+    /** Total member count. */
+    signalCount: number;
+    /** Number of distinct source adapter names across members. */
+    uniqueSources: number;
+    /** Number of Tier 1 (direct) signals in the cluster. */
+    tier1SignalCount: number;
+    /** Number of Tier 2 (ambient) signals in the cluster. */
+    tier2SignalCount: number;
+    /** Oldest member `sourceTimestamp`. */
+    oldestSignalAt: Date;
+    /** Newest member `sourceTimestamp`. */
+    newestSignalAt: Date;
+    /** Fraction of members with `icpResonance === 'strong'`. Range [0, 1]. */
+    icpMatchRate: number;
+    /** Fraction of members with `customerTier === 'churned'`. Range [0, 1]. */
+    churnCorrelation: number;
+    /** Mean recency decay across members. Range [0, 1]. */
+    aggregateRecencyDecay: number;
+    /**
+     * SA resonance against the Soul DID — computed in Phase 4 (RFC-0030 §9).
+     * Always `undefined` from Phase 3.
+     */
+    saResonance?: number;
+    /**
+     * Cluster-theme summary — generated by LLM or adapter in a future phase.
+     * Always `undefined` from Phase 3.
+     */
+    topSummary?: string;
+}
+/**
+ * Result of clustering a batch of classified signals.
+ */
+export interface ClusteringResult {
+    clusters: DemandCluster[];
+    /** Algorithm actually used (may differ from config when adapter missing). */
+    algorithmUsed: ClusteringAlgorithmUsed;
+    /**
+     * Set when `clustering.algorithm === 'embedding'` but no adapter was wired
+     * (graceful fallback to BM25 per AC #6).
+     */
+    fallbackReason?: 'embedding-adapter-missing' | 'embedding-adapter-unavailable';
+}
+/**
+ * Options for `clusterSignals()`.
+ */
+export interface ClusterSignalsOptions {
+    /**
+     * Resolved signal ingestion configuration. Defaults to the framework
+     * default (`bm25` + `similarityThreshold: 0.6`).
+     */
+    config?: SignalIngestionConfig;
+    /**
+     * Embedding adapter for the optional `embedding` algorithm. Resolved per
+     * RFC-0019 § registry semantics by the caller (read the `embedding-config.yaml`
+     * provider field; pass the resolved adapter here). Ignored when the
+     * configured algorithm is `bm25`. When the configured algorithm is
+     * `embedding` but this field is `undefined`, the clusterer logs a fallback
+     * and uses BM25 (graceful degradation per AC #6).
+     */
+    embeddingAdapter?: EmbeddingAdapter;
+    /**
+     * Optional override of the consumer label sent to the embedding adapter
+     * for cost attribution. Defaults to `'rfc-0030-clustering'`.
+     */
+    embeddingConsumerLabel?: string;
+    /**
+     * Optional hook invoked when the clusterer falls back from embedding to
+     * BM25. Defaults to a no-op (callers wire console.warn / structured logger).
+     */
+    onFallback?: (info: {
+        reason: 'embedding-adapter-missing' | 'embedding-adapter-unavailable';
+        message: string;
+    }) => void;
+}
+/**
+ * Cluster a batch of classified signals into demand themes.
+ *
+ * Algorithm selection (per `config.clustering.algorithm`):
+ *   - `'bm25'` (default) — pairwise BM25 similarity, greedy single-linkage.
+ *   - `'embedding'` — requires `options.embeddingAdapter`; falls back to BM25
+ *     with `fallbackReason: 'embedding-adapter-missing'` when not supplied
+ *     (AC #6 graceful degradation).
+ *
+ * Threshold: `config.clustering.similarityThreshold` (default 0.6).
+ *
+ * Cluster IDs are deterministic — re-running with the same inputs yields the
+ * same IDs by SHA-256 of the sorted member `sourceId` set.
+ */
+export declare function clusterSignals(signals: ClusteredSignalInput[], options?: ClusterSignalsOptions): Promise<ClusteringResult>;
+/**
+ * Cosine similarity between two equal-length numeric vectors.
+ * Returns 0 when either vector has zero magnitude.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Compute a deterministic SHA-256-derived cluster ID from the sorted set of
+ * member sourceIds. The first 24 hex chars of the digest are appended to a
+ * `cluster:` prefix — collision-resistant within any realistic ingestion
+ * window while remaining compact for log/event readability.
+ */
+export declare function computeClusterId(sortedSourceIds: string[]): string;
+/**
+ * Cluster signals with per-region segregation per RFC-0030 v0.3 OQ-13.3
+ * clustering enforcement point. Partitions the input by `signal.region`
+ * (via `partitionSignalsByRegion`) and runs `clusterSignals()` once per
+ * partition, concatenating the per-partition `DemandCluster[]` outputs so
+ * cross-region cluster merge is structurally impossible.
+ *
+ * **Decision boundary**: when `partitionByRegion` is `false` (caller-supplied
+ * or the active regime doesn't require segregation via
+ * `clusterRequiresSegregation()`), this function falls through to a single
+ * `clusterSignals()` call — zero overhead for adopters with no residency
+ * regime declared.
+ *
+ * The returned `ClusteringResult.algorithmUsed` is the algorithm used by the
+ * FIRST partition (all partitions use the same algorithm; `fallbackReason`
+ * surfaces if any partition fell back from embedding to BM25). When
+ * `partitionByRegion: true`, the function additionally returns
+ * `regionPartitions: { region: clusterCount }` for audit / cost-attribution
+ * surfacing.
+ */
+export interface ClusterSignalsWithResidencyOptions extends ClusterSignalsOptions {
+    /**
+     * When true, signals are partitioned by `region` before similarity
+     * computation. Defaults to `false` (caller decides based on the active
+     * regime declaration via `clusterRequiresSegregation()`).
+     */
+    partitionByRegion?: boolean;
+}
+export interface ClusteringResultWithResidency extends ClusteringResult {
+    /**
+     * Per-region cluster count breakdown. Only populated when
+     * `partitionByRegion: true`. Region keys lowercased; `__unspecified` is the
+     * bucket for signals with no `region` tag.
+     */
+    regionPartitions?: Record<string, number>;
+}
+export declare function clusterSignalsWithResidency(signals: ClusteredSignalInput[], options?: ClusterSignalsWithResidencyOptions): Promise<ClusteringResultWithResidency>;
+export type { CustomerTier, RawSignal, SignalTier };
+//# sourceMappingURL=clustering.d.ts.map

package/dist/signal-ingestion/clustering.js

@@ -0,0 +1,413 @@
+/**
+ * RFC-0030 Phase 3 — Signal clustering.
+ *
+ * Clusters classified signals into demand themes using one of two algorithms:
+ *
+ *   1. **BM25 (default)** — pairwise BM25 similarity over signal payloads with
+ *      greedy single-linkage agglomerative clustering at `similarityThreshold`.
+ *      Deterministic, model-independent, interpretable. Matches PPA v1.2 Sα₁
+ *      Layer 2 structural-scoring convention. Requires zero embedding
+ *      infrastructure — AC #6 graceful-degradation contract.
+ *
+ *   2. **Embedding (optional)** — when `clustering.algorithm === 'embedding'`
+ *      AND an `EmbeddingAdapter` (RFC-0019) is supplied via
+ *      `ClusterSignalsOptions.embeddingAdapter`, the clusterer embeds each
+ *      signal payload via the adapter and clusters using cosine similarity.
+ *      Falls back to BM25 with a logged warning when the algorithm is
+ *      `'embedding'` but no adapter is wired — never silently swaps semantics.
+ *
+ * **Cluster IDs are deterministic**: SHA-256 of the sorted set of member
+ * `sourceId`s, prefixed with `cluster:`. Re-running clustering on the same
+ * input produces the same IDs — auditable by construction.
+ *
+ * **Aggregated cluster metadata** per RFC-0030 §7:
+ *   - `signalCount`, `uniqueSources`, `oldestSignalAt`, `newestSignalAt`
+ *   - `icpMatchRate` — fraction of `strong`-resonance member signals
+ *   - `churnCorrelation` — fraction of `churned`-tier member signals
+ *   - `tier1SignalCount` / `tier2SignalCount` — counts by adapter tier, for
+ *     Phase 4's Tier 2 significance threshold consumer
+ *   - `aggregateRecencyDecay` — mean recency decay across members
+ *
+ * **Out of scope for Phase 3** (intentional):
+ *   - `saResonance` — left undefined; computed in Phase 4 against the Soul DID
+ *   - `topSummary` — left undefined; cluster summarisation is post-MVP
+ *
+ * @module signal-ingestion/clustering
+ */
+import { createHash } from 'node:crypto';
+import { DEFAULT_SIGNAL_INGESTION_CONFIG } from './config.js';
+import { tokenize } from './classifier.js';
+// ── Main entry point ────────────────────────────────────────────────────────
+/**
+ * Cluster a batch of classified signals into demand themes.
+ *
+ * Algorithm selection (per `config.clustering.algorithm`):
+ *   - `'bm25'` (default) — pairwise BM25 similarity, greedy single-linkage.
+ *   - `'embedding'` — requires `options.embeddingAdapter`; falls back to BM25
+ *     with `fallbackReason: 'embedding-adapter-missing'` when not supplied
+ *     (AC #6 graceful degradation).
+ *
+ * Threshold: `config.clustering.similarityThreshold` (default 0.6).
+ *
+ * Cluster IDs are deterministic — re-running with the same inputs yields the
+ * same IDs by SHA-256 of the sorted member `sourceId` set.
+ */
+export async function clusterSignals(signals, options = {}) {
+    const config = options.config ?? DEFAULT_SIGNAL_INGESTION_CONFIG;
+    const clustering = config.clustering;
+    const threshold = clustering.similarityThreshold;
+    if (signals.length === 0) {
+        return { clusters: [], algorithmUsed: clustering.algorithm };
+    }
+    let algorithmUsed = clustering.algorithm;
+    let fallbackReason;
+    // Resolve algorithm — graceful fallback when embedding is configured but
+    // no adapter is wired (AC #6).
+    let similarityMatrix;
+    if (clustering.algorithm === 'embedding') {
+        if (!options.embeddingAdapter) {
+            algorithmUsed = 'bm25';
+            fallbackReason = 'embedding-adapter-missing';
+            options.onFallback?.({
+                reason: 'embedding-adapter-missing',
+                message: "clustering.algorithm='embedding' configured but no embeddingAdapter supplied; falling back to BM25",
+            });
+            similarityMatrix = computeBm25Matrix(signals);
+        }
+        else {
+            const availability = await options.embeddingAdapter.isAvailable();
+            if (!availability.available) {
+                algorithmUsed = 'bm25';
+                fallbackReason = 'embedding-adapter-unavailable';
+                options.onFallback?.({
+                    reason: 'embedding-adapter-unavailable',
+                    message: `embedding adapter '${options.embeddingAdapter.name}' is unavailable (${availability.reason ?? 'unknown'}); falling back to BM25`,
+                });
+                similarityMatrix = computeBm25Matrix(signals);
+            }
+            else {
+                similarityMatrix = await computeEmbeddingMatrix(signals, options.embeddingAdapter, options.embeddingConsumerLabel ?? 'rfc-0030-clustering');
+            }
+        }
+    }
+    else {
+        similarityMatrix = computeBm25Matrix(signals);
+    }
+    const clusterMembership = singleLinkageCluster(signals.length, similarityMatrix, threshold);
+    const clusters = buildDemandClusters(signals, clusterMembership);
+    return { clusters, algorithmUsed, fallbackReason };
+}
+// ── BM25 similarity matrix ──────────────────────────────────────────────────
+/**
+ * Compute pairwise normalised BM25 similarity over signal payloads.
+ *
+ * BM25 (k1=1.5, b=0.75) is the standard PPA Sα₁ Layer 2 scoring choice. We
+ * normalise each pairwise score by the self-score of the shorter document so
+ * the result lives in [0, 1] and is symmetric around the diagonal.
+ *
+ * Returns an N×N matrix; cell [i][j] is the symmetric similarity. The
+ * diagonal is set to 1.0.
+ */
+function computeBm25Matrix(signals) {
+    const N = signals.length;
+    const K1 = 1.5;
+    const B = 0.75;
+    const tokens = signals.map((s) => tokenize(s.signal.payload));
+    const tfs = tokens.map((toks) => termFrequency(toks));
+    const docLens = tokens.map((toks) => toks.length);
+    const totalLen = docLens.reduce((a, b) => a + b, 0);
+    const avgDocLen = N > 0 ? totalLen / N : 0;
+    // Pre-compute IDF per term across the corpus (collection of payloads).
+    const allTerms = new Set();
+    for (const tf of tfs)
+        for (const term of tf.keys())
+            allTerms.add(term);
+    const idfMap = new Map();
+    for (const term of allTerms) {
+        let df = 0;
+        for (const tf of tfs)
+            if ((tf.get(term) ?? 0) > 0)
+                df++;
+        idfMap.set(term, Math.log((N - df + 0.5) / (df + 0.5) + 1));
+    }
+    const scoreDocWithQuery = (docIdx, queryTerms) => {
+        const tf = tfs[docIdx];
+        const docLen = docLens[docIdx];
+        let score = 0;
+        for (const term of new Set(queryTerms)) {
+            const freq = tf.get(term) ?? 0;
+            if (freq === 0)
+                continue;
+            const termIdf = idfMap.get(term) ?? 0;
+            const numerator = freq * (K1 + 1);
+            const denominator = freq + K1 * (1 - B + B * (docLen / Math.max(avgDocLen, 1)));
+            score += termIdf * (numerator / denominator);
+        }
+        return score;
+    };
+    // Self-scores for normalisation.
+    const selfScores = signals.map((_, i) => scoreDocWithQuery(i, tokens[i]));
+    const matrix = Array.from({ length: N }, () => new Array(N).fill(0));
+    for (let i = 0; i < N; i++) {
+        matrix[i][i] = 1.0;
+        for (let j = i + 1; j < N; j++) {
+            // Score doc j with doc i's terms, doc i with doc j's terms.
+            const sij = scoreDocWithQuery(j, tokens[i]);
+            const sji = scoreDocWithQuery(i, tokens[j]);
+            // Normalise each direction by the queried doc's self-score; then average
+            // for symmetry. Avoids division-by-zero when a payload is empty.
+            const normIJ = selfScores[j] > 0 ? sij / selfScores[j] : 0;
+            const normJI = selfScores[i] > 0 ? sji / selfScores[i] : 0;
+            const sim = Math.min(1, (normIJ + normJI) / 2);
+            matrix[i][j] = sim;
+            matrix[j][i] = sim;
+        }
+    }
+    return matrix;
+}
+function termFrequency(tokens) {
+    const tf = new Map();
+    for (const t of tokens)
+        tf.set(t, (tf.get(t) ?? 0) + 1);
+    return tf;
+}
+// ── Embedding similarity matrix ─────────────────────────────────────────────
+/**
+ * Embed each signal payload via the supplied adapter and compute pairwise
+ * cosine similarity.
+ *
+ * Uses `embedBatch()` when available for efficiency; falls back to a sequential
+ * `embed()` loop otherwise. Per-call cost is attributed to `consumerLabel`
+ * (default `'rfc-0030-clustering'`) per RFC-0019 OQ-6.
+ */
+async function computeEmbeddingMatrix(signals, adapter, consumerLabel) {
+    const N = signals.length;
+    const payloads = signals.map((s) => s.signal.payload);
+    let vectors;
+    if (adapter.embedBatch) {
+        vectors = await adapter.embedBatch(payloads, consumerLabel);
+    }
+    else {
+        vectors = [];
+        for (const text of payloads) {
+            vectors.push(await adapter.embed(text, consumerLabel));
+        }
+    }
+    const matrix = Array.from({ length: N }, () => new Array(N).fill(0));
+    for (let i = 0; i < N; i++) {
+        matrix[i][i] = 1.0;
+        for (let j = i + 1; j < N; j++) {
+            const sim = cosineSimilarity(vectors[i], vectors[j]);
+            matrix[i][j] = sim;
+            matrix[j][i] = sim;
+        }
+    }
+    return matrix;
+}
+/**
+ * Cosine similarity between two equal-length numeric vectors.
+ * Returns 0 when either vector has zero magnitude.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`cosineSimilarity: vector length mismatch (${a.length} vs ${b.length})`);
+    }
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        const va = a[i];
+        const vb = b[i];
+        dot += va * vb;
+        normA += va * va;
+        normB += vb * vb;
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+// ── Single-linkage agglomerative clustering ─────────────────────────────────
+/**
+ * Greedy single-linkage agglomerative clustering using Union-Find.
+ *
+ * Two signals join the same cluster whenever their pairwise similarity meets
+ * or exceeds `threshold`. This is the simplest correct connect-the-dots
+ * algorithm: stable, deterministic, no parameters to tune beyond `threshold`,
+ * O(N^2) which is acceptable for the v1 ingestion window (operators typically
+ * cluster batches of 10²–10³ signals per pipeline-load).
+ *
+ * Returns an array `parent[i]` giving the cluster representative for signal i.
+ */
+function singleLinkageCluster(n, sim, threshold) {
+    const parent = Array.from({ length: n }, (_, i) => i);
+    const find = (x) => {
+        let root = x;
+        while (parent[root] !== root)
+            root = parent[root];
+        // Path compression.
+        let cur = x;
+        while (parent[cur] !== root) {
+            const next = parent[cur];
+            parent[cur] = root;
+            cur = next;
+        }
+        return root;
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra === rb)
+            return;
+        // Union by lower index — keeps cluster representative deterministic.
+        if (ra < rb)
+            parent[rb] = ra;
+        else
+            parent[ra] = rb;
+    };
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            if (sim[i][j] >= threshold) {
+                union(i, j);
+            }
+        }
+    }
+    return parent.map((_, i) => find(i));
+}
+// ── DemandCluster assembly ──────────────────────────────────────────────────
+/**
+ * Assemble `DemandCluster` records from per-signal membership.
+ * Aggregates tier/ICP/recency/timestamp metadata + computes deterministic IDs.
+ *
+ * Output ordering: clusters are sorted by `clusterId` (sha256-derived hex,
+ * lexicographic) so the result is deterministic regardless of input order.
+ */
+function buildDemandClusters(signals, membership) {
+    const byRoot = new Map();
+    for (let i = 0; i < signals.length; i++) {
+        const root = membership[i];
+        let bucket = byRoot.get(root);
+        if (!bucket) {
+            bucket = [];
+            byRoot.set(root, bucket);
+        }
+        bucket.push(signals[i]);
+    }
+    const clusters = [];
+    for (const members of byRoot.values()) {
+        clusters.push(assembleCluster(members));
+    }
+    // Sort clusters by deterministic clusterId for stable output ordering.
+    clusters.sort((a, b) => a.clusterId.localeCompare(b.clusterId));
+    return clusters;
+}
+function assembleCluster(members) {
+    const sourceIds = members.map((m) => m.signal.sourceId).sort();
+    const clusterId = computeClusterId(sourceIds);
+    let oldestMs = Infinity;
+    let newestMs = -Infinity;
+    let strongCount = 0;
+    let churnedCount = 0;
+    let tier1 = 0;
+    let tier2 = 0;
+    let recencySum = 0;
+    const adapterNames = new Set();
+    for (const m of members) {
+        const ts = m.signal.sourceTimestamp.getTime();
+        if (ts < oldestMs)
+            oldestMs = ts;
+        if (ts > newestMs)
+            newestMs = ts;
+        if (m.icpResonance === 'strong')
+            strongCount++;
+        if (m.customerTier === 'churned')
+            churnedCount++;
+        const adapterTier = resolveAdapterTier(m.signal, m.adapterTier);
+        if (adapterTier === 1)
+            tier1++;
+        else
+            tier2++;
+        recencySum += m.recencyDecay;
+        const adapterName = m.signal.metadata?.['adapterName'] ?? 'unknown';
+        adapterNames.add(adapterName);
+    }
+    const n = members.length;
+    return {
+        clusterId,
+        members: [...members],
+        signalCount: n,
+        uniqueSources: adapterNames.size,
+        tier1SignalCount: tier1,
+        tier2SignalCount: tier2,
+        oldestSignalAt: new Date(oldestMs),
+        newestSignalAt: new Date(newestMs),
+        icpMatchRate: strongCount / n,
+        churnCorrelation: churnedCount / n,
+        aggregateRecencyDecay: recencySum / n,
+    };
+}
+/**
+ * Resolve the adapter tier for a member signal. Prefers the explicit
+ * `adapterTier` field on the input (most-authoritative); falls back to
+ * `signal.metadata.adapterTier` for adapters that surface the value via
+ * metadata; defaults to Tier 1 (matches the classifier convention).
+ */
+function resolveAdapterTier(signal, explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    const fromMetadata = signal.metadata?.['adapterTier'];
+    if (fromMetadata === 1 || fromMetadata === 2)
+        return fromMetadata;
+    return 1;
+}
+/**
+ * Compute a deterministic SHA-256-derived cluster ID from the sorted set of
+ * member sourceIds. The first 24 hex chars of the digest are appended to a
+ * `cluster:` prefix — collision-resistant within any realistic ingestion
+ * window while remaining compact for log/event readability.
+ */
+export function computeClusterId(sortedSourceIds) {
+    const hash = createHash('sha256');
+    for (const id of sortedSourceIds) {
+        hash.update(id);
+        hash.update(''); // null-byte delimiter; ensures ['a', 'bc'] !== ['ab', 'c']
+    }
+    return `cluster:${hash.digest('hex').slice(0, 24)}`;
+}
+export async function clusterSignalsWithResidency(signals, options = {}) {
+    const partitionByRegion = options.partitionByRegion ?? false;
+    if (!partitionByRegion) {
+        return clusterSignals(signals, options);
+    }
+    // Lazy-import to avoid a clustering -> residency import cycle.
+    const { partitionSignalsByRegion } = await import('./residency.js');
+    const partitions = partitionSignalsByRegion(signals);
+    const allClusters = [];
+    const regionPartitions = {};
+    let algorithmUsed = 'bm25';
+    let fallbackReason;
+    for (const [region, partitionSignals] of partitions) {
+        if (partitionSignals.length === 0)
+            continue;
+        // Strip partitionByRegion from options when delegating so we don't
+        // recurse (clusterSignals doesn't read this field anyway, but defensive).
+        const { partitionByRegion: _ignored, ...delegateOptions } = options;
+        const result = await clusterSignals(partitionSignals, delegateOptions);
+        allClusters.push(...result.clusters);
+        regionPartitions[region] = result.clusters.length;
+        algorithmUsed = result.algorithmUsed;
+        if (result.fallbackReason !== undefined)
+            fallbackReason = result.fallbackReason;
+    }
+    // Sort across all partitions by deterministic clusterId so the output
+    // ordering matches non-partitioned clusterSignals semantics.
+    allClusters.sort((a, b) => a.clusterId.localeCompare(b.clusterId));
+    const out = {
+        clusters: allClusters,
+        algorithmUsed,
+        regionPartitions,
+    };
+    if (fallbackReason !== undefined)
+        out.fallbackReason = fallbackReason;
+    return out;
+}
+//# sourceMappingURL=clustering.js.map