circle-ir-ai 2.22.0 → 2.26.0

package/dist/cluster/cluster.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Cluster Layer — Foundation
+ *
+ * Top-of-pipeline file clustering (cognium-ai#154, P4 of epic #155).
+ * Groups files in a repo by their static structural fingerprint (CK
+ * metrics + import/annotation set) so downstream passes can apply
+ * per-cluster policy bundles ("library bootstrap" vs "controller
+ * surface" vs "data-access shim") instead of one-size-fits-all
+ * discovery/verification.
+ *
+ * This file ships the **foundation only**:
+ *   - `extractClusterVector(circleIr)` — pull CK vector from analyze() output
+ *   - `clusterFiles(inputs)` — deterministic k-medoids, returns
+ *     `Map<filePath, clusterId>` per acceptance #1
+ *   - distance functions (Euclidean on normalized CK + Jaccard on
+ *     imports/annotations) + the k-medoids loop itself
+ *   - `ClusterPolicy` type so downstream wiring can land in a
+ *     follow-up without re-declaring shape
+ *
+ * **Explicitly out of scope here** (tracked as follow-up tickets):
+ *   - `meta.json.files[*].clusterId` field — needs scan-emit schema
+ *     migration (Acceptance #3)
+ *   - top-100 HIGH/CRIT reduction validation (Acceptance #4)
+ *   - CWE-Bench-Java regression check (Acceptance #5)
+ *   - `--cluster-policy <profile>` CLI flag in cognium-ai
+ *     (Acceptance #6)
+ *   - LLM cluster labeling pass (optional future per the issue)
+ *
+ * The split is deliberate: P1-P3 of epic #155 were single-shot
+ * cache wins; P4's policy bundles + the two benchmark validation
+ * gates need empirical tuning that can't complete in a single
+ * release cycle. Foundation-first lets cognium-ai start consuming
+ * `clusterFiles()` as an opaque grouping signal while the policy
+ * resolver is iterated separately.
+ *
+ * **Determinism:** k-medoids is seeded from a digest of (sorted
+ * file paths || vector signature) so re-runs on the same input
+ * produce the same cluster assignments. Tie-breaking on equal
+ * distances falls back to lexicographic path order.
+ */
+import type { CircleIR } from 'circle-ir';
+/**
+ * Per-file structural fingerprint used as the clustering signal.
+ * CK metrics default to 0 when circle-ir's metric pass didn't run
+ * (e.g. procedural-only files, languages without classes).
+ */
+export interface ClusterVector {
+    cbo: number;
+    rfc: number;
+    lcom: number;
+    dit: number;
+    noc: number;
+    wmc: number;
+    imports: string[];
+    publicSurface: number;
+    annotations: string[];
+}
+export interface ClusterInput {
+    filePath: string;
+    vector: ClusterVector;
+}
+export interface ClusterAssignment {
+    filePath: string;
+    clusterId: number;
+}
+export interface ClusterResult {
+    k: number;
+    assignments: ClusterAssignment[];
+    /** Medoid file path per cluster id (index = clusterId). */
+    medoids: string[];
+    /** Iterations until convergence (for tuning visibility). */
+    iterations: number;
+}
+/**
+ * Downstream policy bundle attached to a cluster. Shape locked here
+ * so wiring tickets can land without re-negotiating the contract;
+ * default policy ("application", everything on) is what consumers
+ * should apply until cluster-specific overrides ship.
+ */
+export type ContextProfile = 'application' | 'library' | 'framework' | 'tool';
+export interface ClusterPolicy {
+    contextProfile: ContextProfile;
+    /** Discovery source kinds permitted; empty array = all. */
+    sourceWhitelist: string[];
+    /** Verification sink classes permitted; empty array = all. */
+    sinkWhitelist: string[];
+    /** When false, downstream LLM passes skip this cluster entirely. */
+    llmEnabled: boolean;
+}
+export declare const DEFAULT_CLUSTER_POLICY: ClusterPolicy;
+/**
+ * Extract a ClusterVector from a single-file `CircleIR` analyze()
+ * result. Missing metrics default to 0 — the cluster vector is
+ * structural, so a procedural file with no CK numbers will land
+ * in the "low-complexity" cluster naturally (it's a valid signal,
+ * not missing data).
+ */
+export declare function extractClusterVector(circleIr: CircleIR): ClusterVector;
+/**
+ * Per-axis max-normalize the CK + publicSurface scalars across the
+ * input set. Max-normalize (rather than z-score) is deliberate:
+ * cluster boundaries should be robust to outliers (one god-class
+ * with WMC=400 shouldn't squash everything else into the same
+ * cluster), and max-normalize gives a clean [0,1] domain that
+ * combines naturally with Jaccard.
+ *
+ * Returns the maxima so callers can normalize new vectors against
+ * the same scale (e.g. for the k-medoids loop on the same set).
+ */
+export declare function computeNormalization(inputs: ClusterInput[]): {
+    cboMax: number;
+    rfcMax: number;
+    lcomMax: number;
+    ditMax: number;
+    nocMax: number;
+    wmcMax: number;
+    publicSurfaceMax: number;
+};
+/** Euclidean distance on the max-normalized CK + publicSurface scalars. */
+export declare function euclideanCkDistance(a: ClusterVector, b: ClusterVector, norm: ReturnType<typeof computeNormalization>): number;
+/**
+ * Jaccard distance on two string sets (1 - |intersection|/|union|).
+ * Returns 0 when both sets are empty (semantically: nothing
+ * distinguishes them on this axis).
+ */
+export declare function jaccardDistance(a: string[], b: string[]): number;
+/**
+ * Combined per-pair distance. Weights mirror the issue's signal
+ * vector ordering (CK is the primary signal; imports + annotations
+ * are tiebreakers). Total is in [0,1] so it composes cleanly with
+ * other metric-space algorithms.
+ *
+ * Weights chosen to sum to 1:
+ *   0.6 — CK + publicSurface Euclidean (clamped to 1 by sqrt of 7
+ *         normalized components, since each (a-b)/max is in [-1,1])
+ *   0.2 — imports Jaccard
+ *   0.2 — annotations Jaccard
+ *
+ * Euclidean is divided by sqrt(7) to renormalize to [0,1] before
+ * weighting — without this, the CK term can exceed 1 and the total
+ * stops being a proper [0,1] distance.
+ */
+export declare function mixedDistance(a: ClusterVector, b: ClusterVector, norm: ReturnType<typeof computeNormalization>): number;
+interface KMedoidsOptions {
+    /** Desired cluster count. Clamped to `[1, inputs.length]`. */
+    k: number;
+    /** Maximum iterations before bailing. Default 50. */
+    maxIter?: number;
+    /** Override the deterministic seed (test-only). */
+    seed?: number;
+}
+/**
+ * PAM-lite k-medoids on `inputs`.
+ *
+ * 1. Seed selection ("build" phase): pick the medoid that minimizes
+ *    total distance to all points, then iteratively pick the point
+ *    that maximizes minimum distance to existing medoids. This is
+ *    deterministic given the seed and degenerates gracefully when
+ *    `inputs.length <= k`.
+ * 2. Assignment: each point joins its closest medoid (lex path
+ *    tiebreak on equal distances).
+ * 3. Swap phase: for each cluster, find the point that minimizes
+ *    intra-cluster distance and promote it to medoid. Repeat until
+ *    no medoid changes (or `maxIter` hits).
+ *
+ * Complexity is O(n^2 * iter) on the distance matrix. For the
+ * top-100 sweep (n ≈ 5000 per repo at the high end) this is ~25M
+ * pairwise computations per iteration — fine for the <2s budget
+ * in Acceptance #2 because distances are scalar arithmetic on
+ * a 9-dim vector.
+ */
+export declare function clusterFiles(inputs: ClusterInput[], options: KMedoidsOptions): ClusterResult;
+export {};
+//# sourceMappingURL=cluster.d.ts.map

package/dist/cluster/cluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster.d.ts","sourceRoot":"","sources":["../../src/cluster/cluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAe,MAAM,WAAW,CAAC;AAMvD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,EAAE,MAAM,CAAC;IACV,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAE9E,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,cAAc,CAAC;IAC/B,2DAA2D;IAC3D,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,8DAA8D;IAC9D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oEAAoE;IACpE,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,eAAO,MAAM,sBAAsB,EAAE,aAKpC,CAAC;AAsBF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CAyDtE;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAYA;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,aAAa,EAChB,CAAC,EAAE,aAAa,EAChB,IAAI,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,GAC5C,MAAM,CAWR;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAShE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,CAAC,EAAE,aAAa,EAChB,CAAC,EAAE,aAAa,EAChB,IAAI,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,GAC5C,MAAM,CAKR;AAwCD,UAAU,eAAe;IACvB,8DAA8D;IAC9D,CAAC,EAAE,MAAM,CAAC;IACV,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,EAAE,eAAe,GACvB,aAAa,CAsJf"}

package/dist/cluster/cluster.js

@@ -0,0 +1,392 @@
+/**
+ * Cluster Layer — Foundation
+ *
+ * Top-of-pipeline file clustering (cognium-ai#154, P4 of epic #155).
+ * Groups files in a repo by their static structural fingerprint (CK
+ * metrics + import/annotation set) so downstream passes can apply
+ * per-cluster policy bundles ("library bootstrap" vs "controller
+ * surface" vs "data-access shim") instead of one-size-fits-all
+ * discovery/verification.
+ *
+ * This file ships the **foundation only**:
+ *   - `extractClusterVector(circleIr)` — pull CK vector from analyze() output
+ *   - `clusterFiles(inputs)` — deterministic k-medoids, returns
+ *     `Map<filePath, clusterId>` per acceptance #1
+ *   - distance functions (Euclidean on normalized CK + Jaccard on
+ *     imports/annotations) + the k-medoids loop itself
+ *   - `ClusterPolicy` type so downstream wiring can land in a
+ *     follow-up without re-declaring shape
+ *
+ * **Explicitly out of scope here** (tracked as follow-up tickets):
+ *   - `meta.json.files[*].clusterId` field — needs scan-emit schema
+ *     migration (Acceptance #3)
+ *   - top-100 HIGH/CRIT reduction validation (Acceptance #4)
+ *   - CWE-Bench-Java regression check (Acceptance #5)
+ *   - `--cluster-policy <profile>` CLI flag in cognium-ai
+ *     (Acceptance #6)
+ *   - LLM cluster labeling pass (optional future per the issue)
+ *
+ * The split is deliberate: P1-P3 of epic #155 were single-shot
+ * cache wins; P4's policy bundles + the two benchmark validation
+ * gates need empirical tuning that can't complete in a single
+ * release cycle. Foundation-first lets cognium-ai start consuming
+ * `clusterFiles()` as an opaque grouping signal while the policy
+ * resolver is iterated separately.
+ *
+ * **Determinism:** k-medoids is seeded from a digest of (sorted
+ * file paths || vector signature) so re-runs on the same input
+ * produce the same cluster assignments. Tie-breaking on equal
+ * distances falls back to lexicographic path order.
+ */
+import * as crypto from 'crypto';
+export const DEFAULT_CLUSTER_POLICY = {
+    contextProfile: 'application',
+    sourceWhitelist: [],
+    sinkWhitelist: [],
+    llmEnabled: true,
+};
+// ───────────────────────────────────────────────────────────────────
+// CK vector extraction
+// ───────────────────────────────────────────────────────────────────
+/**
+ * Names emitted by circle-ir's CK metric passes. Mirrored from
+ * the JSDoc on `MetricValue` in circle-ir's public type surface
+ * (canonical: "CBO" | "RFC" | "LCOM" | "DIT" | "NOC" | "WMC").
+ * Matching is case-insensitive because metric-pass authors have
+ * historically used both casings.
+ */
+const CK_METRIC_KEYS = ['CBO', 'RFC', 'LCOM', 'DIT', 'NOC', 'WMC'];
+function findMetric(metrics, name) {
+    if (!metrics)
+        return 0;
+    const lower = name.toLowerCase();
+    const hit = metrics.find((m) => m.name.toLowerCase() === lower);
+    return hit ? hit.value : 0;
+}
+/**
+ * Extract a ClusterVector from a single-file `CircleIR` analyze()
+ * result. Missing metrics default to 0 — the cluster vector is
+ * structural, so a procedural file with no CK numbers will land
+ * in the "low-complexity" cluster naturally (it's a valid signal,
+ * not missing data).
+ */
+export function extractClusterVector(circleIr) {
+    const metrics = circleIr.metrics?.metrics;
+    // Import package signatures — keep top-2 segments (e.g.
+    // `java.util.List` → `java.util`) so unrelated imports of
+    // different leaf types in the same package don't artificially
+    // increase Jaccard distance. circle-ir's `ImportInfo` carries
+    // `from_package` (the canonical package path) and falls back to
+    // `imported_name` when `from_package` is null (wildcard / default
+    // imports).
+    const imports = Array.from(new Set((circleIr.imports ?? [])
+        .map((imp) => {
+        const raw = imp.from_package ?? imp.imported_name ?? '';
+        const parts = raw.split('.');
+        return parts.length >= 2 ? parts.slice(0, 2).join('.') : raw;
+    })
+        .filter((s) => s.length > 0)));
+    // Class-level annotations (Java: `@RestController`, `@Service`,
+    // `@Entity`; Python: `@app.route` would surface here if circle-ir
+    // attaches it to the class node). Pulled from `types[*].annotations`.
+    const annotations = Array.from(new Set((circleIr.types ?? [])
+        .flatMap((t) => t.annotations ?? [])
+        .filter((s) => typeof s === 'string' && s.length > 0)));
+    // Public surface = count of types + methods that aren't explicitly
+    // marked private. `TypeInfo` has no visibility field in circle-ir's
+    // surface (all top-level types count as "public-ish" for clustering
+    // purposes); methods carry `modifiers: string[]` from which we pull
+    // the visibility token.
+    let publicSurface = 0;
+    for (const t of circleIr.types ?? []) {
+        publicSurface++;
+        for (const m of t.methods ?? []) {
+            if (!(m.modifiers ?? []).includes('private'))
+                publicSurface++;
+        }
+    }
+    return {
+        cbo: findMetric(metrics, 'CBO'),
+        rfc: findMetric(metrics, 'RFC'),
+        lcom: findMetric(metrics, 'LCOM'),
+        dit: findMetric(metrics, 'DIT'),
+        noc: findMetric(metrics, 'NOC'),
+        wmc: findMetric(metrics, 'WMC'),
+        imports,
+        publicSurface,
+        annotations,
+    };
+}
+// ───────────────────────────────────────────────────────────────────
+// Distance functions
+// ───────────────────────────────────────────────────────────────────
+/**
+ * Per-axis max-normalize the CK + publicSurface scalars across the
+ * input set. Max-normalize (rather than z-score) is deliberate:
+ * cluster boundaries should be robust to outliers (one god-class
+ * with WMC=400 shouldn't squash everything else into the same
+ * cluster), and max-normalize gives a clean [0,1] domain that
+ * combines naturally with Jaccard.
+ *
+ * Returns the maxima so callers can normalize new vectors against
+ * the same scale (e.g. for the k-medoids loop on the same set).
+ */
+export function computeNormalization(inputs) {
+    const max = (sel) => Math.max(1, ...inputs.map((i) => sel(i.vector)));
+    return {
+        cboMax: max((v) => v.cbo),
+        rfcMax: max((v) => v.rfc),
+        lcomMax: max((v) => v.lcom),
+        ditMax: max((v) => v.dit),
+        nocMax: max((v) => v.noc),
+        wmcMax: max((v) => v.wmc),
+        publicSurfaceMax: max((v) => v.publicSurface),
+    };
+}
+/** Euclidean distance on the max-normalized CK + publicSurface scalars. */
+export function euclideanCkDistance(a, b, norm) {
+    const dx = [
+        (a.cbo - b.cbo) / norm.cboMax,
+        (a.rfc - b.rfc) / norm.rfcMax,
+        (a.lcom - b.lcom) / norm.lcomMax,
+        (a.dit - b.dit) / norm.ditMax,
+        (a.noc - b.noc) / norm.nocMax,
+        (a.wmc - b.wmc) / norm.wmcMax,
+        (a.publicSurface - b.publicSurface) / norm.publicSurfaceMax,
+    ];
+    return Math.sqrt(dx.reduce((acc, x) => acc + x * x, 0));
+}
+/**
+ * Jaccard distance on two string sets (1 - |intersection|/|union|).
+ * Returns 0 when both sets are empty (semantically: nothing
+ * distinguishes them on this axis).
+ */
+export function jaccardDistance(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    const sa = new Set(a);
+    const sb = new Set(b);
+    let intersect = 0;
+    for (const x of sa)
+        if (sb.has(x))
+            intersect++;
+    const union = sa.size + sb.size - intersect;
+    if (union === 0)
+        return 0;
+    return 1 - intersect / union;
+}
+/**
+ * Combined per-pair distance. Weights mirror the issue's signal
+ * vector ordering (CK is the primary signal; imports + annotations
+ * are tiebreakers). Total is in [0,1] so it composes cleanly with
+ * other metric-space algorithms.
+ *
+ * Weights chosen to sum to 1:
+ *   0.6 — CK + publicSurface Euclidean (clamped to 1 by sqrt of 7
+ *         normalized components, since each (a-b)/max is in [-1,1])
+ *   0.2 — imports Jaccard
+ *   0.2 — annotations Jaccard
+ *
+ * Euclidean is divided by sqrt(7) to renormalize to [0,1] before
+ * weighting — without this, the CK term can exceed 1 and the total
+ * stops being a proper [0,1] distance.
+ */
+export function mixedDistance(a, b, norm) {
+    const ck = euclideanCkDistance(a, b, norm) / Math.sqrt(7);
+    const importsD = jaccardDistance(a.imports, b.imports);
+    const annotationsD = jaccardDistance(a.annotations, b.annotations);
+    return 0.6 * ck + 0.2 * importsD + 0.2 * annotationsD;
+}
+// ───────────────────────────────────────────────────────────────────
+// Seeded PRNG (deterministic across runs)
+// ───────────────────────────────────────────────────────────────────
+/**
+ * Mulberry32 — fast, well-distributed seeded PRNG. We don't need
+ * cryptographic randomness here, just reproducibility across runs
+ * for the same input set. Seed is derived from a digest of the
+ * sorted (path || vector) signatures so adding/removing files
+ * changes the seed but reordering inputs does not.
+ */
+function mulberry32(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s = (s + 0x6d2b79f5) >>> 0;
+        let t = s;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function deriveSeed(inputs) {
+    const sig = inputs
+        .map((i) => `${i.filePath}\0${i.vector.cbo},${i.vector.rfc},${i.vector.lcom},${i.vector.dit},${i.vector.noc},${i.vector.wmc},${i.vector.publicSurface}`)
+        .sort()
+        .join('|');
+    const hash = crypto.createHash('sha256').update(sig).digest();
+    return hash.readUInt32BE(0);
+}
+/**
+ * PAM-lite k-medoids on `inputs`.
+ *
+ * 1. Seed selection ("build" phase): pick the medoid that minimizes
+ *    total distance to all points, then iteratively pick the point
+ *    that maximizes minimum distance to existing medoids. This is
+ *    deterministic given the seed and degenerates gracefully when
+ *    `inputs.length <= k`.
+ * 2. Assignment: each point joins its closest medoid (lex path
+ *    tiebreak on equal distances).
+ * 3. Swap phase: for each cluster, find the point that minimizes
+ *    intra-cluster distance and promote it to medoid. Repeat until
+ *    no medoid changes (or `maxIter` hits).
+ *
+ * Complexity is O(n^2 * iter) on the distance matrix. For the
+ * top-100 sweep (n ≈ 5000 per repo at the high end) this is ~25M
+ * pairwise computations per iteration — fine for the <2s budget
+ * in Acceptance #2 because distances are scalar arithmetic on
+ * a 9-dim vector.
+ */
+export function clusterFiles(inputs, options) {
+    const k = Math.max(1, Math.min(options.k, inputs.length));
+    const maxIter = options.maxIter ?? 50;
+    if (inputs.length === 0) {
+        return { k: 0, assignments: [], medoids: [], iterations: 0 };
+    }
+    // Sort by path so ties are broken lexicographically regardless of
+    // input order.
+    const sorted = [...inputs].sort((a, b) => a.filePath.localeCompare(b.filePath));
+    const n = sorted.length;
+    const norm = computeNormalization(sorted);
+    // Precompute distance matrix (symmetric, diagonal zero).
+    const dist = Array.from({ length: n }, () => new Array(n).fill(0));
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            const d = mixedDistance(sorted[i].vector, sorted[j].vector, norm);
+            dist[i][j] = d;
+            dist[j][i] = d;
+        }
+    }
+    // Build phase — deterministic seed init.
+    const seed = options.seed ?? deriveSeed(sorted);
+    const rng = mulberry32(seed);
+    const medoidIdx = [];
+    // First medoid: minimize total distance to all points (1-medoid PAM).
+    let bestSum = Infinity;
+    let bestIdx = 0;
+    for (let i = 0; i < n; i++) {
+        let sum = 0;
+        for (let j = 0; j < n; j++)
+            sum += dist[i][j];
+        if (sum < bestSum || (sum === bestSum && sorted[i].filePath < sorted[bestIdx].filePath)) {
+            bestSum = sum;
+            bestIdx = i;
+        }
+    }
+    medoidIdx.push(bestIdx);
+    // Remaining medoids: maximize min-distance to existing medoids.
+    // RNG breaks ties on equally-far candidates for deterministic but
+    // non-degenerate seeding when the set has structural symmetry.
+    while (medoidIdx.length < k) {
+        let bestPick = -1;
+        let bestMinDist = -1;
+        const candidates = [];
+        for (let i = 0; i < n; i++) {
+            if (medoidIdx.includes(i))
+                continue;
+            let minD = Infinity;
+            for (const m of medoidIdx) {
+                if (dist[i][m] < minD)
+                    minD = dist[i][m];
+            }
+            if (minD > bestMinDist) {
+                bestMinDist = minD;
+                bestPick = i;
+                candidates.length = 0;
+                candidates.push(i);
+            }
+            else if (minD === bestMinDist) {
+                candidates.push(i);
+            }
+        }
+        if (bestPick === -1)
+            break;
+        // Tiebreak: lex-first wins; if rng() < 0.5, allow a randomized
+        // alternative from the tied set. This preserves determinism
+        // (same seed → same pick) while avoiding pathological pile-ups
+        // on highly-symmetric inputs.
+        if (candidates.length > 1 && rng() < 0.5) {
+            candidates.sort((a, b) => sorted[a].filePath.localeCompare(sorted[b].filePath));
+            bestPick = candidates[Math.floor(rng() * candidates.length)];
+        }
+        else {
+            // Default: lex-first.
+            bestPick = candidates.reduce((best, c) => (sorted[c].filePath < sorted[best].filePath ? c : best), candidates[0]);
+        }
+        medoidIdx.push(bestPick);
+    }
+    // Iterate: assign → swap → check convergence.
+    let assignment = new Array(n).fill(0);
+    let iterations = 0;
+    for (let iter = 0; iter < maxIter; iter++) {
+        iterations = iter + 1;
+        // Assign each point to closest medoid (lex tiebreak via medoid order).
+        for (let i = 0; i < n; i++) {
+            let bestC = 0;
+            let bestD = dist[i][medoidIdx[0]];
+            for (let c = 1; c < medoidIdx.length; c++) {
+                const d = dist[i][medoidIdx[c]];
+                if (d < bestD ||
+                    (d === bestD && sorted[medoidIdx[c]].filePath < sorted[medoidIdx[bestC]].filePath)) {
+                    bestD = d;
+                    bestC = c;
+                }
+            }
+            assignment[i] = bestC;
+        }
+        // Swap: for each cluster, find the point that minimizes
+        // intra-cluster distance and promote it.
+        const newMedoids = [...medoidIdx];
+        for (let c = 0; c < medoidIdx.length; c++) {
+            const members = [];
+            for (let i = 0; i < n; i++)
+                if (assignment[i] === c)
+                    members.push(i);
+            if (members.length === 0)
+                continue;
+            let bestM = newMedoids[c];
+            let bestCost = Infinity;
+            for (const m of members) {
+                let cost = 0;
+                for (const other of members)
+                    cost += dist[m][other];
+                if (cost < bestCost || (cost === bestCost && sorted[m].filePath < sorted[bestM].filePath)) {
+                    bestCost = cost;
+                    bestM = m;
+                }
+            }
+            newMedoids[c] = bestM;
+        }
+        // Check convergence (medoid set stable).
+        let changed = false;
+        for (let c = 0; c < newMedoids.length; c++) {
+            if (newMedoids[c] !== medoidIdx[c]) {
+                changed = true;
+                break;
+            }
+        }
+        medoidIdx.length = 0;
+        medoidIdx.push(...newMedoids);
+        if (!changed)
+            break;
+    }
+    const assignments = sorted.map((inp, i) => ({
+        filePath: inp.filePath,
+        clusterId: assignment[i],
+    }));
+    return {
+        k: medoidIdx.length,
+        assignments,
+        medoids: medoidIdx.map((i) => sorted[i].filePath),
+        iterations,
+    };
+}
+//# sourceMappingURL=cluster.js.map

package/dist/cluster/cluster.js.map

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

package/dist/cluster/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Cluster layer public surface.
+ *
+ * Foundation only (cognium-ai#154, P4 of epic #155). Re-exports the
+ * primitives that downstream wiring tickets (meta.json schema, CLI
+ * flag, benchmark validation) will consume — see `cluster.ts`
+ * file-header for the scope split.
+ */
+export { clusterFiles, extractClusterVector, computeNormalization, euclideanCkDistance, jaccardDistance, mixedDistance, DEFAULT_CLUSTER_POLICY, } from './cluster.js';
+export type { ClusterVector, ClusterInput, ClusterAssignment, ClusterResult, ClusterPolicy, ContextProfile, } from './cluster.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cluster/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cluster/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,cAAc,CAAC"}

package/dist/cluster/index.js

@@ -0,0 +1,10 @@
+/**
+ * Cluster layer public surface.
+ *
+ * Foundation only (cognium-ai#154, P4 of epic #155). Re-exports the
+ * primitives that downstream wiring tickets (meta.json schema, CLI
+ * flag, benchmark validation) will consume — see `cluster.ts`
+ * file-header for the scope split.
+ */
+export { clusterFiles, extractClusterVector, computeNormalization, euclideanCkDistance, jaccardDistance, mixedDistance, DEFAULT_CLUSTER_POLICY, } from './cluster.js';
+//# sourceMappingURL=index.js.map

package/dist/cluster/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cluster/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,sBAAsB,GACvB,MAAM,cAAc,CAAC"}

package/dist/index.d.ts

@@ -55,4 +55,5 @@ export { analyzeComponents, enrichComponent, enrichComponents, clusterComponents
 export { summarizeFunction, summarizeAllFunctions, summarizeModule, detectRole, type FunctionEffect, type SideEffect, type SideEffectKind, type ModuleSummary, type ModuleRole, type UnderstandOptions, type UnderstandResult, } from './understand/index.js';
 export { analyzeSpecGap, parseSpecMd, type SpecGapResult, type SpecGapOptions, type RequirementMatch, type UncoveredRequirement, type UndocumentedBehavior, } from './spec-gap/index.js';
 export { loadCogniumConfig, convertCogniumConfigToPassOptions, type CogniumConfig, type Suppression, } from './config/cognium-config.js';
+export { clusterFiles, extractClusterVector, computeNormalization, euclideanCkDistance, jaccardDistance, mixedDistance, DEFAULT_CLUSTER_POLICY, type ClusterVector, type ClusterInput, type ClusterAssignment, type ClusterResult, type ClusterPolicy, type ContextProfile, } from './cluster/index.js';
 //# sourceMappingURL=index.d.ts.map