@backthread/extractor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Backthread
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @backthread/extractor
+
+Deterministic, install-free **structural extraction** for TypeScript and Python
+codebases. Point it at a working tree and it returns a structural graph of the
+system — modules, edges, communities, god-nodes, framework roles, and
+infrastructure — with **zero LLM, database, or network**.
+
+It's the open, auditable structural core behind [Backthread](https://backthread.dev).
+The extraction is exact and offline, so the same tree always yields the same
+graph; it never executes the analyzed repo's code.
+
+## What it does
+
+- **AST, install-free.** TypeScript via [ts-morph](https://ts-morph.com); Python
+  via Pyright's static analyzer under a no-filesystem-access host (never runs a
+  subprocess, never touches a virtualenv, never executes repo code). Import edges
+  are the backbone; call edges resolve through inferred types.
+- **Polyglot.** A TS-frontend + Python-backend repo extracts as one merged graph,
+  with a coarse cross-language frontend→backend HTTP-API seam.
+- **Communities + god-nodes.** Louvain community detection groups files into
+  modules; a statistical-outlier rule flags over-connected "god" modules.
+- **Framework-aware.** A fleet of adapters (Next, Nest, React Native, an ORM
+  layer, and a Python fleet: FastAPI, Django, Flask, Litestar, Celery, SQLAlchemy,
+  gRPC, GraphQL, and more) contributes synthetic edges, role tags, and grouping
+  priors — deterministically, from parser output only.
+- **Infra-aware.** Static readers for Cloudflare, Supabase, Terraform, and other
+  config surface deployment topology (workers, queues, datastores, …) without a
+  single API call.
+- **Incremental.** A SHA-keyed file graph re-parses only changed files on
+  re-extraction.
+
+## Install
+
+```sh
+npm install @backthread/extractor
+```
+
+## Usage
+
+```ts
+import { extract } from '@backthread/extractor';
+
+const result = await extract('/path/to/repo');
+
+console.log(result.cluster.modules); // modules with kinds, god-node flags, subsystems
+console.log(result.cluster.moduleEdges); // structural edges between modules
+console.log(result.infra); // deployment topology from config
+console.log(result.frameworks); // detected framework stacks
+```
+
+`extract()` is the one-shot convenience surface. Every stage is exported too, so
+you can compose your own pipeline — run the incremental extractor, warm-start
+clustering with a prior partition, or inject a resource-type classifier for
+open-ended IaC:
+
+```ts
+import {
+  extractGraph,
+  clusterGraph,
+  detectWorkspaceLayout,
+  contributeFrameworkGraph,
+  extractInfra,
+} from '@backthread/extractor';
+
+const graph = await extractGraph(repoDir);
+const layout = detectWorkspaceLayout(repoDir);
+const cluster = clusterGraph(graph, {}, { layout });
+await contributeFrameworkGraph({ repoDir, graph, cluster });
+const { graph: infra } = await extractInfra({ repoDir });
+```
+
+## Guarantees
+
+- **No code execution.** Pure static analysis.
+- **No network, no database, no LLM.** Extraction is fully offline and
+  deterministic. (You may optionally inject a `classifyResourceTypes` callback to
+  resolve unrecognized IaC resource types; without it, those keep a placeholder
+  kind.)
+- **Stable output.** Same tree + same options → same graph.
+
+## License
+
+MIT

package/dist/cluster/domain-grouping.d.ts

@@ -0,0 +1,113 @@
+export interface DomainGroup {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface ModuleAssignment {
+    groupId: string;
+    signature: string;
+}
+export interface GroupingModel {
+    groups: DomainGroup[];
+    assignments: Record<string, ModuleAssignment>;
+}
+export interface ProposedGroup {
+    name: string;
+    description?: string;
+}
+export interface LlmGrouping {
+    groups: ProposedGroup[];
+    assignments: Record<string, string>;
+}
+export interface ModuleSignal {
+    id: string;
+    summary: string;
+    whys: string[];
+}
+/**
+ * The per-module content SIGNATURE: a short hash of (summary + sorted decision
+ * ids + sorted changelog entry ids). It is the warm-start cache key — an
+ * unchanged signature means the module's semantic signal didn't materially move,
+ * so it keeps its cached group with NO LLM call. Sorted inputs make it
+ * order-independent; the slice keeps the cache JSON compact.
+ */
+export declare function moduleSignature(input: {
+    summary: string;
+    decisionIds: readonly string[];
+    changelogIds: readonly string[];
+}): string;
+/**
+ * Mint a STABLE, unique group id from a display name (slugify + de-collide
+ * against an in-use set). An empty/garbage name falls back to `group`. The
+ * `taken` set is mutated to reserve the returned id.
+ *
+ * the id is `domain:`-NAMESPACED so a domain-group id can NEVER equal a
+ * module id (a bare path-derived slug — slugify strips ':'). The domain-pass
+ * overwrites measured modules' `subsystem` with these ids when the gate trips;
+ * React Flow keys both module nodes and subsystem super-nodes by id, so a bare
+ * `billing-money` group colliding with a `billing-money` module would corrupt its
+ * node store (the  camera bug). The de-collision suffix is appended AFTER
+ * the namespaced base, so collisions stay namespaced too (`domain:foo-2`).
+ */
+export declare function mintGroupId(name: string, taken: Set<string>): string;
+/**
+ * MIGRATION: ensure every group id in a model is `domain:`-namespaced.
+ * A pre CACHED model (`subsystem_groups`) carries BARE ids that can equal
+ * a module id; the warm-start / cache-hit paths would otherwise carry those bare
+ * ids straight back onto the snapshots on a re-ingest. This maps each non-`domain:`
+ * id to `domain:<id>` (de-colliding against any already-namespaced id) and rewrites
+ * the assignments to match. Idempotent: an already-namespaced (or empty) model is
+ * returned unchanged. Only the OPAQUE id changes — display name/description and the
+ * member sets are untouched; the renderer treats subsystem ids opaquely and the
+ * uniform-apply rewrites every snapshot, so the one-time re-id is renderer-safe.
+ */
+export declare function namespaceModelIds(model: GroupingModel): GroupingModel;
+/**
+ * The WARM-START partition. Split the union of modules into:
+ *   - `kept`: modules whose cached signature is unchanged AND whose cached group
+ *     still exists → reuse the cached assignment, ZERO LLM.
+ *   - `pendingIds`: new modules (no cache row) or modules whose signal changed →
+ *     need (re)assignment by the LLM.
+ * With no cache, everything is pending (a first full pass).
+ */
+export declare function selectPending(unionIds: readonly string[], signatures: Record<string, string>, cached: GroupingModel | null): {
+    kept: Record<string, ModuleAssignment>;
+    pendingIds: string[];
+};
+/**
+ * Build a model from a FULL LLM pass (every module assigned from scratch). Mints
+ * a stable id per proposed group and resolves every assignment to it.
+ */
+export declare function buildFullModel(llm: LlmGrouping, signatures: Record<string, string>): GroupingModel;
+/**
+ * Build a model from an INCREMENTAL pass: keep the prior groups + the `kept`
+ * assignments verbatim (existing modules NEVER move — the zero-churn guarantee),
+ * fold in any genuinely-new groups the LLM proposed, and assign the pending
+ * modules. A "new" group whose name matches an existing one reuses that id (the
+ * LLM just re-named an existing domain), so we don't duplicate it.
+ */
+export declare function buildIncrementalModel(priorGroups: readonly DomainGroup[], kept: Record<string, ModuleAssignment>, llm: LlmGrouping, signatures: Record<string, string>): GroupingModel;
+/**
+ * Carry stable group ids across a FULL re-cluster (the anti-drift safety valve).
+ * Greedily map each NEW group to the PRIOR group it overlaps most (by shared
+ * member count), carrying the prior id so a re-cluster doesn't rename/re-id a
+ * domain that's substantially the same set of modules — the
+ * `stabilizeModuleIds` warm-start precedent. New groups with no prior overlap
+ * keep their freshly-minted id (re-minted on collision with a carried id).
+ * Returns a NEW model; inputs are untouched.
+ */
+export declare function reconcileGroupIds(next: GroupingModel, prior: GroupingModel): GroupingModel;
+/**
+ * The  finalize: DROP empty groups (an LLM-proposed group nobody landed
+ * in — a known Flash-Lite artifact) and ASSERT every module in `unionIds` is
+ * assigned to exactly one EXISTING group. Throws on any gap; the caller runs
+ * fail-soft, so a broken partition degrades to the directory default rather than
+ * persisting. Returns the pruned model.
+ */
+export declare function finalizeModel(model: GroupingModel, unionIds: readonly string[]): GroupingModel;
+export declare function groupToSubsystem(g: DomainGroup): {
+    id: string;
+    name: string;
+    description?: string;
+};
+//# sourceMappingURL=domain-grouping.d.ts.map

package/dist/cluster/domain-grouping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-grouping.d.ts","sourceRoot":"","sources":["../../src/cluster/domain-grouping.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC/C;AAGD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAKD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,GAAG,MAAM,CAOT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAOpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAqBrE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,MAAM,EAAE,aAAa,GAAG,IAAI,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAalE;AAmBD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,WAAW,EAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,aAAa,CAWf;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,SAAS,WAAW,EAAE,EACnC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACtC,GAAG,EAAE,WAAW,EAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,aAAa,CAgBf;AAWD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GAAG,aAAa,CAwD1F;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CAsB9F;AAGD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,WAAW,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAEnG"}

package/dist/cluster/domain-grouping.js

@@ -0,0 +1,277 @@
+// PURE helpers for the LLM domain-pass GROUPING MODEL: the per-repo
+// { groups, assignments } artifact that is cached in `subsystem_groups` and
+// applied UNIFORMLY to every snapshot (so the time slider never reshuffles a
+// box). No I/O, no LLM here — just the deterministic glue the orchestration
+// (decisions/subsystem-grouping.ts) and its tests share:
+//
+//   * content SIGNATURES (the warm-start cache key),
+//   * stable group-id minting,
+//   * the warm-start PARTITION (which modules can keep their cached group vs
+//     which need (re)assignment),
+//   * building the model from a FULL or INCREMENTAL LLM reply,
+//   * member-overlap id RECONCILIATION (carry ids across a full re-cluster — the
+//     stabilizeModuleIds precedent), and
+//   * the  TOTALITY finalize (drop empty groups + assert every module is
+//     in exactly one non-empty group).
+import { createHash } from 'node:crypto';
+import { slugify } from './overrides.js';
+import { DOMAIN_SUBSYSTEM_PREFIX } from './subsystem.js';
+/**
+ * The per-module content SIGNATURE: a short hash of (summary + sorted decision
+ * ids + sorted changelog entry ids). It is the warm-start cache key — an
+ * unchanged signature means the module's semantic signal didn't materially move,
+ * so it keeps its cached group with NO LLM call. Sorted inputs make it
+ * order-independent; the slice keeps the cache JSON compact.
+ */
+export function moduleSignature(input) {
+    const canonical = JSON.stringify({
+        s: input.summary ?? '',
+        d: [...input.decisionIds].sort(),
+        c: [...input.changelogIds].sort(),
+    });
+    return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}
+/**
+ * Mint a STABLE, unique group id from a display name (slugify + de-collide
+ * against an in-use set). An empty/garbage name falls back to `group`. The
+ * `taken` set is mutated to reserve the returned id.
+ *
+ * the id is `domain:`-NAMESPACED so a domain-group id can NEVER equal a
+ * module id (a bare path-derived slug — slugify strips ':'). The domain-pass
+ * overwrites measured modules' `subsystem` with these ids when the gate trips;
+ * React Flow keys both module nodes and subsystem super-nodes by id, so a bare
+ * `billing-money` group colliding with a `billing-money` module would corrupt its
+ * node store (the  camera bug). The de-collision suffix is appended AFTER
+ * the namespaced base, so collisions stay namespaced too (`domain:foo-2`).
+ */
+export function mintGroupId(name, taken) {
+    const base = DOMAIN_SUBSYSTEM_PREFIX + (slugify(name) || 'group');
+    let id = base;
+    let n = 2;
+    while (taken.has(id))
+        id = `${base}-${n++}`;
+    taken.add(id);
+    return id;
+}
+/**
+ * MIGRATION: ensure every group id in a model is `domain:`-namespaced.
+ * A pre CACHED model (`subsystem_groups`) carries BARE ids that can equal
+ * a module id; the warm-start / cache-hit paths would otherwise carry those bare
+ * ids straight back onto the snapshots on a re-ingest. This maps each non-`domain:`
+ * id to `domain:<id>` (de-colliding against any already-namespaced id) and rewrites
+ * the assignments to match. Idempotent: an already-namespaced (or empty) model is
+ * returned unchanged. Only the OPAQUE id changes — display name/description and the
+ * member sets are untouched; the renderer treats subsystem ids opaquely and the
+ * uniform-apply rewrites every snapshot, so the one-time re-id is renderer-safe.
+ */
+export function namespaceModelIds(model) {
+    if (model.groups.every((g) => g.id.startsWith(DOMAIN_SUBSYSTEM_PREFIX)))
+        return model;
+    // Reserve the ids already in the right namespace so a bare id can't collide onto one.
+    const taken = new Set(model.groups.filter((g) => g.id.startsWith(DOMAIN_SUBSYSTEM_PREFIX)).map((g) => g.id));
+    const remap = new Map(); // old bare id → namespaced id
+    const groups = model.groups.map((g) => {
+        if (g.id.startsWith(DOMAIN_SUBSYSTEM_PREFIX))
+            return g;
+        let id = DOMAIN_SUBSYSTEM_PREFIX + g.id;
+        let n = 2;
+        while (taken.has(id))
+            id = `${DOMAIN_SUBSYSTEM_PREFIX}${g.id}-${n++}`;
+        taken.add(id);
+        remap.set(g.id, id);
+        return { ...g, id };
+    });
+    const assignments = {};
+    for (const [moduleId, a] of Object.entries(model.assignments)) {
+        assignments[moduleId] = { groupId: remap.get(a.groupId) ?? a.groupId, signature: a.signature };
+    }
+    return { groups, assignments };
+}
+/**
+ * The WARM-START partition. Split the union of modules into:
+ *   - `kept`: modules whose cached signature is unchanged AND whose cached group
+ *     still exists → reuse the cached assignment, ZERO LLM.
+ *   - `pendingIds`: new modules (no cache row) or modules whose signal changed →
+ *     need (re)assignment by the LLM.
+ * With no cache, everything is pending (a first full pass).
+ */
+export function selectPending(unionIds, signatures, cached) {
+    const kept = {};
+    const pendingIds = [];
+    const groupIds = new Set((cached?.groups ?? []).map((g) => g.id));
+    for (const id of unionIds) {
+        const c = cached?.assignments[id];
+        if (c && c.signature === signatures[id] && groupIds.has(c.groupId)) {
+            kept[id] = c;
+        }
+        else {
+            pendingIds.push(id);
+        }
+    }
+    return { kept, pendingIds };
+}
+// Resolve LLM assignments (moduleId → group NAME) to {groupId, signature} via a
+// name→id map. A module whose chosen name doesn't resolve is left unassigned —
+// finalizeModel's totality assert is the single fail-loud gate for that, so we
+// never silently invent a group here.
+function resolveAssignments(llmAssignments, nameToId, signatures, into) {
+    for (const [moduleId, groupName] of Object.entries(llmAssignments)) {
+        const groupId = nameToId.get(groupName);
+        if (!groupId)
+            continue;
+        into[moduleId] = { groupId, signature: signatures[moduleId] ?? '' };
+    }
+}
+/**
+ * Build a model from a FULL LLM pass (every module assigned from scratch). Mints
+ * a stable id per proposed group and resolves every assignment to it.
+ */
+export function buildFullModel(llm, signatures) {
+    const taken = new Set();
+    const nameToId = new Map();
+    const groups = llm.groups.map((g) => {
+        const id = mintGroupId(g.name, taken);
+        nameToId.set(g.name, id);
+        return g.description ? { id, name: g.name, description: g.description } : { id, name: g.name };
+    });
+    const assignments = {};
+    resolveAssignments(llm.assignments, nameToId, signatures, assignments);
+    return { groups, assignments };
+}
+/**
+ * Build a model from an INCREMENTAL pass: keep the prior groups + the `kept`
+ * assignments verbatim (existing modules NEVER move — the zero-churn guarantee),
+ * fold in any genuinely-new groups the LLM proposed, and assign the pending
+ * modules. A "new" group whose name matches an existing one reuses that id (the
+ * LLM just re-named an existing domain), so we don't duplicate it.
+ */
+export function buildIncrementalModel(priorGroups, kept, llm, signatures) {
+    const taken = new Set(priorGroups.map((g) => g.id));
+    const nameToId = new Map();
+    for (const g of priorGroups)
+        nameToId.set(g.name, g.id);
+    const groups = [...priorGroups];
+    for (const g of llm.groups) {
+        if (nameToId.has(g.name))
+            continue; // re-proposed existing domain — reuse id
+        const id = mintGroupId(g.name, taken);
+        nameToId.set(g.name, id);
+        groups.push(g.description ? { id, name: g.name, description: g.description } : { id, name: g.name });
+    }
+    const assignments = { ...kept };
+    resolveAssignments(llm.assignments, nameToId, signatures, assignments);
+    return { groups, assignments };
+}
+/** Members (module ids) assigned to each group id, from a model's assignments. */
+function membersByGroup(model) {
+    const out = new Map();
+    for (const [moduleId, a] of Object.entries(model.assignments)) {
+        (out.get(a.groupId) ?? out.set(a.groupId, new Set()).get(a.groupId)).add(moduleId);
+    }
+    return out;
+}
+/**
+ * Carry stable group ids across a FULL re-cluster (the anti-drift safety valve).
+ * Greedily map each NEW group to the PRIOR group it overlaps most (by shared
+ * member count), carrying the prior id so a re-cluster doesn't rename/re-id a
+ * domain that's substantially the same set of modules — the
+ * `stabilizeModuleIds` warm-start precedent. New groups with no prior overlap
+ * keep their freshly-minted id (re-minted on collision with a carried id).
+ * Returns a NEW model; inputs are untouched.
+ */
+export function reconcileGroupIds(next, prior) {
+    const nextMembers = membersByGroup(next);
+    const priorMembers = membersByGroup(prior);
+    // All (nextId, priorId, overlap>0) pairs, strongest first.
+    const pairs = [];
+    for (const [nextId, nMembers] of nextMembers) {
+        for (const [priorId, pMembers] of priorMembers) {
+            let overlap = 0;
+            for (const m of nMembers)
+                if (pMembers.has(m))
+                    overlap += 1;
+            if (overlap > 0)
+                pairs.push({ nextId, priorId, overlap });
+        }
+    }
+    pairs.sort((a, b) => b.overlap - a.overlap || (a.nextId < b.nextId ? -1 : 1));
+    const remap = new Map(); // nextId → priorId
+    const claimedPrior = new Set();
+    const claimedNext = new Set();
+    for (const { nextId, priorId } of pairs) {
+        if (claimedNext.has(nextId) || claimedPrior.has(priorId))
+            continue;
+        remap.set(nextId, priorId);
+        claimedNext.add(nextId);
+        claimedPrior.add(priorId);
+    }
+    // Reserve carried prior ids; re-mint any unmatched next id that would collide.
+    const taken = new Set(remap.values());
+    const finalIdFor = new Map();
+    for (const g of next.groups) {
+        const carried = remap.get(g.id);
+        if (carried) {
+            finalIdFor.set(g.id, carried);
+            continue;
+        }
+        // Unmatched: keep its own id unless a carried id already took it.
+        let id = g.id;
+        if (taken.has(id))
+            id = mintGroupId(g.name, taken);
+        else
+            taken.add(id);
+        finalIdFor.set(g.id, id);
+    }
+    // Carry the prior group's NAME/description for a matched group (id + label
+    // stay together so the carried box reads identically to before).
+    const priorById = new Map(prior.groups.map((g) => [g.id, g]));
+    const groups = next.groups.map((g) => {
+        const id = finalIdFor.get(g.id);
+        const carried = remap.has(g.id) ? priorById.get(id) : undefined;
+        const name = carried?.name ?? g.name;
+        const description = g.description ?? carried?.description;
+        return description ? { id, name, description } : { id, name };
+    });
+    const assignments = {};
+    for (const [moduleId, a] of Object.entries(next.assignments)) {
+        assignments[moduleId] = { groupId: finalIdFor.get(a.groupId) ?? a.groupId, signature: a.signature };
+    }
+    return { groups, assignments };
+}
+/**
+ * The  finalize: DROP empty groups (an LLM-proposed group nobody landed
+ * in — a known Flash-Lite artifact) and ASSERT every module in `unionIds` is
+ * assigned to exactly one EXISTING group. Throws on any gap; the caller runs
+ * fail-soft, so a broken partition degrades to the directory default rather than
+ * persisting. Returns the pruned model.
+ */
+export function finalizeModel(model, unionIds) {
+    const members = membersByGroup(model);
+    const groups = model.groups.filter((g) => (members.get(g.id)?.size ?? 0) > 0);
+    const liveIds = new Set(groups.map((g) => g.id));
+    const missing = [];
+    const dangling = [];
+    for (const id of unionIds) {
+        const a = model.assignments[id];
+        if (!a) {
+            missing.push(id);
+        }
+        else if (!liveIds.has(a.groupId)) {
+            dangling.push(id);
+        }
+    }
+    if (missing.length || dangling.length) {
+        const parts = [];
+        if (missing.length)
+            parts.push(`${missing.length} unassigned (${missing.slice(0, 5).join(', ')}…)`);
+        if (dangling.length)
+            parts.push(`${dangling.length} in a dropped/unknown group (${dangling.slice(0, 5).join(', ')}…)`);
+        throw new Error(`domain grouping is not a complete partition: ${parts.join('; ')}`);
+    }
+    return { groups, assignments: model.assignments };
+}
+// A group resolved to a Module.subsystem shape (id + name + optional description).
+export function groupToSubsystem(g) {
+    return g.description ? { id: g.id, name: g.name, description: g.description } : { id: g.id, name: g.name };
+}
+//# sourceMappingURL=domain-grouping.js.map

package/dist/cluster/domain-grouping.js.map

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

package/dist/cluster/grouping-gate.d.ts

@@ -0,0 +1,54 @@
+export declare const LAYER_NAMES: ReadonlySet<string>;
+export declare const GATE_THRESHOLDS: {
+    readonly layerNamedFraction: 0.3;
+    readonly singletonBoxRatio: 0.35;
+    readonly godBucketRatio: 0.35;
+};
+export declare function isFrameworkSubsystemId(id: string | undefined): boolean;
+/** One internal code module's gate input: its id + the file ids it owns (used
+ *  only to derive the dominant directory box). `subsystemId` is the
+ *  module's CURRENT subsystem id, if any: an adapter-namespaced one means the
+ *  framework already grouped it, so the gate EXCLUDES it from the directory-
+ *  quality measurement (optional + backward-compatible — absent ⇒ measured). */
+export interface GateModule {
+    id: string;
+    fileIds: readonly string[];
+    subsystemId?: string;
+}
+export interface GroupingGateResult {
+    /** layerNamedFraction ≥ 0.30 OR singletonBoxRatio ≥ 0.35 OR godBucketRatio ≥ 0.35. */
+    trips: boolean;
+    /** Layer-named MODULES ÷ total internal modules. */
+    layerNamedFraction: number;
+    /** Singleton (1-module) BOXES ÷ total BOXES — the fragmentation signal. Note the
+     *  BOX denominator (ratified against example-app: 3 singleton boxes of 8 →
+     *  0.375), distinct from the two module-denominator ratios. */
+    singletonBoxRatio: number;
+    /** Largest directory box size ÷ total internal MODULES (the mega-bucket smell;
+     *  ratified against marola: 8/18 ≈ 0.44). */
+    godBucketRatio: number;
+    /** How many internal DIRECTORY-derived modules the gate ranged over (framework-
+     *  grouped modules are excluded — see `frameworkExcluded`). */
+    internalCount: number;
+    /** how many framework-grouped (adapter-namespaced) modules were
+     *  excluded from the measurement above. Surfaced so the orchestration can log
+     *  the pin/skip (no silent caps) and audit why a framework-grouped repo didn't
+     *  trip the LLM domain-pass. */
+    frameworkExcluded: number;
+    /** Human-readable threshold(s) that tripped — persisted to the cache `gate`
+     *  column + logged, so we can always audit WHY a repo did/didn't get the lens. */
+    reasons: string[];
+}
+/**
+ * Evaluate the three directory-quality ratios over a repo's internal modules.
+ *
+ * Each module is bucketed by its dominant top-level directory. A ROOT-LEVEL
+ * module (no top-level dir at all — `dominantTopLevelDir` returns null) gets its
+ * OWN unique box, so it reads as a singleton and is never merged with other
+ * root files — which is correct: a loose root module is exactly the un-grouped
+ * smell the gate is meant to detect.
+ *
+ * An empty input never trips (there is nothing to group).
+ */
+export declare function evaluateGroupingGate(modules: ReadonlyArray<GateModule>): GroupingGateResult;
+//# sourceMappingURL=grouping-gate.d.ts.map

package/dist/cluster/grouping-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grouping-gate.d.ts","sourceRoot":"","sources":["../../src/cluster/grouping-gate.ts"],"names":[],"mappings":"AA+BA,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,CAG1C,CAAC;AAKH,eAAO,MAAM,eAAe;;;;CAIlB,CAAC;AAgBX,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAGtE;AAED;;;;gFAIgF;AAChF,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,KAAK,EAAE,OAAO,CAAC;IACf,oDAAoD;IACpD,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;mEAE+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;IAC1B;iDAC6C;IAC7C,cAAc,EAAE,MAAM,CAAC;IACvB;mEAC+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB;;;oCAGgC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B;sFACkF;IAClF,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,GACjC,kBAAkB,CAoEpB"}

package/dist/cluster/grouping-gate.js.map

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