loomweave-plugin-python 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

loomweave_plugin_python/__init__.py

@@ -1,3 +1,3 @@
 """loomweave-plugin-python — Python language plugin for Loomweave."""
 
-__version__ = "1.0.0"
+__version__ = "1.2.0"

loomweave_plugin_python/extractor.py

@@ -3,7 +3,11 @@
 Walks a parsed Python file and emits one ``module`` entity per file plus
 one ``function`` entity per ``FunctionDef`` / ``AsyncFunctionDef`` and one
 ``class`` entity per ``ClassDef``. It also emits anchored scan-time
-``imports``, ``calls``, and ``references`` candidate edges.
+``imports``, ``calls``, ``references``, ``inherits_from``, and ``decorates``
+candidate edges. The last three share one resolution pass: base-class and
+decorator expressions become ``base`` / ``decorator`` relation sites in the
+same collector that gathers generic reference sites, and the site kind
+selects the emitted edge kind (see ``reference_resolver.ReferenceSiteKind``).
 
 Entity shape matches the Rust host's ``RawEntity`` + ``RawSource``
 contract (``crates/loomweave-core/src/plugin/host.rs:132-154``)::
@@ -40,6 +44,12 @@ Behaviour (B.2 §3 Q1 supersedes Sprint-1 UQ-WP3-11 for module entities):
   with ``parse_status="syntax_error"`` plus one stderr log line
   (UQ-WP3-02). The run continues; WP4-era findings can later attach a
   ``LMWV-PY-SYNTAX-ERROR`` annotation.
+- ``RecursionError``/``MemoryError`` from hostile or degenerate nesting
+  (deep BinOp/attribute chains, unary prefix runs) — whether raised by
+  ``ast.parse`` itself or by the post-parse walkers — → one degraded
+  module entity with ``parse_status="too_complex"`` plus a
+  ``LMWV-PY-TOO-COMPLEX`` plugin finding (clarion-f3eb3852d6; Rust
+  parse-guard parity, ADR-050). The plugin process survives.
 - Top-level ``__init__.py`` (where the dotted module name resolves to
   ``""``) is skipped with stderr; the entity-ID assembler rejects an
   empty ``canonical_qualified_name``.
@@ -85,6 +95,18 @@ if TYPE_CHECKING:
 
 _PLUGIN_ID = "python"
 _NOOP_CALL_RESOLVER = NoOpCallResolver()
+
+# Deep-nesting degradation (clarion-f3eb3852d6; Rust parse-guard parity,
+# ADR-050). CPython's tokenizer self-limits indentation (100) and paren
+# nesting (~200) as SyntaxError, but indentation-free deep ASTs (BinOp
+# chains, attribute chains, unary prefix runs) pass tokenization and blow
+# up later: ast.parse raises RecursionError ("during ast construction") or
+# MemoryError ("Parser stack overflowed"), and chains as shallow as ~350
+# nodes blow Python-level NodeVisitor recursion in the post-parse walkers
+# AFTER a clean parse. All three degrade to a `too_complex` module entity
+# plus this plugin finding — escaping would fail the whole plugin run at
+# the host's analyze_file boundary.
+FINDING_TOO_COMPLEX = "LMWV-PY-TOO-COMPLEX"
 _NOOP_REFERENCE_RESOLVER = NoOpReferenceResolver()
 
 
@@ -180,7 +202,7 @@ class RawEntity(TypedDict):
     qualified_name: str
     source: EntitySource
     parent_id: NotRequired[str]
-    parse_status: NotRequired[Literal["ok", "syntax_error"]]
+    parse_status: NotRequired[Literal["ok", "syntax_error", "too_complex"]]
     # entity_context evidence (clarion-460def6a51). Set on function/class
     # entities; omitted for modules. Rides the host's RawEntity `extra` flatten
     # into `properties_json`, so no host or storage schema change is needed.
@@ -323,7 +345,7 @@ def _build_module_entity(
     source: str,
     dotted_module: str,
     file_path: str,
-    parse_status: Literal["ok", "syntax_error"],
+    parse_status: Literal["ok", "syntax_error", "too_complex"],
     docstring: str | None = None,
 ) -> RawEntity:
     """Build the per-file module entity (Q1 + Q4 resolutions)."""
@@ -424,6 +446,17 @@ def extract_with_stats(  # noqa: PLR0913 - resolver seams + optional Wardline vo
             [],
             ExtractionStats(extractor_parse_latency_ms=parse_latency_ms),
         )
+    except (RecursionError, MemoryError) as exc:
+        # Deep AST construction (RecursionError) or PEG parser stack guard
+        # (MemoryError) — see FINDING_TOO_COMPLEX. Stack is unwound here.
+        return _too_complex_result(
+            source,
+            dotted_module,
+            file_path,
+            "parse",
+            exc,
+            _elapsed_ms(parse_started_ns),
+        )
     parse_latency_ms = _elapsed_ms(parse_started_ns)
 
     module_entity = _build_module_entity(
@@ -432,35 +465,51 @@ def extract_with_stats(  # noqa: PLR0913 - resolver seams + optional Wardline vo
     entities: list[RawEntity] = [module_entity]
     edges: list[RawEdge] = []
     function_ids: list[str] = []
-    walk_state = _WalkState(
-        seen_ids={module_entity["id"]},
-        file_path=file_path,
-        exported_names=_module_export_names(tree),
-        wardline_vocabulary=wardline_vocabulary,
-    )
-    _walk(
-        tree,
-        [tree],
-        dotted_module,
-        file_path,
-        module_entity["id"],
-        entities,
-        edges,
-        function_ids,
-        walk_state,
-    )
-    edges.extend(
-        _collect_import_edges(
-            source,
+    try:
+        walk_state = _WalkState(
+            seen_ids={module_entity["id"]},
+            file_path=file_path,
+            exported_names=_module_export_names(tree),
+            wardline_vocabulary=wardline_vocabulary,
+        )
+        _walk(
             tree,
+            [tree],
             dotted_module,
+            file_path,
             module_entity["id"],
-            is_package_module=is_package_module,
-        ),
-    )
-    reference_sites = _collect_reference_sites(source, tree, dotted_module, module_entity["id"])
-    call_stats = call_resolver.resolve_calls(file_path, function_ids)
-    reference_stats = reference_resolver.resolve_references(file_path, reference_sites)
+            entities,
+            edges,
+            function_ids,
+            walk_state,
+        )
+        edges.extend(
+            _collect_import_edges(
+                source,
+                tree,
+                dotted_module,
+                module_entity["id"],
+                is_package_module=is_package_module,
+            ),
+        )
+        reference_sites = _collect_reference_sites(source, tree, dotted_module, module_entity["id"])
+        call_stats = call_resolver.resolve_calls(file_path, function_ids)
+        reference_stats = reference_resolver.resolve_references(file_path, reference_sites)
+    except (RecursionError, MemoryError) as exc:
+        # A tree can parse cleanly (the C parser's limit is deeper than the
+        # Python recursion limit) and still blow the recursive NodeVisitor
+        # walkers / pyright function index at ~350+ nesting. Degrade the
+        # whole file: partially-walked entities/edges are discarded so the
+        # emission is all-or-nothing per file.
+        return _too_complex_result(
+            source,
+            dotted_module,
+            file_path,
+            "extract",
+            exc,
+            parse_latency_ms,
+            ast.get_docstring(tree),
+        )
     edges.extend(cast("list[RawEdge]", call_stats.edges))
     edges.extend(cast("list[RawEdge]", reference_stats.edges))
     stats = ExtractionStats.from_resolution_results(call_stats, reference_stats)
@@ -469,6 +518,46 @@ def extract_with_stats(  # noqa: PLR0913 - resolver seams + optional Wardline vo
     return ExtractResult(entities, edges, stats)
 
 
+def _too_complex_result(  # noqa: PLR0913 - degraded-path builder mirrors the syntax_error arm's inputs.
+    source: str,
+    dotted_module: str,
+    file_path: str,
+    phase: Literal["parse", "extract"],
+    exc: BaseException,
+    parse_latency_ms: int,
+    docstring: str | None = None,
+) -> ExtractResult:
+    """Degrade a nesting-bomb file to a `too_complex` module entity + finding.
+
+    Mirrors the Rust plugin's parse-guard degrade-to-finding pattern
+    (ADR-050): the file is ingested as a single degraded module entity, the
+    failure is visible as a `LMWV-PY-TOO-COMPLEX` plugin finding riding the
+    findings wire, and the plugin (and the host's run) survives.
+    """
+    sys.stderr.write(
+        f"loomweave-plugin-python: degrading {file_path}: nesting too complex "
+        f"during {phase} ({type(exc).__name__})\n",
+    )
+    stats = ExtractionStats(extractor_parse_latency_ms=parse_latency_ms)
+    stats.findings.append(
+        Finding(
+            subcode=FINDING_TOO_COMPLEX,
+            severity="warning",
+            message=(
+                f"{file_path}: source nesting too complex to extract "
+                f"({type(exc).__name__} during {phase}); file ingested as a "
+                "degraded module entity"
+            ),
+            metadata={"phase": phase, "exception": type(exc).__name__},
+        ),
+    )
+    return ExtractResult(
+        [_build_module_entity(source, dotted_module, file_path, "too_complex", docstring)],
+        [],
+        stats,
+    )
+
+
 def _elapsed_ms(started_ns: int) -> int:
     return max(1, (time.perf_counter_ns() - started_ns + 999_999) // 1_000_000)
 
@@ -710,6 +799,7 @@ class _ReferenceSiteCollector(ast.NodeVisitor):
         if _has_overload_decorator(node):
             return
         function_id = self._entity_id_for_scope("function", node)
+        self._collect_decorator_sites(node, function_id)
         self.owner_stack.append(function_id)
         self.bound_stack.append(_scope_local_names(node))
         self._visit_function_signature(node)
@@ -722,6 +812,16 @@ class _ReferenceSiteCollector(ast.NodeVisitor):
 
     def visit_ClassDef(self, node: ast.ClassDef) -> None:
         class_id = self._entity_id_for_scope("class", node)
+        self._collect_decorator_sites(node, class_id)
+        # Base expressions become `base` relation sites owned by the subclass
+        # (resolved into `inherits_from` edges). Call bases (`class X(make())`)
+        # are outside the relation envelope: the call's *result* is the base,
+        # so anchoring the callee would assert a false inheritance fact.
+        # Keyword arguments (`metaclass=...`) are likewise out of scope.
+        for base in node.bases:
+            anchor = _relation_anchor(base)
+            if anchor is not None:
+                self.sites.append(self._site_for_relation(anchor, class_id, "base"))
         self.owner_stack.append(class_id)
         self.bound_stack.append(_scope_local_names(node))
         self.parents.append(node)
@@ -793,6 +893,59 @@ class _ReferenceSiteCollector(ast.NodeVisitor):
         )
         return entity_id(_PLUGIN_ID, kind, qualified_name)
 
+    def _collect_decorator_sites(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef,
+        owner_id: str,
+    ) -> None:
+        """Emit one ``decorator`` relation site per reducible decorator.
+
+        ``owner_id`` is the *decorated* entity (the site owner); the resolver
+        inverts direction at edge construction so the stored edge reads
+        ``decorator decorates decorated`` (`from_id` = decorator entity).
+        Factory decorators (``@app.route("/x")``) reduce to the callee path —
+        the factory is the entity that decorates, its arguments are not part
+        of the relation token.
+        """
+        for decorator in node.decorator_list:
+            target = decorator.func if isinstance(decorator, ast.Call) else decorator
+            anchor = _relation_anchor(target)
+            if anchor is not None:
+                self.sites.append(self._site_for_relation(anchor, owner_id, "decorator"))
+
+    def _site_for_relation(
+        self,
+        anchor: ast.Name | ast.Attribute,
+        from_id: str,
+        kind: Literal["base", "decorator"],
+    ) -> ReferenceSite:
+        """Build a relation site anchored on the full dotted path token.
+
+        The anchored byte range covers the whole path (Rust parity: the
+        implemented-trait PATH's span in ``impl Tr for Foo``), while the
+        pyright query position lands on the *final* attribute segment so
+        ``helpers.Base`` resolves the class, not the module prefix.
+        """
+        start_line = anchor.lineno - 1
+        end_line = (anchor.end_lineno or anchor.lineno) - 1
+        end_col = anchor.end_col_offset if anchor.end_col_offset is not None else anchor.col_offset
+        if isinstance(anchor, ast.Attribute):
+            query_line = end_line
+            query_byte_col = end_col - len(anchor.attr.encode("utf-8"))
+        else:
+            query_line = start_line
+            query_byte_col = anchor.col_offset
+        return ReferenceSite(
+            from_id=from_id,
+            line=query_line,
+            character=_byte_col_to_lsp_character(self.source_lines[query_line], query_byte_col),
+            end_line=end_line,
+            end_character=_byte_col_to_lsp_character(self.source_lines[end_line], end_col),
+            source_byte_start=self.line_starts[start_line] + anchor.col_offset,
+            source_byte_end=self.line_starts[end_line] + end_col,
+            kind=kind,
+        )
+
     def _site_for_name(self, node: ast.Name) -> ReferenceSite:
         line = node.lineno - 1
         end_line = (node.end_lineno or node.lineno) - 1
@@ -811,6 +964,23 @@ class _ReferenceSiteCollector(ast.NodeVisitor):
         )
 
 
+def _relation_anchor(expr: ast.expr) -> ast.Name | ast.Attribute | None:
+    """Reduce a base/decorator expression to its resolvable path token.
+
+    ``Name`` and ``Attribute`` are the anchor itself; ``Subscript`` reduces to
+    its value (``Generic[T]`` → ``Generic``). Anything else (calls, literals,
+    conditional expressions) has no stable path token and yields no relation
+    site — the resolution-side precise-entity discipline would drop it anyway.
+    """
+    match expr:
+        case ast.Name() | ast.Attribute():
+            return expr
+        case ast.Subscript(value=value):
+            return _relation_anchor(value)
+        case _:
+            return None
+
+
 def _line_starts(source: str) -> tuple[int, ...]:
     starts = [0]
     total = 0

loomweave_plugin_python/pyright_session.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import ast
 import ctypes
 import ctypes.util
+import errno
 import json
 import math
 import os
@@ -41,6 +42,8 @@ FINDING_PYRIGHT_POISON_FRAME = "LMWV-PY-PYRIGHT-POISON-FRAME"
 FINDING_PYRIGHT_INIT_TIMEOUT = "LMWV-PY-PYRIGHT-INIT-TIMEOUT"
 FINDING_PYRIGHT_UNAVAILABLE = "LMWV-PY-PYRIGHT-UNAVAILABLE"
 FINDING_PYRIGHT_INSTALL_FAILURE = "LMWV-PY-PYRIGHT-INSTALL-FAILURE"
+FINDING_PYRIGHT_SPAWN_DEFERRED = "LMWV-PY-PYRIGHT-SPAWN-DEFERRED"
+FINDING_PYRIGHT_RESOURCE_EXHAUSTED = "LMWV-PY-PYRIGHT-RESOURCE-EXHAUSTED"
 FINDING_PYRIGHT_CALL_RESOLUTION_TIMEOUT = "LMWV-PY-CALL-RESOLUTION-TIMEOUT"
 FINDING_PYRIGHT_REFERENCE_RESOLUTION_TIMEOUT = "LMWV-PY-REFERENCE-RESOLUTION-TIMEOUT"
 FINDING_PYRIGHT_REFERENCE_SITE_CAP = "LMWV-PY-REFERENCE-SITE-CAP"
@@ -56,21 +59,44 @@ class PyrightRunState:
     consume ``ceil(N/25) * 3`` restarts instead of 3 for an entire analysis
     run. Pass the same ``PyrightRunState`` instance to every successive
     ``PyrightSession`` so the budget is enforced across the full run.
+
+    ``consecutive_spawn_deferrals`` tracks transient (resource-pressure) spawn
+    failures separately from the ``restart_count`` crash budget: it is reset to
+    zero on every successful spawn, so intermittent pressure never poisons the
+    run, while a sustained run of deferrals still terminates pyright once it
+    exceeds ``MAX_CONSECUTIVE_SPAWN_DEFERRALS``.
     """
 
     restart_count: int = 0
     disabled: bool = False
+    consecutive_spawn_deferrals: int = 0
 
 
 MAX_UNRESOLVED_CALLEE_EXPR_BYTES = 512
 MAX_PYRIGHT_RESTARTS_PER_RUN = 3
+# A spawn that fails with one of these errnos is a *transient* resource-pressure
+# condition (the host is momentarily out of process slots / memory), not a broken
+# install. EAGAIN in particular is what a busy workstation returns from fork(2)
+# when the per-UID RLIMIT_NPROC is hit. These are deferred-and-retried rather
+# than treated as a permanent install failure.
+_TRANSIENT_SPAWN_ERRNOS = frozenset({errno.EAGAIN, errno.ENOMEM, errno.EMFILE, errno.ENFILE})
+# Upper bound on *consecutive* transient spawn deferrals before pyright is
+# disabled for the run. Reset to zero on any successful spawn, so this only
+# fires under sustained pressure, never on an intermittent blip. A failed fork
+# costs microseconds, so retrying once per file across a large run is cheap.
+MAX_CONSECUTIVE_SPAWN_DEFERRALS = 50
 MAX_REFERENCE_SITES_PER_FILE = 2000
 PYRIGHT_INIT_TIMEOUT_SECS = 30.0
 PYRIGHT_CALL_TIMEOUT_SECS = 5.0
-PYRIGHT_FILE_TIMEOUT_SECS = 3.0
+# Per-file wall-clock budget for reference resolution. Large, heavily-typed
+# files (e.g. numpy/torch-vectorised ML code) can starve a tighter budget and
+# surface LMWV-PY-REFERENCE-RESOLUTION-TIMEOUT findings with edges left
+# unresolved. Such files are rare enough that the extra ceiling is worth the
+# more-complete graph.
+PYRIGHT_FILE_TIMEOUT_SECS = 10.0
 STDERR_TAIL_LIMIT = 65536
 PYRIGHT_EXCLUDE_PATTERNS = [
-    "**/.loomweave/**",
+    "**/.weft/**",
     "**/.git/**",
     "**/.hg/**",
     "**/.svn/**",
@@ -79,7 +105,7 @@ PYRIGHT_EXCLUDE_PATTERNS = [
     "**/__pycache__/**",
     "**/node_modules/**",
 ]
-PROJECT_LOCAL_EXTERNAL_DIRS = {".loomweave", ".git", ".hg", ".svn", ".jj", ".venv", "node_modules"}
+PROJECT_LOCAL_EXTERNAL_DIRS = {".weft", ".git", ".hg", ".svn", ".jj", ".venv", "node_modules"}
 
 
 if TYPE_CHECKING:
@@ -144,6 +170,7 @@ class _FunctionIndex:
 
 @dataclass
 class _ReferenceEdgeAccumulator:
+    kind: Literal["references", "inherits_from", "decorates"]
     from_id: str
     to_id: str
     source_byte_start: int
@@ -151,6 +178,17 @@ class _ReferenceEdgeAccumulator:
     candidates: set[str]
 
 
+# Site kind → emitted edge kind (clarion-43416be550). `name`/`annotation`
+# sites keep producing `references`; the two relation kinds map onto the
+# ontology kinds that were previously declared-but-dead for Python.
+_EDGE_KIND_BY_SITE_KIND: dict[str, Literal["references", "inherits_from", "decorates"]] = {
+    "name": "references",
+    "annotation": "references",
+    "base": "inherits_from",
+    "decorator": "decorates",
+}
+
+
 class PyrightSession:
     def __init__(  # noqa: PLR0913 - knobs are tested lifecycle boundaries.
         self,
@@ -484,7 +522,7 @@ class PyrightSession:
             },
         )
         try:
-            accumulators: dict[tuple[str, str], _ReferenceEdgeAccumulator] = {}
+            accumulators: dict[tuple[str, str, str], _ReferenceEdgeAccumulator] = {}
             lookup_cache: dict[
                 tuple[str, str, str, int, int, int, int], tuple[list[str], bool]
             ] = {}
@@ -518,6 +556,7 @@ class PyrightSession:
                                 deadline=deadline,
                             )
                             saw_external = saw_external or fallback_external
+                        candidate_ids = _filter_relation_candidates(site, candidate_ids)
                     except LspTimeoutError as exc:
                         self._record_finding(
                             FINDING_PYRIGHT_REFERENCE_RESOLUTION_TIMEOUT,
@@ -568,7 +607,13 @@ class PyrightSession:
             },
             self._budgeted_timeout(deadline),
         )
-        return self._target_ids_from_locations(result)
+        # Relation sites (base/decorator) resolve to precise entities only:
+        # the module-id coarse fallback would mint nonsense facts like
+        # "class inherits_from module" for aliased bases.
+        return self._target_ids_from_locations(
+            result,
+            precise_only=site.kind in ("base", "decorator"),
+        )
 
     def _deadline_for_file(self, path: Path) -> float:
         return self._file_deadlines.setdefault(
@@ -591,19 +636,32 @@ class PyrightSession:
     def _file_budget_expired(self, deadline: float) -> bool:
         return deadline - time.monotonic() <= 0
 
-    def _target_ids_from_locations(self, result: object) -> tuple[list[str], bool]:
+    def _target_ids_from_locations(
+        self,
+        result: object,
+        *,
+        precise_only: bool = False,
+    ) -> tuple[list[str], bool]:
         locations = result if isinstance(result, list) else [result]
         candidate_ids: set[str] = set()
         saw_external = False
         for location in locations:
-            target_id, external = self._target_id_from_location(location)
+            target_id, external = self._target_id_from_location(
+                location,
+                precise_only=precise_only,
+            )
             if external:
                 saw_external = True
             if target_id is not None:
                 candidate_ids.add(target_id)
         return sorted(candidate_ids), saw_external
 
-    def _target_id_from_location(self, location: object) -> tuple[str | None, bool]:
+    def _target_id_from_location(
+        self,
+        location: object,
+        *,
+        precise_only: bool = False,
+    ) -> tuple[str | None, bool]:
         if not isinstance(location, dict):
             return None, False
         raw_uri = location.get("uri")
@@ -625,6 +683,8 @@ class PyrightSession:
         key = _range_start_key(raw_range)
         if key is not None and key in target_index.entity_by_name_position:
             return target_index.entity_by_name_position[key], False
+        if precise_only:
+            return None, False
         return target_index.module_id, False
 
     def _ensure_process(self) -> bool:
@@ -711,14 +771,7 @@ class PyrightSession:
                 preexec_fn=preexec_fn,  # noqa: PLW1509
             )
         except OSError as exc:
-            self._run_state.disabled = True
-            self._record_finding(
-                FINDING_PYRIGHT_INSTALL_FAILURE,
-                "pyright-langserver failed to start",
-                executable=executable,
-                error=str(exc),
-            )
-            return False
+            return self._handle_spawn_oserror(exc, executable)
 
         self._process = process
         self._start_stderr_drain(process)
@@ -745,8 +798,57 @@ class PyrightSession:
                 process.kill()
                 process.wait(timeout=2)
             return False
+        # A clean spawn + handshake clears any accumulated transient-deferral
+        # pressure: the per-UID resource squeeze that caused earlier EAGAINs has
+        # eased, so the run is healthy again.
+        self._run_state.consecutive_spawn_deferrals = 0
         return True
 
+    def _handle_spawn_oserror(self, exc: OSError, executable: str) -> bool:
+        """Triage a ``subprocess.Popen`` failure into transient vs. permanent.
+
+        ``EAGAIN``/``ENOMEM``/``EMFILE``/``ENFILE`` are *transient*
+        resource-pressure errors: a busy host momentarily out of process slots,
+        memory, or file descriptors. The spawn is deferred — ``self._process``
+        stays ``None`` and ``disabled`` is left unset, so the next file retries a
+        fresh spawn — and only a sustained run of deferrals
+        (``MAX_CONSECUTIVE_SPAWN_DEFERRALS``) gives up. Any other errno (notably
+        ``ENOENT``/``EACCES``) is a genuine, permanent install defect and
+        disables pyright for the rest of the run.
+        """
+        if exc.errno in _TRANSIENT_SPAWN_ERRNOS:
+            self._run_state.consecutive_spawn_deferrals += 1
+            if self._run_state.consecutive_spawn_deferrals > MAX_CONSECUTIVE_SPAWN_DEFERRALS:
+                self._run_state.disabled = True
+                self._record_finding(
+                    FINDING_PYRIGHT_RESOURCE_EXHAUSTED,
+                    "pyright-langserver persistently unavailable under resource "
+                    "pressure; skipping call resolution",
+                    executable=executable,
+                    consecutive_spawn_deferrals=self._run_state.consecutive_spawn_deferrals,
+                    error=str(exc),
+                )
+                return False
+            # Emit one finding per pressure *episode* (the 0 -> 1 transition),
+            # not one per deferred file, so a busy run is not buried in findings.
+            if self._run_state.consecutive_spawn_deferrals == 1:
+                self._record_finding(
+                    FINDING_PYRIGHT_SPAWN_DEFERRED,
+                    "pyright-langserver spawn deferred under resource pressure; "
+                    "will retry on subsequent files",
+                    executable=executable,
+                    error=str(exc),
+                )
+            return False
+        self._run_state.disabled = True
+        self._record_finding(
+            FINDING_PYRIGHT_INSTALL_FAILURE,
+            "pyright-langserver failed to start",
+            executable=executable,
+            error=str(exc),
+        )
+        return False
+
     def _initialize(self) -> None:
         result = self._request(
             "initialize",
@@ -1143,17 +1245,31 @@ def _has_overload_decorator(node: ast.FunctionDef | ast.AsyncFunctionDef) -> boo
 
 
 def _merge_reference_site(
-    accumulators: dict[tuple[str, str], _ReferenceEdgeAccumulator],
+    accumulators: dict[tuple[str, str, str], _ReferenceEdgeAccumulator],
     site: ReferenceSite,
     candidate_ids: Sequence[str],
 ) -> None:
+    """Fold one resolved site into the per-file edge accumulators.
+
+    The site kind selects the edge kind (``_EDGE_KIND_BY_SITE_KIND``).
+    ``decorator`` sites invert direction: the site owner is the *decorated*
+    entity, but the stored edge reads ``decorator decorates decorated``
+    (ADR-051: from_id = decorator entity, to_id = decorated entity), so the
+    resolved candidate becomes ``from_id``. Ambiguous candidates therefore
+    list alternative decorators (from-side) rather than alternative targets.
+    """
     sorted_candidates = sorted(set(candidate_ids))
-    to_id = sorted_candidates[0]
-    key = (site.from_id, to_id)
+    edge_kind = _EDGE_KIND_BY_SITE_KIND[site.kind]
+    if site.kind == "decorator":
+        from_id, to_id = sorted_candidates[0], site.from_id
+    else:
+        from_id, to_id = site.from_id, sorted_candidates[0]
+    key = (edge_kind, from_id, to_id)
     existing = accumulators.get(key)
     if existing is None:
         accumulators[key] = _ReferenceEdgeAccumulator(
-            from_id=site.from_id,
+            kind=edge_kind,
+            from_id=from_id,
             to_id=to_id,
             source_byte_start=site.source_byte_start,
             source_byte_end=site.source_byte_end,
@@ -1169,6 +1285,22 @@ def _merge_reference_site(
         existing.source_byte_end = site.source_byte_end
 
 
+def _filter_relation_candidates(site: ReferenceSite, candidate_ids: list[str]) -> list[str]:
+    """Apply the relation-site target discipline (Rust derives/implements parity).
+
+    ``inherits_from`` targets must be class entities — a base name resolving
+    to a function (factory alias, shadowing ``def``) is dropped rather than
+    stored as a class-inherits-function fact, mirroring the Rust resolver's
+    ``rust:trait:`` kind filter. Both relation kinds drop self-edges
+    (``class X(X)`` resolving the in-definition name to itself).
+    """
+    if site.kind == "base":
+        candidate_ids = [cid for cid in candidate_ids if cid.startswith("python:class:")]
+    if site.kind in ("base", "decorator"):
+        candidate_ids = [cid for cid in candidate_ids if cid != site.from_id]
+    return candidate_ids
+
+
 def _reference_lookup_cache_key(
     site: ReferenceSite,
     source_bytes: bytes,
@@ -1186,7 +1318,7 @@ def _reference_lookup_cache_key(
 
 
 def _sorted_reference_accumulators(
-    accumulators: dict[tuple[str, str], _ReferenceEdgeAccumulator],
+    accumulators: dict[tuple[str, str, str], _ReferenceEdgeAccumulator],
 ) -> list[_ReferenceEdgeAccumulator]:
     return sorted(
         accumulators.values(),
@@ -1204,7 +1336,7 @@ def _reference_accumulator_to_edge(
 ) -> ReferencesRawEdge:
     candidates = sorted(accumulator.candidates)
     edge: ReferencesRawEdge = {
-        "kind": "references",
+        "kind": accumulator.kind,
         "from_id": accumulator.from_id,
         "to_id": accumulator.to_id,
         "source_byte_start": accumulator.source_byte_start,

loomweave_plugin_python/qualname.py

@@ -19,9 +19,9 @@ the same bare Python ``__qualname__`` semantics that Wardline stores in its
 dotted module path elsewhere; ADR-018 requires cross-product joins to translate
 between those shapes instead of comparing strings directly.
 
-Sprint 1 covers ``FunctionDef`` and ``AsyncFunctionDef`` as emitted
-entities; ``ClassDef`` is recognised as a parent scope only (class
-entities are WP3-feature-complete scope).
+``FunctionDef``, ``AsyncFunctionDef``, and ``ClassDef`` are all emitted
+entities (class entities since WP3); every one of the three also acts as
+a parent scope for qualname reconstruction.
 """
 
 from __future__ import annotations

loomweave_plugin_python/reference_resolver.py

@@ -10,7 +10,12 @@ if TYPE_CHECKING:
     from loomweave_plugin_python.call_resolver import Finding
 
 
-ReferenceSiteKind = Literal["name", "annotation"]
+# ``name``/``annotation`` resolve into ``references`` edges; ``base`` and
+# ``decorator`` are relation sites resolving into ``inherits_from`` /
+# ``decorates`` edges respectively (clarion-43416be550). All four ride the
+# same pyright resolution machinery (external-skip, per-file cap, lookup
+# cache); the site kind selects the emitted edge kind.
+ReferenceSiteKind = Literal["name", "annotation", "base", "decorator"]
 
 
 @dataclass(frozen=True)
@@ -30,7 +35,16 @@ class ReferencesEdgeProperties(TypedDict):
 
 
 class ReferencesRawEdge(TypedDict):
-    kind: Literal["references"]
+    """Anchored edge produced by the reference-site resolution pass.
+
+    Despite the name (historic — B.5* shipped ``references`` alone), this is
+    the wire shape for all three site-derived edge kinds. ``candidates`` in
+    ``properties`` is present only on ambiguous edges; for ``decorates`` the
+    candidates are alternative *from*-side decorator entities (direction is
+    inverted relative to the site owner).
+    """
+
+    kind: Literal["references", "inherits_from", "decorates"]
     from_id: str
     to_id: str
     source_byte_start: int

loomweave_plugin_python/server.py

@@ -34,7 +34,7 @@ from loomweave_plugin_python.pyright_session import PyrightRunState, PyrightSess
 from loomweave_plugin_python.stdout_guard import install_stdio
 from loomweave_plugin_python.wardline_descriptor import WardlineVocabulary, load_wardline_descriptor
 
-ONTOLOGY_VERSION = "0.7.0"
+ONTOLOGY_VERSION = "0.8.0"
 
 # Plugin-side Content-Length sanity cap. Matches the host's ADR-021 §2b
 # default (8 MiB) so the plugin never emits a frame the host would kill us

loomweave_plugin_python/wardline_descriptor.py

@@ -4,7 +4,7 @@ This module deliberately reads descriptor files without importing Wardline.
 Wardline remains authoritative for the vocabulary; Loomweave records only the
 source-observed decorator facts it can derive from that descriptor.
 
-Two contract details below (``PROJECT_DESCRIPTOR_PATH`` and the descriptor
+Two contract details below (``PROJECT_DESCRIPTOR_PATHS`` and the descriptor
 ``version`` semantics) are Loomweave-side assumptions pending Wardline's
 "Pre-Rust core hardening" Task B, which has not yet published the canonical
 project-local descriptor location or the ``schema: wardline.vocabulary/v1``
@@ -28,7 +28,18 @@ import yaml
 # location and descriptor-version semantics are not yet pinned by Wardline.
 # Tracked: filigree clarion-6ab5668d82.
 EXPECTED_DESCRIPTOR_VERSION = "wardline-generic-2"
-PROJECT_DESCRIPTOR_PATH = Path(".wardline/vocabulary.yaml")
+
+# Weft store consolidation (ADR-046): sibling runtime state lives under the
+# shared ``.weft/<member>/`` dotdir, so the Wardline descriptor is read only from
+# the consolidated ``.weft/wardline/`` location. There is no fallback to the
+# pre-consolidation ``.wardline/`` path: after the coordinated cutover every
+# sibling is at ``.weft/`` by construction, so a descriptor found only on the
+# legacy path means a mis-sequenced cutover; resolving it would silently bind a
+# stale dir. Instead the project descriptor reads as absent and the loader falls
+# through to the package descriptor (a loud, visible signal). Loomweave never
+# writes a sibling's subtree — this is read-only.
+WEFT_DESCRIPTOR_PATH = Path(".weft/wardline/vocabulary.yaml")
+PROJECT_DESCRIPTOR_PATHS = (WEFT_DESCRIPTOR_PATH,)
 
 DescriptorSource = Literal["project", "package"]
 DescriptorStatus = Literal["enabled", "version_skew", "absent"]
@@ -97,13 +108,17 @@ def load_wardline_descriptor(project_root: Path | None) -> WardlineDescriptorSta
 def _read_project_descriptor(project_root: Path | None) -> str | None:
     if project_root is None:
         return None
-    path = project_root / PROJECT_DESCRIPTOR_PATH
-    if not path.is_file():
-        return None
-    try:
-        return path.read_text(encoding="utf-8")
-    except OSError:
-        return None
+    # Read only the consolidated .weft/wardline/ location (ADR-046); the
+    # pre-consolidation .wardline/ path is not consulted.
+    for relative in PROJECT_DESCRIPTOR_PATHS:
+        path = project_root / relative
+        if not path.is_file():
+            continue
+        try:
+            return path.read_text(encoding="utf-8")
+        except OSError:
+            return None
+    return None
 
 
 def _read_package_descriptor() -> str | None:

{loomweave_plugin_python-1.0.0.data → loomweave_plugin_python-1.2.0.data}/data/share/loomweave/plugins/python/plugin.toml

@@ -1,7 +1,7 @@
 [plugin]
 name = "loomweave-plugin-python"
 plugin_id = "python"
-version = "1.0.0"
+version = "1.2.0"
 protocol_version = "1.0"
 # Bare basename per ADR-021 §Layer 1 + WP2 scrub commit eb0a41d — the host
 # refuses manifests whose `executable` carries any path component.
@@ -25,6 +25,11 @@ wardline_aware = true
 # v0.1 rejects `true` at initialize with LMWV-INFRA-MANIFEST-UNSUPPORTED-CAPABILITY.
 reads_outside_project_root = false
 
+# Declaring this sub-table marks the plugin as a language-server host: it spawns
+# pyright-langserver (Node). The host detects this and leaves RLIMIT_NPROC
+# uncapped for the plugin — RLIMIT_NPROC is per-UID-global and would otherwise
+# fail pyright's fork() with EAGAIN on a busy workstation (see ADR-021,
+# "process-count control", and host::effective_max_nproc).
 [capabilities.runtime.pyright]
 pin = "1.1.409"
 
@@ -32,19 +37,23 @@ pin = "1.1.409"
 # Sprint 2 B.2: classes + modules join the kind set. B.3 (ADR-026) adds
 # the first edge kind, `contains`. B.4* adds scan-time `calls` edges.
 # B.5* adds scan-time `references` edges. Phase 3 Task 3 adds scan-time
-# `imports` candidate edges.
+# `imports` candidate edges. clarion-43416be550 adds scan-time
+# `inherits_from` (subclass → base) + `decorates` (decorator → decorated)
+# relation edges, resolved through the same pyright reference machinery.
 entity_kinds = ["function", "class", "module"]
-edge_kinds = ["contains", "calls", "references", "imports"]
+edge_kinds = ["contains", "calls", "references", "imports", "inherits_from", "decorates"]
 # Per ADR-022: uppercase `LMWV-{PLUGIN_ID_UPPER}-`. Reserved at parse
 # against the LMWV-INFRA-* and LMWV-FACT-* namespaces.
 rule_id_prefix = "LMWV-PY-"
 # Bumps per ADR-027 when the entity/edge/rule set shifts. Phase 3 Task 3 is a
-# MINOR bump (additive `imports` edge kind). NOTE: ADR-007's summary-cache key
-# is the 5-tuple (entity_id, content_hash, prompt_template_id, model_tier,
-# guidance_fingerprint) — ontology_version is handshake-validation, NOT a
-# cache-key component. New edge rows miss the cache by component-1 of
-# the 5-tuple organically (no edges live in the 5-tuple yet anyway).
-ontology_version = "0.7.0"
+# MINOR bump (additive `imports` edge kind); 0.8.0 is the additive
+# `inherits_from` + `decorates` MINOR bump (clarion-43416be550). NOTE:
+# ADR-007's summary-cache key is the 5-tuple (entity_id, content_hash,
+# prompt_template_id, model_tier, guidance_fingerprint) — ontology_version is
+# handshake-validation, NOT a cache-key component. New edge rows miss the
+# cache by component-1 of the 5-tuple organically (no edges live in the
+# 5-tuple yet anyway).
+ontology_version = "0.8.0"
 
 [integrations.wardline]
 expected_descriptor_version = "wardline-generic-2"

{loomweave_plugin_python-1.0.0.dist-info → loomweave_plugin_python-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loomweave-plugin-python
-Version: 1.0.0
+Version: 1.2.0
 Summary: Loomweave Python language plugin — v1.0 release
 Author-email: John Morrissey <qacona@gmail.com>
 Classifier: Development Status :: 4 - Beta

loomweave_plugin_python-1.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+loomweave_plugin_python/__init__.py,sha256=XS_Benpj-Em19GvyBlzkxZN4irB4JyXjbNcDwpaqmxE,95
+loomweave_plugin_python/__main__.py,sha256=oy1S1Ru7WdX6jcAVhsqNI25LxAbQq3jHBlETBt20fyM,376
+loomweave_plugin_python/call_resolver.py,sha256=V6w5AEmWgjkKuWdgUPJTXStOavmmbyvjP0PQOeT3xkU,1692
+loomweave_plugin_python/entity_id.py,sha256=l7_5yyh6WVH9xIzrQVCDb2GmBMhovOVmuQezcZIVf8k,2691
+loomweave_plugin_python/extractor.py,sha256=3S98y0CTjapmNnkU_-E5ySUXDeGyXjzQQsIZGhxB3HM,56261
+loomweave_plugin_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+loomweave_plugin_python/pyright_session.py,sha256=QWgXlOSgmN29iZ059sJE6hIbogi2mSCR3aTMFITXoyY,67579
+loomweave_plugin_python/qualname.py,sha256=gk6N2e4tMvufnPgpVZLv--c9_9gW5y9YvJIwUArffFg,2102
+loomweave_plugin_python/reference_resolver.py,sha256=hfcKX3WcDL26vEq7Ahdouq7WBs7mqCNy-rBvl8t97iI,2698
+loomweave_plugin_python/server.py,sha256=_MdaoRE1D-4VMvqLw79JyIvBmyqpU540Grk9FIBXSZg,12329
+loomweave_plugin_python/stdout_guard.py,sha256=tUzcXyvXuy3-dXB81_xCNk8KWE3mqtsWSge81KPDhKg,2007
+loomweave_plugin_python/wardline_descriptor.py,sha256=9rU-DhN1USpsHW9hS6YeWFRgGL4xgBeG41Yr1LfK-M4,8136
+loomweave_plugin_python-1.2.0.data/data/share/loomweave/plugins/python/plugin.toml,sha256=H6rj0AKyM4FaXSHiseFKLpjz86i-yOpWwEsHEE13ios,3580
+loomweave_plugin_python-1.2.0.dist-info/METADATA,sha256=ISJLdfmtVv2iRluZlTWF_M56_-_9jgztQsXRBM9XVOA,2751
+loomweave_plugin_python-1.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+loomweave_plugin_python-1.2.0.dist-info/entry_points.txt,sha256=X1DQOYU5o1z2lBOJoh9JgQR5pg9fd_Yd8KozTHdfZqA,82
+loomweave_plugin_python-1.2.0.dist-info/RECORD,,

loomweave_plugin_python-1.0.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-loomweave_plugin_python/__init__.py,sha256=wmv6wivp3tnzIGHWWG9eO2JiGwxYZW9uqvggUibOLlA,95
-loomweave_plugin_python/__main__.py,sha256=oy1S1Ru7WdX6jcAVhsqNI25LxAbQq3jHBlETBt20fyM,376
-loomweave_plugin_python/call_resolver.py,sha256=V6w5AEmWgjkKuWdgUPJTXStOavmmbyvjP0PQOeT3xkU,1692
-loomweave_plugin_python/entity_id.py,sha256=l7_5yyh6WVH9xIzrQVCDb2GmBMhovOVmuQezcZIVf8k,2691
-loomweave_plugin_python/extractor.py,sha256=niapsUWBbHlQXI17eYY6teJoQB4XxF-Nh2fcqa7dvro,48316
-loomweave_plugin_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-loomweave_plugin_python/pyright_session.py,sha256=0qXZFTzprefLYEaM7wMP6DjylR_ej9XqDbngQKIkvS4,60871
-loomweave_plugin_python/qualname.py,sha256=7JVETZnQkgU1FxPbyTmzSVZDBm_2SrXGZlqUOjB51W0,2090
-loomweave_plugin_python/reference_resolver.py,sha256=7r2QsM9tRWeYHeRD62-jBvByGkdLC-0AWYhhgKNBgV4,1871
-loomweave_plugin_python/server.py,sha256=UARexfFun59sOpFSMWP7t6baLcOoi98Thbc_Gq6JQ3Q,12329
-loomweave_plugin_python/stdout_guard.py,sha256=tUzcXyvXuy3-dXB81_xCNk8KWE3mqtsWSge81KPDhKg,2007
-loomweave_plugin_python/wardline_descriptor.py,sha256=49yYtIUdUfv4FGKyINql5yEZ2JTOUkl8sJXF3J6fPF8,7197
-loomweave_plugin_python-1.0.0.data/data/share/loomweave/plugins/python/plugin.toml,sha256=0H-_lBqflTkXsm_sqySmS6j0s7pGDQdDntkf1TcCRz0,2908
-loomweave_plugin_python-1.0.0.dist-info/METADATA,sha256=UzoJmnhdF1IOPaIuIBRvwAVxlfkg37zoss3xUBCYem0,2751
-loomweave_plugin_python-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-loomweave_plugin_python-1.0.0.dist-info/entry_points.txt,sha256=X1DQOYU5o1z2lBOJoh9JgQR5pg9fd_Yd8KozTHdfZqA,82
-loomweave_plugin_python-1.0.0.dist-info/RECORD,,