sourcecode 2.1.0__py3-none-any.whl → 2.3.0__py3-none-any.whl

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.1.0"
+__version__ = "2.3.0"

sourcecode/archetype.py

@@ -0,0 +1,605 @@
+"""Evidence-based architectural archetype classifier (ADDITIVE / EXPERIMENTAL).
+
+Runs in PARALLEL with the legacy `ArchitectureAnalyzer` pattern. It does NOT feed
+the report wording yet — it exists so the new model can be validated against the
+legacy one across many repos before any cutover.
+
+Design goals (vs the legacy directory-name matcher):
+  * describe WHAT a system is, not which technologies it contains;
+  * accumulate weighted evidence from many signals — never a single dominant rule;
+  * weight every signal by CODE MASS (fraction of the codebase it represents), so a
+    directory named `api/` in a 5,600-file engine contributes ~0.003, not 1.0;
+  * report per-candidate score + evidence + confidence + a human explanation.
+
+Four ORTHOGONAL dimensions (a system is a point in each, not one enum):
+  * software_archetype : engine | platform | framework | library | application | compiler | sdk
+  * architectural_style: layered | hexagonal | clean | mvc | event-driven | plugin-based | microkernel
+  * deployment_shape   : monolith | multi-module | distributed | embedded
+  * primary_interface  : api-first | cli | worker | daemon | library | embedded
+
+Signals consumed today (all cheap / already computed by a normal scan):
+  module masses (file_tree), package-concept masses (path segments), entry-point
+  kinds, HTTP endpoint share, packaging, detected frameworks, and — when present on
+  the SourceMap — module_graph_summary (hubs/cycles). Richer signals (repo-ir
+  subsystem masses, Semantic-IR SPI fan-in, protocol handlers) are declared in
+  `signals_missing` when unavailable so the confidence reflects it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from sourcecode.graph_evidence import GraphEvidence, GraphEvidenceProvider, GraphEvidenceResult
+from sourcecode.schema import SourceMap
+from sourcecode.tree_utils import flatten_file_tree
+
+_JVM_EXTS = (".java", ".kt", ".kts", ".scala", ".groovy")
+_CODE_EXTS = _JVM_EXTS + (".py", ".go", ".rs", ".cs", ".ts", ".js", ".rb", ".php")
+_NON_SOURCE = frozenset({
+    "test", "tests", "src-test", "it", "benchmark", "benchmarks", "bench",
+    "example", "examples", "demo", "docs", "doc", "fixture", "fixtures",
+    "node_modules", "target", "build", "generated", "resources",
+})
+
+# Concept banks: path-segment keywords → a named concept. Mass of a concept =
+# fraction of source files whose path contains any of its segments. These are
+# DOMAIN concepts, not framework names; membership is deliberately broad.
+_CONCEPTS: dict[str, frozenset[str]] = {
+    "storage":     frozenset({"storage", "store", "pagecache", "pagecache", "recordstorage",
+                              "record", "btree", "gbptree", "wal", "log", "tx", "transaction",
+                              "commit", "checkpoint", "index", "lucene", "kvstore", "heap"}),
+    "kernel":      frozenset({"kernel", "engine", "executor", "runtime", "core", "internal"}),
+    "compiler":    frozenset({"parser", "lexer", "ast", "grammar", "antlr", "codegen",
+                              "compiler", "ir", "bytecode", "semantic", "typecheck", "rewriter",
+                              "planner", "optimizer", "expression"}),
+    "protocol":    frozenset({"protocol", "bolt", "netty", "transport", "wire", "packstream",
+                              "rpc", "grpc", "http", "connector", "connection"}),
+    "distributed": frozenset({"cluster", "raft", "discovery", "gossip", "consensus",
+                              "replication", "coordination", "membership", "fabric", "routing"}),
+    "web":         frozenset({"controller", "controllers", "rest", "mvc", "servlet",
+                              "endpoint", "endpoints", "resource", "webapp", "jaxrs"}),
+    "service":     frozenset({"service", "services", "usecase", "usecases", "application"}),
+    "repository":  frozenset({"repository", "repositories", "repo", "dao", "persistence"}),
+    "event":       frozenset({"event", "events", "listener", "listeners", "publisher",
+                              "subscriber", "bus", "dispatcher", "reactor"}),
+    "plugin":      frozenset({"plugin", "plugins", "extension", "extensions", "spi",
+                              "provider", "providers", "addon", "module"}),
+    "api_pkg":     frozenset({"api", "apis", "spi", "contract", "interfaces"}),
+    "cli":         frozenset({"cli", "command", "commands", "commandline", "shell", "console"}),
+    "hexagonal":   frozenset({"adapter", "adapters", "port", "ports"}),
+    "clean":       frozenset({"domain", "domains", "usecase", "usecases", "infrastructure", "infra"}),
+    "cqrs":        frozenset({"command", "commands", "query", "queries"}),
+    "sdk_client":  frozenset({"client", "clients", "sdk"}),
+}
+
+_CONF_ORDER = {"high": 3, "medium": 2, "low": 1}
+# A dimension whose best candidate scores below this is reported as undetermined
+# (primary=None) rather than asserting a label on noise.
+_MIN_PRIMARY_SCORE = 0.05
+# A winner must clear this absolute score (not just the top-2 margin) to earn
+# medium/high confidence — a near-floor lone candidate stays "low".
+_MIN_CONFIDENT_SCORE = 0.5
+
+
+@dataclass
+class Evidence:
+    signal: str          # machine name, e.g. "storage_mass"
+    detail: str          # human-readable
+    weight: float        # base importance of the signal
+    strength: float      # 0..1 — how strongly the signal is present
+    mass: float          # 0..1 — fraction of the codebase it represents (1.0 if N/A)
+    contribution: float  # weight * strength * mass (what actually adds to the score)
+
+
+@dataclass
+class ArchetypeCandidate:
+    label: str
+    score: float
+    evidence: list[Evidence] = field(default_factory=list)
+
+
+@dataclass
+class DimensionResult:
+    dimension: str
+    primary: Optional[str]
+    confidence: str                       # high | medium | low
+    candidates: list[ArchetypeCandidate]  # sorted score desc
+    explanation: str
+
+
+@dataclass
+class ArchetypeAnalysis:
+    dimensions: dict[str, DimensionResult]
+    signals_used: list[str]
+    signals_missing: list[str]
+    generated_from: str
+    graph_metrics: dict[str, float] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": "0.1-experimental",
+            "note": "Parallel/experimental model. Legacy architecture pattern is unchanged.",
+            "dimensions": {
+                dim: {
+                    "primary": r.primary,
+                    "confidence": r.confidence,
+                    "explanation": r.explanation,
+                    "candidates": [
+                        {
+                            "label": c.label,
+                            "score": round(c.score, 4),
+                            "evidence": [
+                                {
+                                    "signal": e.signal, "detail": e.detail,
+                                    "weight": e.weight, "strength": round(e.strength, 3),
+                                    "mass": round(e.mass, 4),
+                                    "contribution": round(e.contribution, 4),
+                                }
+                                for e in c.evidence
+                            ],
+                        }
+                        for c in r.candidates
+                    ],
+                }
+                for dim, r in self.dimensions.items()
+            },
+            "signals_used": self.signals_used,
+            "signals_missing": self.signals_missing,
+            "generated_from": self.generated_from,
+            "graph_metrics": {k: round(v, 4) for k, v in self.graph_metrics.items()},
+        }
+
+
+@dataclass
+class _Features:
+    total_files: int
+    module_counts: dict[str, int]
+    dominant_module: Optional[str]
+    dominant_share: float
+    module_count: int
+    concept_mass: dict[str, float]        # concept → fraction of source files
+    entry_kinds: dict[str, int]
+    endpoint_total: int
+    endpoint_share: float                 # endpoints per source file
+    packaging: Optional[str]
+    frameworks: set[str]
+    graph_hubs: list[str]
+    graph_cycles: int
+    graph_available: bool
+    graph_evidence: list[GraphEvidence]
+    graph_metrics: dict[str, float]
+    signals_used: list[str]
+    signals_missing: list[str]
+
+
+# Which archetype each topological metric supports, and how. Each entry is
+# (dimension, label, weight, polarity, lo, hi): the metric's raw value is ramped
+# to a strength via (value-lo)/(hi-lo) clamped to [0,1]; polarity +1 supports the
+# label, -1 refutes it (negative contribution). This is the ONLY place that knows
+# both graphs and archetypes — the provider stays archetype-agnostic, the scorer
+# stays graph-agnostic, and the coupling lives here as declarative data.
+_GRAPH_MAP: dict[str, list[tuple[str, str, float, int, float, float]]] = {
+    "scc_mass": [
+        ("software_archetype", "engine",      2.5, +1, 0.10, 0.50),
+        ("architectural_style", "layered",    1.5, -1, 0.10, 0.50),
+    ],
+    "cyclic_density": [
+        ("software_archetype", "engine",      2.0, +1, 0.05, 0.40),
+        ("architectural_style", "layered",    2.0, -1, 0.05, 0.40),
+        ("architectural_style", "hexagonal",  1.5, -1, 0.05, 0.40),
+        ("architectural_style", "microkernel", 1.5, -1, 0.05, 0.40),
+    ],
+    "hub_concentration": [
+        ("software_archetype", "engine",      1.5, +1, 0.10, 0.40),
+        ("architectural_style", "microkernel", 1.5, +1, 0.10, 0.40),
+    ],
+    "module_centralization": [
+        ("architectural_style", "microkernel", 2.0, +1, 0.30, 0.80),
+        ("architectural_style", "hexagonal",  1.5, -1, 0.30, 0.80),  # a single hub is not a distributed domain core
+        ("software_archetype", "platform",    0.8, +1, 0.30, 0.80),
+    ],
+    "downward_edge_ratio": [
+        ("architectural_style", "layered",    2.5, +1, 0.55, 0.90),
+        ("architectural_style", "hexagonal",  1.0, +1, 0.55, 0.90),
+    ],
+    "dependency_inversion_ratio": [
+        ("architectural_style", "hexagonal",  2.5, +1, 0.50, 0.80),
+        ("architectural_style", "clean",      1.5, +1, 0.50, 0.80),
+    ],
+    "fan_in_gini": [
+        ("software_archetype", "engine",      1.5, +1, 0.40, 0.75),
+    ],
+}
+
+
+class ArchetypeClassifier:
+    """Consumes a SourceMap; emits an ArchetypeAnalysis. Pure (no filesystem writes)."""
+
+    def analyze(
+        self,
+        sm: SourceMap,
+        root: Optional[Path] = None,
+        module_graph: object = None,
+    ) -> ArchetypeAnalysis:
+        f = self._extract_features(sm, root, module_graph)
+        dims = {
+            "software_archetype": self._software_archetype(f),
+            "architectural_style": self._architectural_style(f),
+            "deployment_shape": self._deployment_shape(f),
+            "primary_interface": self._primary_interface(f),
+        }
+        return ArchetypeAnalysis(
+            dimensions=dims,
+            signals_used=f.signals_used,
+            signals_missing=f.signals_missing,
+            generated_from=(
+                f"{f.total_files} source files, {f.module_count} modules, "
+                f"{f.endpoint_total} endpoints"
+            ),
+            graph_metrics=f.graph_metrics,
+        )
+
+    # ── feature extraction ────────────────────────────────────────────────────
+    def _extract_features(
+        self, sm: SourceMap, root: Optional[Path], module_graph: object = None,
+    ) -> _Features:
+        used: list[str] = []
+        missing: list[str] = []
+        paths = [p.replace("\\", "/") for p in (sm.file_paths or flatten_file_tree(sm.file_tree))]
+        src = [
+            p for p in paths
+            if p.endswith(_CODE_EXTS)
+            and not any(seg.lower() in _NON_SOURCE for seg in p.split("/")[:-1])
+        ]
+        total = len(src)
+
+        module_counts: dict[str, int] = {}
+        for p in src:
+            module_counts[self._module_of(p)] = module_counts.get(self._module_of(p), 0) + 1
+        module_counts.pop("", None)
+        dominant = max(module_counts, key=lambda m: module_counts[m], default=None)
+        dominant_share = (module_counts[dominant] / total) if (dominant and total) else 0.0
+        if module_counts:
+            used.append("module_masses")
+
+        # concept masses (share of source files whose path touches the concept)
+        concept_mass: dict[str, float] = {}
+        for concept, kws in _CONCEPTS.items():
+            hits = sum(
+                1 for p in src
+                if any(seg.lower() in kws for seg in p.split("/")[:-1])
+            )
+            concept_mass[concept] = (hits / total) if total else 0.0
+        if total:
+            used.append("concept_masses")
+
+        entry_kinds: dict[str, int] = {}
+        for ep in sm.entry_points or []:
+            k = getattr(ep, "kind", None) or "unknown"
+            entry_kinds[k] = entry_kinds.get(k, 0) + 1
+        if sm.entry_points:
+            used.append("entry_points")
+        else:
+            missing.append("entry_points")
+
+        endpoint_total = self._endpoint_count(root)
+        endpoint_share = (endpoint_total / total) if total else 0.0
+        if root is not None:
+            used.append("endpoints")
+        else:
+            missing.append("endpoints")
+
+        frameworks = {fw.name for s in (sm.stacks or []) for fw in s.frameworks}
+        if frameworks:
+            used.append("frameworks")
+
+        hubs: list[str] = []
+        cycles = 0
+        mgs = sm.module_graph_summary
+        if mgs is not None:
+            hubs = list(getattr(mgs, "hubs", []) or [])
+            cycles = int(getattr(mgs, "cycle_count", 0) or 0)
+            used.append("module_graph_summary")
+
+        # Module graph as a first-class Evidence Provider (ADR-0003 step 2).
+        # A ModuleGraph (nodes+edges) yields topological evidence the scorer can
+        # consume WITHOUT ever walking the graph. Absent/too-small graphs degrade
+        # to today's name-mass-only behaviour and are declared missing.
+        graph = module_graph if module_graph is not None else sm.module_graph
+        graph_result: GraphEvidenceResult = (
+            GraphEvidenceProvider().analyze(graph) if graph is not None
+            else GraphEvidenceResult(node_count=0, edge_count=0)
+        )
+        if graph_result.available:
+            used.append("module_graph")
+            if not cycles and graph_result.metric("cyclic_density") > 0:
+                cycles = 1  # topology confirms a cyclic core even without a summary
+        else:
+            missing.append("module_graph")
+        # Richer signals not wired yet — declare them so confidence reflects it.
+        missing.append("repo_ir_subsystem_masses")
+        missing.append("semantic_ir_spi_fanin")
+
+        return _Features(
+            total_files=total,
+            module_counts=module_counts,
+            dominant_module=dominant,
+            dominant_share=dominant_share,
+            module_count=len(module_counts),
+            concept_mass=concept_mass,
+            entry_kinds=entry_kinds,
+            endpoint_total=endpoint_total,
+            endpoint_share=endpoint_share,
+            packaging=sm.packaging,
+            frameworks=frameworks,
+            graph_hubs=hubs,
+            graph_cycles=cycles,
+            graph_available=graph_result.available,
+            graph_evidence=graph_result.evidence,
+            graph_metrics=graph_result.metrics,
+            signals_used=used,
+            signals_missing=missing,
+        )
+
+    # ── dimension scorers ─────────────────────────────────────────────────────
+    def _software_archetype(self, f: _Features) -> DimensionResult:
+        cm = f.concept_mass
+        cands: dict[str, list[Evidence]] = {a: [] for a in
+                                            ("engine", "compiler", "framework", "library",
+                                             "application", "platform", "sdk")}
+
+        def add(label: str, signal: str, detail: str, weight: float, strength: float, mass: float):
+            cands[label].append(Evidence(signal, detail, weight, strength,
+                                         mass, weight * strength * mass))
+
+        # engine: storage/kernel mass is the core of the codebase
+        eng_mass = min(1.0, cm["storage"] + cm["kernel"])
+        add("engine", "storage_kernel_mass",
+            f"storage+kernel packages ≈ {eng_mass:.0%} of source", 3.0, 1.0, eng_mass)
+        if f.graph_cycles > 0:
+            add("engine", "cyclic_core",
+                f"{f.graph_cycles} import cycle(s) — tightly-woven engine core", 1.0, 1.0, 0.5)
+        # compiler: parser/ast/ir/codegen pipeline mass
+        add("compiler", "compiler_pipeline_mass",
+            f"parser/ast/ir/codegen packages ≈ {cm['compiler']:.0%}", 3.0, 1.0, cm["compiler"])
+        # framework: plugin/SPI extension surface + jar packaging + not app-entry
+        fw_strength = 1.0 if f.packaging == "jar" else 0.6
+        add("framework", "extension_surface_mass",
+            f"plugin/SPI/provider packages ≈ {cm['plugin']:.0%}", 2.5, fw_strength, cm["plugin"])
+        # library/SDK: public API surface, no server/cli bootstrap
+        has_server = any(k in f.entry_kinds for k in ("server", "jax_rs_controller"))
+        has_bootstrap = "bootstrap" in f.entry_kinds or "application" in f.entry_kinds
+        lib_strength = 0.4 if (has_server or has_bootstrap) else 1.0
+        add("library", "public_api_no_runtime",
+            f"api/contract packages ≈ {cm['api_pkg']:.0%}; "
+            f"{'no' if lib_strength == 1.0 else 'has'} server/bootstrap entry",
+            2.0, lib_strength, max(cm["api_pkg"], 0.15))
+        if cm["sdk_client"] > 0.1:
+            add("sdk", "client_packages",
+                f"client/sdk packages ≈ {cm['sdk_client']:.0%}", 2.0, 1.0, cm["sdk_client"])
+        # application: has bootstrap/server + business (service) mass
+        if has_bootstrap or has_server:
+            add("application", "runtime_entry_plus_services",
+                f"bootstrap/server entry + service mass ≈ {cm['service']:.0%}",
+                2.0, 1.0, max(cm["service"], 0.2))
+        # platform: many modules + multiple concept clusters + distribution
+        multi = 1.0 if f.module_count >= 8 else f.module_count / 8
+        add("platform", "many_modules_multi_concern",
+            f"{f.module_count} modules; distributed mass ≈ {cm['distributed']:.0%}",
+            1.5, multi, max(cm["distributed"], 0.1))
+        self._apply_graph_evidence("software_archetype", cands, f)
+        return self._resolve("software_archetype", cands, f)
+
+    def _architectural_style(self, f: _Features) -> DimensionResult:
+        cm = f.concept_mass
+        cands: dict[str, list[Evidence]] = {a: [] for a in
+                                            ("layered", "hexagonal", "clean", "mvc",
+                                             "event-driven", "plugin-based", "microkernel")}
+
+        def add(label, signal, detail, weight, strength, mass):
+            cands[label].append(Evidence(signal, detail, weight, strength,
+                                         mass, weight * strength * mass))
+
+        # layered: needs BOTH web/controller AND service AND repository mass — and each
+        # must be non-trivial. Legacy asserted this from mere name presence; we weight
+        # by mass so a 0.3% `api/` dir does not manufacture a "controller layer".
+        layered_present = sum(1 for c in ("web", "service", "repository") if cm[c] >= 0.05)
+        layered_mass = min(1.0, cm["web"] + cm["service"] + cm["repository"])
+        add("layered", "layered_triplet_mass",
+            f"controller/service/repository mass ≈ {layered_mass:.0%} "
+            f"({layered_present}/3 layers above 5%)",
+            2.0, layered_present / 3, layered_mass)
+        # mvc requires a view/web surface with real mass
+        add("mvc", "web_view_mass", f"web/controller mass ≈ {cm['web']:.0%}",
+            2.0, 1.0 if cm["web"] >= 0.05 else 0.0, cm["web"])
+        # hexagonal / clean
+        add("hexagonal", "ports_adapters_mass", f"ports/adapters mass ≈ {cm['hexagonal']:.0%}",
+            2.5, 1.0, cm["hexagonal"])
+        add("clean", "domain_usecase_infra_mass", f"domain/usecase/infra mass ≈ {cm['clean']:.0%}",
+            2.5, 1.0, cm["clean"])
+        # event-driven
+        add("event-driven", "event_mass", f"event/listener/bus mass ≈ {cm['event']:.0%}",
+            2.0, 1.0, cm["event"])
+        # plugin-based / microkernel: plugin mass + small dominant core
+        add("plugin-based", "plugin_mass", f"plugin/extension mass ≈ {cm['plugin']:.0%}",
+            2.0, 1.0, cm["plugin"])
+        micro_strength = 1.0 if (cm["plugin"] > 0.05 and f.dominant_share < 0.4) else 0.0
+        add("microkernel", "small_core_many_plugins",
+            f"plugin mass ≈ {cm['plugin']:.0%}, dominant module {f.dominant_share:.0%}",
+            1.5, micro_strength, max(cm["plugin"], 0.1))
+        self._apply_graph_evidence("architectural_style", cands, f)
+        return self._resolve("architectural_style", cands, f)
+
+    def _deployment_shape(self, f: _Features) -> DimensionResult:
+        cm = f.concept_mass
+        cands: dict[str, list[Evidence]] = {a: [] for a in
+                                            ("monolith", "multi-module", "distributed", "embedded")}
+
+        def add(label, signal, detail, weight, strength, mass):
+            cands[label].append(Evidence(signal, detail, weight, strength,
+                                         mass, weight * strength * mass))
+
+        multi = 1.0 if f.module_count >= 3 else f.module_count / 3
+        add("multi-module", "module_count", f"{f.module_count} source modules", 2.0, multi, 1.0)
+        # monolith: modules but a single deployable (one war, or a single dominant module)
+        mono_strength = 1.0 if (f.packaging == "war" or f.dominant_share >= 0.5) else 0.3
+        add("monolith", "single_deployable",
+            f"packaging={f.packaging}, dominant module {f.dominant_share:.0%}",
+            1.5, mono_strength, 1.0)
+        add("distributed", "cluster_mass", f"cluster/raft/discovery mass ≈ {cm['distributed']:.0%}",
+            2.5, 1.0, cm["distributed"])
+        # embedded: library packaging + embeddable API, no server bootstrap
+        emb_strength = 1.0 if (f.packaging == "jar" and "server" not in f.entry_kinds) else 0.3
+        add("embedded", "library_packaging_no_server",
+            f"packaging={f.packaging}, {'no' if 'server' not in f.entry_kinds else 'has'} server entry",
+            1.5, emb_strength, 0.5)
+        return self._resolve("deployment_shape", cands, f)
+
+    def _primary_interface(self, f: _Features) -> DimensionResult:
+        cm = f.concept_mass
+        cands: dict[str, list[Evidence]] = {a: [] for a in
+                                            ("api-first", "cli", "worker", "daemon",
+                                             "library", "embedded")}
+
+        def add(label, signal, detail, weight, strength, mass):
+            cands[label].append(Evidence(signal, detail, weight, strength,
+                                         mass, weight * strength * mass))
+
+        # api-first: HTTP surface must be significant relative to size. Ramp so a
+        # rounding-error surface cannot win: 0 below 0.5 endpoints/100 files, linear
+        # to full strength at >=2/100 files. (neo4j: 18/5600 = 0.32/100 -> 0.)
+        density = f.endpoint_share * 100
+        api_strength = max(0.0, min(1.0, (density - 0.5) / 1.5)) if f.endpoint_total else 0.0
+        add("api-first", "endpoint_density",
+            f"{f.endpoint_total} endpoints over {f.total_files} files "
+            f"({density:.2f}/100 files)",
+            3.0, api_strength, 1.0)
+        cli_entries = f.entry_kinds.get("cli", 0)
+        add("cli", "cli_entry_points", f"{cli_entries} CLI entry point(s); cli mass ≈ {cm['cli']:.0%}",
+            2.5, 1.0 if cli_entries else (1.0 if cm["cli"] > 0.05 else 0.0), max(cm["cli"], 0.2))
+        add("daemon", "server_bootstrap",
+            f"server/bootstrap entries: {f.entry_kinds.get('server',0)+f.entry_kinds.get('bootstrap',0)}",
+            2.0, 1.0 if ("server" in f.entry_kinds or "bootstrap" in f.entry_kinds) else 0.0, 0.5)
+        add("worker", "event_no_http",
+            f"event mass ≈ {cm['event']:.0%}, endpoints={f.endpoint_total}",
+            1.5, 1.0 if (cm["event"] > 0.05 and f.endpoint_total == 0) else 0.0, max(cm["event"], 0.1))
+        lib_strength = 1.0 if (f.packaging == "jar" and not f.entry_kinds) else 0.3
+        add("library", "consumed_as_dependency",
+            f"packaging={f.packaging}, entry kinds={list(f.entry_kinds) or 'none'}",
+            1.5, lib_strength, 0.4)
+        add("embedded", "embeddable_api", f"api mass ≈ {cm['api_pkg']:.0%}, packaging={f.packaging}",
+            1.2, 1.0 if (f.packaging == "jar" and cm["api_pkg"] > 0.03) else 0.0, 0.4)
+        return self._resolve("primary_interface", cands, f)
+
+    # ── graph evidence bridge ──────────────────────────────────────────────────
+    def _apply_graph_evidence(
+        self, dimension: str, cands: dict[str, list[Evidence]], f: _Features,
+    ) -> None:
+        """Translate topological GraphEvidence into archetype Evidence for this
+        dimension, via the declarative `_GRAPH_MAP`. The scorer consumes evidence
+        objects here; it never inspects nodes or edges. A metric with polarity -1
+        contributes NEGATIVELY (e.g. a dense cyclic core refutes 'layered')."""
+        if not f.graph_available:
+            return
+        ev_by_kind = {e.kind: e for e in f.graph_evidence}
+        for kind, mappings in _GRAPH_MAP.items():
+            ge = ev_by_kind.get(kind)
+            if ge is None:
+                continue
+            for dim, label, weight, polarity, lo, hi in mappings:
+                if dim != dimension or label not in cands:
+                    continue
+                span = (hi - lo) or 1.0
+                strength = max(0.0, min(1.0, (ge.value - lo) / span))
+                if strength <= 0.0:
+                    continue
+                contribution = weight * strength * ge.mass * polarity
+                sign = "" if polarity > 0 else "_refutes"
+                cands[label].append(Evidence(
+                    signal=f"graph_{kind}{sign}",
+                    detail=ge.detail,
+                    weight=weight, strength=strength, mass=ge.mass,
+                    contribution=contribution,
+                ))
+
+    # ── conflict resolution + confidence ──────────────────────────────────────
+    def _resolve(self, dimension: str, raw: dict[str, list[Evidence]], f: _Features) -> DimensionResult:
+        candidates = [
+            ArchetypeCandidate(label=lbl, score=sum(e.contribution for e in evs), evidence=evs)
+            for lbl, evs in raw.items()
+        ]
+        candidates.sort(key=lambda c: c.score, reverse=True)
+        top = candidates[0] if candidates else None
+        runner = candidates[1] if len(candidates) > 1 else None
+        # Floor: do not declare a winner on negligible evidence (e.g. a 0.3% plugin
+        # dir "winning" architectural_style). Below it, the dimension is undetermined.
+        primary = top.label if top and top.score >= _MIN_PRIMARY_SCORE else None
+
+        # Confidence from margin between top-2 + whether mass/graph evidence backs it
+        # (vs name-only), plus penalties for missing richer signals.
+        confidence = "low"
+        if top and top.score > 0:
+            margin = top.score - (runner.score if runner else 0.0)
+            rel_margin = margin / top.score if top.score else 0.0
+            mass_backed = any(e.mass < 1.0 and e.contribution > 0 for e in top.evidence)
+            # Graph-backed = the WINNING conclusion is supported by real topology,
+            # not merely that a graph exists. Ties "high" confidence to structural
+            # evidence for THIS label (ADR-0003 acceptance criterion).
+            graph_backed = any(
+                e.signal.startswith("graph_") and e.contribution > 0 for e in top.evidence
+            )
+            # Elevated confidence also requires a non-marginal absolute score: a
+            # winner barely above the evidence floor is "undetermined-ish" and must
+            # not read as high/medium however lonely it is.
+            confident_enough = top.score >= _MIN_CONFIDENT_SCORE
+            if confident_enough and rel_margin >= 0.4 and mass_backed and graph_backed:
+                confidence = "high"
+            elif confident_enough and rel_margin >= 0.25 and mass_backed:
+                confidence = "medium"
+            else:
+                confidence = "low"
+
+        if primary is None:
+            explanation = (
+                f"No dominant {dimension.replace('_', ' ')}: best candidate "
+                f"'{top.label}' ({top.score:.3f}) is below the evidence floor "
+                f"({_MIN_PRIMARY_SCORE}) — undetermined."
+            ) if top else f"No evidence for {dimension.replace('_', ' ')}."
+            confidence = "low" if not top or top.score == 0 else confidence
+        else:
+            explanation = self._explain(dimension, top, runner)
+        return DimensionResult(dimension, primary, confidence, candidates, explanation)
+
+    def _explain(self, dimension: str, top: Optional[ArchetypeCandidate],
+                 runner: Optional[ArchetypeCandidate]) -> str:
+        if top is None or top.score <= 0:
+            return f"No archetype evidence for {dimension}."
+        parts = [f"{e.signal}(+{e.contribution:.3f})"
+                 for e in sorted(top.evidence, key=lambda e: e.contribution, reverse=True)
+                 if e.contribution > 0][:3]
+        base = f"'{top.label}' wins ({top.score:.3f}) on {', '.join(parts) or 'weak signals'}"
+        if runner and runner.score > 0:
+            base += f"; over '{runner.label}' ({runner.score:.3f})"
+        return base + "."
+
+    # ── helpers ───────────────────────────────────────────────────────────────
+    @staticmethod
+    def _module_of(path: str) -> str:
+        norm = path.replace("\\", "/")
+        idx = norm.find("/src/")
+        if idx > 0:
+            return norm[:idx]
+        head, _, tail = norm.partition("/")
+        return head if tail else ""
+
+    @staticmethod
+    def _endpoint_count(root: Optional[Path]) -> int:
+        if root is None:
+            return 0
+        try:
+            from sourcecode.repository_ir import extract_java_endpoints
+            data = extract_java_endpoints(root)
+            return int(data.get("total", len(data.get("endpoints", []))))
+        except Exception:
+            return 0