audit-tools 0.32.17 → 0.32.19

package/dist/shared/decompose/charterExtraction.js

@@ -0,0 +1,209 @@
+// The charter layer of the conceptual design-review — assemble a gated charter
+// register from a host LLM submission (Phase C; design of record
+// spec/conceptual-design-review-design.md §"The four charters" + §"The True
+// charter needs hard gates").
+//
+// Division of labour ([[contract-authoring-determinism-direction]]): the LLM emits
+// JUDGMENT (per consensus subsystem, the four charter families in telos terms +
+// the interpreted pairwise deltas it sees); this module is the deterministic
+// ENFORCEMENT half — it assigns stable ids, derives each delta's kind + routing
+// from its charter pair (the design's routing table, never host discretion), runs
+// the Phase-A hard gates (applyTrueCharterGate drops un-falsifiable True;
+// gateCharterDelta forces a low-confidence side to the human channel), grounds
+// every subsystem against the Phase-B consensus scaffold, and surfaces the
+// surviving deltas as Finding leads for synthesis. PURE + deterministic +
+// language-neutral (operates on abstract node-id partitions + telos strings, no
+// IO): provenance-on-disk grounding is the ingest's concern, not this module's.
+import { z } from "zod";
+import { CharterSchema, CharterKindSchema, GoalGraphSchema, } from "../types/charter.js";
+import { applyTrueCharterGate, gateCharterDelta, } from "../validation/charterGate.js";
+// ── Submission contract (what the host LLM writes to incoming/) ────────────────
+/**
+ * A single charter as the host emits it — the persisted `Charter` minus its
+ * `charter_id`, which the tool assigns deterministically (`node_id:kind`) so
+ * charter identity can never drift from the host's free choice.
+ */
+const CharterInputSchema = CharterSchema.omit({ charter_id: true });
+/**
+ * A delta as the host emits it: the symmetric charter-kind `pair` it sees a gap
+ * across + the interpreted `summary` of that gap. The tool derives `kind`,
+ * `routed_to`, and `delta_id` — the host never picks the routing (that is the
+ * design's fixed table, enforced here).
+ */
+const CharterDeltaInputSchema = z
+    .object({
+    pair: z.tuple([CharterKindSchema, CharterKindSchema]),
+    summary: z.string(),
+})
+    .strict();
+/** One reviewed subsystem: its consensus `node_id` + the charters/deltas for it. */
+const CharterSubsystemInputSchema = z
+    .object({
+    node_id: z.string(),
+    charters: z.array(CharterInputSchema),
+    deltas: z.array(CharterDeltaInputSchema).default([]),
+})
+    .strict();
+/** The full host submission consumed at charter-extraction ingest. */
+export const CharterSubmissionSchema = z
+    .object({
+    subsystems: z.array(CharterSubsystemInputSchema).default([]),
+    goal_graph: GoalGraphSchema.optional(),
+})
+    .strict();
+// ── Deterministic routing table (design §"The four charters") ──────────────────
+/**
+ * Canonical charter-kind order — pairs are sorted by this so `[stated, revealed]`
+ * and `[revealed, stated]` map to one key (the deltas are symmetric).
+ */
+const KIND_ORDER = ["stated", "inferred", "revealed", "true"];
+function canonicalPair(pair) {
+    return [...pair].sort((a, b) => KIND_ORDER.indexOf(a) - KIND_ORDER.indexOf(b));
+}
+/**
+ * The design's routing table, keyed by canonical `pair` — who acts on each gap.
+ * A pair OUTSIDE this table has no defined owner and is a validation issue (the
+ * tool never invents a route). `severity` ranks the surfaced lead: a wrong-goal
+ * provocation is the highest-blast, an unstated assumption the lowest.
+ */
+const DELTA_ROUTES = {
+    "stated|inferred": {
+        kind: "unstated_assumption",
+        routed_to: "clarification",
+        severity: "low",
+    },
+    "stated|revealed": {
+        kind: "spec_drift",
+        routed_to: "remediator",
+        severity: "medium",
+    },
+    "revealed|true": {
+        kind: "wrong_goal",
+        routed_to: "human",
+        severity: "high",
+    },
+    "stated|true": {
+        kind: "wrong_goal",
+        routed_to: "human",
+        severity: "high",
+    },
+};
+/** Lower of two charter confidences — a delta is only as strong as its weaker side. */
+function weakerConfidence(a, b) {
+    const rank = { high: 2, medium: 1, low: 0 };
+    return rank[a.confidence] <= rank[b.confidence] ? a.confidence : b.confidence;
+}
+// ── Assembly ───────────────────────────────────────────────────────────────────
+/**
+ * Assemble a gated charter register from a validated host submission.
+ *
+ * `membersByNode` grounds each submitted subsystem against the Phase-B consensus
+ * scaffold: a `node_id` the structure decomposition never surfaced is an invented
+ * subsystem → dropped with an issue (the host cannot conjure boundaries the
+ * deterministic layer didn't find). Deterministic throughout — same submission +
+ * same scaffold always yields the same register.
+ */
+export function assembleCharterRegister(submission, membersByNode) {
+    const subsystems = [];
+    const deltas = [];
+    const findings = [];
+    const validation_issues = [];
+    // Stable output order: sort subsystems by node_id (content-derived, never input
+    // order — an incidentally-ordered array churns the artifact hash, cascading
+    // phantom staleness; see the extractor-ordering invariant in CLAUDE.md).
+    const sortedSubsystems = [...submission.subsystems].sort((a, b) => a.node_id.localeCompare(b.node_id));
+    for (const sub of sortedSubsystems) {
+        const members = membersByNode.get(sub.node_id);
+        if (!members) {
+            validation_issues.push(`subsystem "${sub.node_id}" is not a consensus node in the structure decomposition — dropped (charters may only review discovered subsystems)`);
+            continue;
+        }
+        // Assign ids + enforce one charter per kind (a dup kind is a submission error;
+        // keep the first, flag the rest).
+        const seenKinds = new Set();
+        const withIds = [];
+        for (const input of sub.charters) {
+            if (seenKinds.has(input.kind)) {
+                validation_issues.push(`subsystem "${sub.node_id}" has more than one "${input.kind}" charter — kept the first, dropped the rest`);
+                continue;
+            }
+            seenKinds.add(input.kind);
+            withIds.push({ ...input, charter_id: `${sub.node_id}:${input.kind}` });
+        }
+        // Phase-A True gate: drop un-falsifiable True nominations (no concrete
+        // alternative + cost). Surface each drop as an issue.
+        const { kept, dropped } = applyTrueCharterGate(withIds);
+        for (const drop of dropped) {
+            validation_issues.push(`${drop.charter_id}: ${drop.reason}`);
+        }
+        subsystems.push({
+            node_id: sub.node_id,
+            members,
+            charters: [...kept].sort((a, b) => a.charter_id.localeCompare(b.charter_id)),
+        });
+        const keptByKind = new Map(kept.map((c) => [c.kind, c]));
+        // Route + gate each submitted delta against the surviving charters.
+        for (const draft of sub.deltas) {
+            const [ka, kb] = canonicalPair(draft.pair);
+            if (ka === kb) {
+                validation_issues.push(`subsystem "${sub.node_id}" delta pairs "${ka}" with itself — dropped`);
+                continue;
+            }
+            const route = DELTA_ROUTES[`${ka}|${kb}`];
+            if (!route) {
+                validation_issues.push(`subsystem "${sub.node_id}" delta [${ka}, ${kb}] has no routing in the design's table — dropped`);
+                continue;
+            }
+            const charterA = keptByKind.get(ka);
+            const charterB = keptByKind.get(kb);
+            if (!charterA || !charterB) {
+                const missing = [!charterA ? ka : null, !charterB ? kb : null]
+                    .filter((m) => m !== null)
+                    .join(" + ");
+                validation_issues.push(`subsystem "${sub.node_id}" delta [${ka}, ${kb}] references a missing/dropped charter (${missing}) — dropped`);
+                continue;
+            }
+            const baseDelta = {
+                delta_id: `${sub.node_id}:${ka}-${kb}`,
+                pair: [ka, kb],
+                kind: route.kind,
+                routed_to: route.routed_to,
+                summary: draft.summary,
+            };
+            // Phase-A low-confidence gate: a shaky side forces the human channel.
+            const gated = gateCharterDelta(baseDelta, kept);
+            deltas.push(gated);
+            findings.push(deltaToFinding(gated, sub.node_id, members, route.severity, weakerConfidence(charterA, charterB)));
+        }
+    }
+    deltas.sort((a, b) => a.delta_id.localeCompare(b.delta_id));
+    findings.sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        subsystems,
+        deltas,
+        findings,
+        goal_graph: submission.goal_graph ?? { nodes: [], edges: [] },
+        validation_issues,
+    };
+}
+/**
+ * Surface a routed charter delta as a Finding LEAD ([[leads-not-verdicts]] — the
+ * owner judges it; a charter delta is never a verdict). `lens` is `architecture`:
+ * a charter-boundary gap is a design defect. Members of the subsystem are the
+ * affected files (structure decomposition operates over file ids).
+ */
+function deltaToFinding(delta, nodeId, members, severity, confidence) {
+    const kindLabel = delta.kind.replace(/_/g, " ");
+    return {
+        id: delta.delta_id,
+        title: `Charter delta (${kindLabel}) in subsystem ${nodeId}`,
+        category: `charter_delta:${delta.kind}`,
+        severity,
+        confidence,
+        lens: "architecture",
+        summary: delta.summary,
+        affected_files: members.map((path) => ({ path })),
+        systemic: true,
+    };
+}
+//# sourceMappingURL=charterExtraction.js.map

package/dist/shared/decompose/charterExtraction.js.map

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

package/dist/shared/decompose/consensus.d.ts

@@ -0,0 +1,66 @@
+import type { Partition } from "./modularity.js";
+/**
+ * One independently-sourced view of the target, contributing a family of
+ * partitions over the shared node universe. A multi-resolution behavior source
+ * (call/import, co-change, data/state) supplies several partitions (one per
+ * resolution); an intent-declared source (directory, docs, comments) typically
+ * supplies one.
+ */
+export interface DecompositionSource {
+    /** Stable source id, e.g. `call_import` / `co_change` / `directory`. */
+    id: string;
+    /**
+     * Which decomposition family this source belongs to (design §"two families"):
+     * `behavior` = what the system does (coupling / co-change / data-state);
+     * `intent` = what humans assert the pieces are (dirs / docs / comments). Only
+     * `behavior` partitions feed the scale-stability score.
+     */
+    family: "behavior" | "intent";
+    partitions: Partition[];
+}
+/** A discovered subsystem candidate — an emergent node, never pre-defined. */
+export interface DecomposedNode {
+    /** Stable id: the lexicographically smallest member. */
+    node_id: string;
+    /** Member node ids, lexically sorted. */
+    members: string[];
+    /** Fraction of sources co-locating the members, in [0,1]. */
+    agreed_across_source: number;
+    /** Fraction of behavior resolution levels co-locating the members, in [0,1]. */
+    stable_across_scale: number;
+    /** True when low on EITHER score (below the confident bar). */
+    contested: boolean;
+}
+export interface DecomposeResult {
+    target: string;
+    /** Nodes high on BOTH scores — confident subsystems. */
+    consensus: DecomposedNode[];
+    /** Nodes low on EITHER score — contested boundaries (each a hotspot/finding). */
+    contested: DecomposedNode[];
+}
+export interface DecomposeOptions {
+    /**
+     * Minimum agreed-across-source a pair needs for its members to be unioned into
+     * the same candidate node. The co-association edge threshold.
+     */
+    agreementThreshold?: number;
+    /**
+     * The "confident" bar: a node is consensus only when BOTH scores meet it.
+     */
+    confidentThreshold?: number;
+}
+/**
+ * Cluster nodes that co-locate in at least `minFraction` of the given partitions
+ * (a consensus over the partition family). Returns member groups of size ≥ 2,
+ * lexically sorted, in a deterministic order. Shared by {@link decompose} and by
+ * the non-co-localization finding detectors, which need behavior-only and
+ * intent-only cluster views separately.
+ */
+export declare function clustersFromPartitions(partitions: Partition[], minFraction?: number): string[][];
+/**
+ * The overlay-and-delta operator. Builds a co-association over all sources,
+ * unions strongly-agreed pairs into candidate nodes, scores each node on the two
+ * orthogonal robustness axes, and splits confident (consensus) from contested.
+ */
+export declare function decompose(sources: DecompositionSource[], target: string, options?: DecomposeOptions): DecomposeResult;
+//# sourceMappingURL=consensus.d.ts.map

package/dist/shared/decompose/consensus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consensus.d.ts","sourceRoot":"","sources":["../../../src/shared/decompose/consensus.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC9B,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6DAA6D;IAC7D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,gFAAgF;IAChF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,iFAAiF;IACjF,SAAS,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAE7B;AA4FD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,SAAS,EAAE,EACvB,WAAW,SAA8B,GACxC,MAAM,EAAE,EAAE,CAeZ;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,mBAAmB,EAAE,EAC9B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CAiFjB"}

package/dist/shared/decompose/consensus.js

@@ -0,0 +1,213 @@
+// The overlay-and-delta operator — consensus / ensemble decomposition (Phase B;
+// design of record spec/conceptual-design-review-design.md §"The one operator").
+//
+//   decompose(sources, target) → { consensus, contested }
+//
+// Feed several INDEPENDENTLY-SOURCED views of a target; where they AGREE you have
+// a node (a real subsystem boundary), where they DISAGREE you have a finding and a
+// hotspot. The views are NEVER reconciled into one truth — the disagreement is the
+// product. A node carries TWO orthogonal robustness scores (design §"Granularity
+// resolves across scale"):
+//   - agreed_across_source: how many independent sources co-locate its members.
+//   - stable_across_scale:  how many resolution levels (within the behavior graphs'
+//                           modularity sweep) keep its members together.
+// High on BOTH = a confident subsystem (consensus). Low on EITHER = contested
+// (routed to more adversarial review; the contested status is itself a finding).
+//
+// PURE + DETERMINISTIC + language-neutral: operates only on abstract partitions of
+// string node ids, so the SAME primitive runs at the structure layer (this phase)
+// and, in Phase C, at the charter layer (sources = the four charters). No IO.
+const DEFAULT_AGREEMENT_THRESHOLD = 0.5;
+const DEFAULT_CONFIDENT_THRESHOLD = 0.6;
+/** Canonical unordered-pair key (`minmax`, a text-safe unit separator that
+ * cannot appear in a node id) so (u,v) and (v,u) collide. */
+function pairKey(a, b) {
+    return a.localeCompare(b) <= 0 ? `${a}\u001f${b}` : `${b}\u001f${a}`;
+}
+function splitPairKey(key) {
+    const idx = key.indexOf("\u001f");
+    return [key.slice(0, idx), key.slice(idx + 1)];
+}
+/** Minimal deterministic union-find over string ids. */
+class UnionFind {
+    parent = new Map();
+    find(x) {
+        let root = this.parent.get(x);
+        if (root === undefined) {
+            this.parent.set(x, x);
+            return x;
+        }
+        while (root !== this.parent.get(root)) {
+            const grand = this.parent.get(root);
+            this.parent.set(root, this.parent.get(grand));
+            root = this.parent.get(root);
+        }
+        return root;
+    }
+    add(x) {
+        if (!this.parent.has(x))
+            this.parent.set(x, x);
+    }
+    union(a, b) {
+        const ra = this.find(a);
+        const rb = this.find(b);
+        if (ra === rb)
+            return;
+        // Attach the lexically larger root under the smaller so the representative is
+        // stable and independent of union order.
+        if (ra.localeCompare(rb) < 0)
+            this.parent.set(rb, ra);
+        else
+            this.parent.set(ra, rb);
+    }
+    groups() {
+        const out = new Map();
+        for (const node of this.parent.keys()) {
+            const root = this.find(node);
+            const list = out.get(root);
+            if (list)
+                list.push(node);
+            else
+                out.set(root, [node]);
+        }
+        for (const list of out.values())
+            list.sort((a, b) => a.localeCompare(b));
+        return out;
+    }
+}
+/**
+ * Per-pair co-membership counts over a set of partitions. Only pairs that are
+ * co-located in at least one partition get an entry (so the result is bounded by
+ * Σ|community|² rather than |universe|²). Returns the counts + partition total.
+ */
+function coMembershipCounts(partitions) {
+    const counts = new Map();
+    for (const partition of partitions) {
+        // Group nodes by community for this partition.
+        const communities = new Map();
+        for (const [node, comm] of partition) {
+            const list = communities.get(comm);
+            if (list)
+                list.push(node);
+            else
+                communities.set(comm, [node]);
+        }
+        for (const members of communities.values()) {
+            if (members.length < 2)
+                continue;
+            const sorted = [...members].sort((a, b) => a.localeCompare(b));
+            for (let i = 0; i < sorted.length; i++) {
+                for (let j = i + 1; j < sorted.length; j++) {
+                    const key = pairKey(sorted[i], sorted[j]);
+                    counts.set(key, (counts.get(key) ?? 0) + 1);
+                }
+            }
+        }
+    }
+    return { counts, total: partitions.length };
+}
+/**
+ * Cluster nodes that co-locate in at least `minFraction` of the given partitions
+ * (a consensus over the partition family). Returns member groups of size ≥ 2,
+ * lexically sorted, in a deterministic order. Shared by {@link decompose} and by
+ * the non-co-localization finding detectors, which need behavior-only and
+ * intent-only cluster views separately.
+ */
+export function clustersFromPartitions(partitions, minFraction = DEFAULT_AGREEMENT_THRESHOLD) {
+    const { counts, total } = coMembershipCounts(partitions);
+    if (total === 0)
+        return [];
+    const uf = new UnionFind();
+    for (const [key, count] of counts) {
+        if (count / total + 1e-12 >= minFraction) {
+            const [a, b] = splitPairKey(key);
+            uf.add(a);
+            uf.add(b);
+            uf.union(a, b);
+        }
+    }
+    const groups = [...uf.groups().values()].filter((g) => g.length >= 2);
+    groups.sort((a, b) => a[0].localeCompare(b[0]));
+    return groups;
+}
+/**
+ * The overlay-and-delta operator. Builds a co-association over all sources,
+ * unions strongly-agreed pairs into candidate nodes, scores each node on the two
+ * orthogonal robustness axes, and splits confident (consensus) from contested.
+ */
+export function decompose(sources, target, options = {}) {
+    const agreementThreshold = options.agreementThreshold ?? DEFAULT_AGREEMENT_THRESHOLD;
+    const confidentThreshold = options.confidentThreshold ?? DEFAULT_CONFIDENT_THRESHOLD;
+    // agreed-across-source: mean over sources of each source's within-family
+    // co-location fraction. Accumulate one source at a time to bound memory.
+    const agreedSum = new Map();
+    const activeSources = sources.filter((s) => s.partitions.length > 0);
+    for (const source of activeSources) {
+        const { counts, total } = coMembershipCounts(source.partitions);
+        for (const [key, count] of counts) {
+            agreedSum.set(key, (agreedSum.get(key) ?? 0) + count / total);
+        }
+    }
+    const numSources = activeSources.length;
+    // stable-across-scale: co-location fraction pooled over ALL behavior partitions
+    // (every resolution level of every behavior source).
+    const behaviorPartitions = activeSources
+        .filter((s) => s.family === "behavior")
+        .flatMap((s) => s.partitions);
+    const { counts: stableCounts, total: behaviorTotal } = coMembershipCounts(behaviorPartitions);
+    const agreedOf = (key) => numSources === 0 ? 0 : (agreedSum.get(key) ?? 0) / numSources;
+    const stableOf = (key) => behaviorTotal === 0 ? 0 : (stableCounts.get(key) ?? 0) / behaviorTotal;
+    // Union strongly-agreed pairs into candidate nodes.
+    const uf = new UnionFind();
+    for (const key of agreedSum.keys()) {
+        if (agreedOf(key) + 1e-12 >= agreementThreshold) {
+            const [a, b] = splitPairKey(key);
+            uf.add(a);
+            uf.add(b);
+            uf.union(a, b);
+        }
+    }
+    const consensus = [];
+    const contested = [];
+    for (const members of uf.groups().values()) {
+        if (members.length < 2)
+            continue;
+        // Node scores = mean over all internal member-pairs (missing pair ⇒ 0), so a
+        // loosely-agreed component is penalized on both axes.
+        let agreedAcc = 0;
+        let stableAcc = 0;
+        let pairs = 0;
+        for (let i = 0; i < members.length; i++) {
+            for (let j = i + 1; j < members.length; j++) {
+                const key = pairKey(members[i], members[j]);
+                agreedAcc += agreedOf(key);
+                stableAcc += stableOf(key);
+                pairs += 1;
+            }
+        }
+        const agreed = pairs === 0 ? 0 : agreedAcc / pairs;
+        const stable = pairs === 0 ? 0 : stableAcc / pairs;
+        const isContested = !(agreed + 1e-12 >= confidentThreshold &&
+            stable + 1e-12 >= confidentThreshold);
+        const node = {
+            node_id: members[0],
+            members,
+            agreed_across_source: round(agreed),
+            stable_across_scale: round(stable),
+            contested: isContested,
+        };
+        if (isContested)
+            contested.push(node);
+        else
+            consensus.push(node);
+    }
+    const byId = (a, b) => a.node_id.localeCompare(b.node_id);
+    consensus.sort(byId);
+    contested.sort(byId);
+    return { target, consensus, contested };
+}
+/** Round a score to 4 decimals so persisted artifacts don't churn on float noise. */
+function round(value) {
+    return Math.round(value * 1e4) / 1e4;
+}
+//# sourceMappingURL=consensus.js.map

package/dist/shared/decompose/consensus.js.map

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

package/dist/shared/decompose/modularity.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A weighted undirected graph over string node ids. `edges` are undirected; a
+ * repeated {a,b} pair (either orientation) accumulates weight. Self-loops
+ * (a === b) are allowed and accounted for in the degree, which matters once
+ * communities are aggregated into super-nodes.
+ */
+export interface WeightedGraph {
+    /** The full node universe (may include nodes with no edges). */
+    nodes: string[];
+    edges: Array<{
+        a: string;
+        b: string;
+        weight: number;
+    }>;
+}
+/**
+ * A partition of a node universe: a map from node id to the id of the community
+ * it belongs to. Community ids are themselves node ids (the lexicographically
+ * smallest member acts as the stable representative).
+ */
+export type Partition = Map<string, string>;
+/**
+ * Default resolution ladder, coarse→fine. Higher resolution γ penalizes large
+ * communities more, yielding more (smaller) communities — so the ladder walks
+ * from few coarse subsystems to many fine ones. A boundary present at coarse γ
+ * AND fine γ is scale-stable. Chosen as a geometric spread so each rung is a
+ * distinct scale rather than a small perturbation of its neighbor.
+ */
+export declare const DEFAULT_RESOLUTIONS: readonly number[];
+/**
+ * Detect communities in a weighted graph at a single resolution γ via the
+ * Louvain method: local-moving then aggregation, repeated until a level stops
+ * improving. Returns a flat node→community partition (community ids are the
+ * lexicographically smallest member). Deterministic for a given graph + γ.
+ */
+export declare function louvain(graph: WeightedGraph, resolution: number): Partition;
+/**
+ * Cluster the same graph at every resolution in the ladder, coarse→fine, and
+ * return the partitions in ladder order. The multi-resolution family is the
+ * input to scale-stability scoring (consensus.ts). Resolutions are applied in
+ * the given order; the default ladder is {@link DEFAULT_RESOLUTIONS}.
+ */
+export declare function resolutionSweep(graph: WeightedGraph, resolutions?: readonly number[]): Partition[];
+//# sourceMappingURL=modularity.d.ts.map

package/dist/shared/decompose/modularity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modularity.d.ts","sourceRoot":"","sources":["../../../src/shared/decompose/modularity.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAyB,CAAC;AA0N3E;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,CAmC3E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,EACpB,WAAW,GAAE,SAAS,MAAM,EAAwB,GACnD,SAAS,EAAE,CAEb"}