loomweave-plugin-python 1.3.1__tar.gz → 1.4.0__tar.gz

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.4.0}/.gitignore

@@ -68,3 +68,4 @@ CLAUDE.md
 # Local tool/federation config — not part of the solution
 .mcp.json
 loomweave.yaml
+.wardline

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loomweave-plugin-python
-Version: 1.3.1
+Version: 1.4.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.3.1 → loomweave_plugin_python-1.4.0}/plugin.toml

@@ -1,7 +1,7 @@
 [plugin]
 name = "loomweave-plugin-python"
 plugin_id = "python"
-version = "1.3.1"
+version = "1.4.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.
@@ -47,13 +47,15 @@ edge_kinds = ["contains", "calls", "references", "imports", "inherits_from", "de
 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); 0.8.0 is the additive
-# `inherits_from` + `decorates` MINOR bump (clarion-43416be550). NOTE:
+# `inherits_from` + `decorates` MINOR bump (clarion-43416be550); 0.9.0 is the
+# additive `public-surface` reachability-root tag (clarion-4ec50f3d92) — a
+# no-`__all__` library's public defs/classes are now tagged as roots. 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"
+ontology_version = "0.9.0"
 
 [integrations.wardline]
 expected_descriptor_version = "wardline-generic-2"

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "loomweave-plugin-python"
-version = "1.3.1"
+version = "1.4.0"
 description = "Loomweave Python language plugin — v1.0 release"
 readme = "README.md"
 requires-python = ">=3.11"

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.4.0}/src/loomweave_plugin_python/__init__.py

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

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.4.0}/src/loomweave_plugin_python/extractor.py

@@ -1058,7 +1058,10 @@ class _WalkState:
     seen_ids: set[str]
     file_path: str
     wardline_vocabulary: WardlineVocabulary | None = None
-    exported_names: set[str] = field(default_factory=set)
+    # ``None`` means no ``__all__`` was declared (triggers the public-surface
+    # heuristic); a set (possibly empty) means ``__all__`` was declared
+    # explicitly (clarion-4ec50f3d92).
+    exported_names: set[str] | None = None
     duplicate_entities_dropped: int = 0
 
 
@@ -1274,16 +1277,39 @@ def _attach_wardline_entity_metadata(
         }
 
 
-def _module_export_names(tree: ast.Module) -> set[str]:
-    exported: set[str] = set()
+def _module_export_names(tree: ast.Module) -> set[str] | None:
+    """Names declared in a module-level ``__all__``, or ``None`` when no
+    ``__all__`` is declared at all (clarion-4ec50f3d92).
+
+    The ``None`` vs empty-set distinction is load-bearing for the public-surface
+    fallback: an explicit ``__all__ = []`` declares an *empty* public surface
+    (no roots), whereas the *absence* of ``__all__`` triggers the PEP 8
+    public-surface heuristic in :func:`_function_tags` / :func:`_class_tags`.
+    Both plain (``__all__ = [...]``) and annotated (``__all__: list[str] = [...]``)
+    assignments count as a declaration so an annotated ``__all__`` is never
+    mistaken for an absent one. A non-literal value (``__all__ = a + b``, an
+    alias, a comprehension) or an annotation-only stub (``__all__: list[str]``
+    with no value) counts as a declaration but contributes no names — i.e. it is
+    treated as an explicit *empty* surface, which suppresses ``public-surface``;
+    this matches the prior behaviour for non-literal ``__all__`` (no names were
+    ever extracted from it). Bare ``__all__ += [...]`` (``ast.AugAssign`` without a
+    prior ``=`` assignment) is intentionally not handled: it is a runtime
+    ``NameError`` and so unreachable in valid Python."""
+    exported: set[str] | None = None
     for statement in tree.body:
-        if not isinstance(statement, ast.Assign):
+        if isinstance(statement, ast.Assign):
+            targets: list[ast.expr] = statement.targets
+            value: ast.expr | None = statement.value
+        elif isinstance(statement, ast.AnnAssign):
+            targets = [statement.target]
+            value = statement.value
+        else:
             continue
-        if not any(
-            isinstance(target, ast.Name) and target.id == "__all__" for target in statement.targets
-        ):
+        if not any(isinstance(target, ast.Name) and target.id == "__all__" for target in targets):
             continue
-        match statement.value:
+        if exported is None:
+            exported = set()
+        match value:
             case ast.List(elts=elts) | ast.Tuple(elts=elts) | ast.Set(elts=elts):
                 for elt in elts:
                     if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
@@ -1321,16 +1347,18 @@ def _is_module_level(parents: list[ast.AST]) -> bool:
 def _function_tags(
     node: ast.FunctionDef | ast.AsyncFunctionDef,
     parents: list[ast.AST],
-    exported_names: set[str],
+    exported_names: set[str] | None,
 ) -> set[str]:
     tags: set[str] = set()
-    if _is_module_level(parents) and node.name == "main":
-        tags.add("entry-point")
-    if _is_module_level(parents) and node.name in exported_names:
-        tags.add("exported-api")
-    if node.name.startswith("test_") or any(
+    module_level = _is_module_level(parents)
+    is_test = node.name.startswith("test_") or any(
         isinstance(parent, ast.ClassDef) and parent.name.startswith("Test") for parent in parents
-    ):
+    )
+    if module_level and node.name == "main":
+        tags.add("entry-point")
+    if module_level:
+        tags.update(_module_surface_tag(node.name, exported_names, is_test=is_test))
+    if is_test:
         tags.add("test")
     decorator_names = _decorator_names(node)
     if any(_last_name(name) in _HTTP_ROUTE_DECORATOR_NAMES for name in decorator_names):
@@ -1340,11 +1368,38 @@ def _function_tags(
     return tags
 
 
-def _class_tags(node: ast.ClassDef, parents: list[ast.AST], exported_names: set[str]) -> set[str]:
+def _module_surface_tag(name: str, exported_names: set[str] | None, *, is_test: bool) -> set[str]:
+    """Root tag for a module-level public entity (clarion-4ec50f3d92).
+
+    With a declared ``__all__`` (``exported_names is not None``) only listed
+    names are ``exported-api`` — the declaration is **authoritative**: a name the
+    author explicitly exported is an exported root regardless of its spelling
+    (so a ``Test``/``test_``-named or underscore-prefixed name listed in
+    ``__all__`` still gets ``exported-api``). With no ``__all__`` at all
+    (``None``) every non-underscore, non-test module-level def/class is the
+    module's public surface by PEP 8 convention, tagged ``public-surface``: a
+    reachability root of lower confidence than a declared export. It is a
+    fail-toward-live posture for public code invoked from outside the static call
+    graph (a library's consumers, or an app's framework-dispatched / DI / CLI
+    handlers), so a codebase that does not exhaustively declare ``__all__`` is not
+    read as mostly dead. ``is_test`` gates only this inferred fallback — test
+    entities are already roots via the ``test`` tag and are not a module's public
+    API; it never suppresses a declared export."""
+    if exported_names is None:
+        if is_test or name.startswith("_"):
+            return set()
+        return {"public-surface"}
+    return {"exported-api"} if name in exported_names else set()
+
+
+def _class_tags(
+    node: ast.ClassDef, parents: list[ast.AST], exported_names: set[str] | None
+) -> set[str]:
     tags: set[str] = set()
-    if _is_module_level(parents) and node.name in exported_names:
-        tags.add("exported-api")
-    if node.name.startswith("Test"):
+    is_test = node.name.startswith("Test")
+    if _is_module_level(parents):
+        tags.update(_module_surface_tag(node.name, exported_names, is_test=is_test))
+    if is_test:
         tags.add("test")
     decorator_names = _decorator_names(node)
     base_names = [_expr_qualified_name(base) for base in node.bases]

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.4.0}/src/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.8.0"
+ONTOLOGY_VERSION = "0.9.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-1.4.0/tests/fixtures/wardline-vocabulary-descriptor.golden.yaml

@@ -0,0 +1,14 @@
+schema: wardline.vocabulary/v1
+version: wardline-generic-2
+entries:
+- canonical_name: external_boundary
+  group: 1
+  attrs: {}
+- canonical_name: trust_boundary
+  group: 1
+  attrs:
+    _wardline_to_level: TaintState
+- canonical_name: trusted
+  group: 1
+  attrs:
+    _wardline_level: TaintState

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.4.0}/tests/test_extractor.py

@@ -1262,6 +1262,225 @@ class Config:
     assert "data-model" in config["tags"]
 
 
+def test_no_dunder_all_tags_public_module_surface_as_public_surface() -> None:
+    """clarion-4ec50f3d92: a module with no ``__all__`` falls back to the PEP 8
+    public-surface heuristic — non-underscore module-level defs/classes become
+    ``public-surface`` reachability roots (a lower-confidence root than a
+    declared ``exported-api``), while private, nested, and test entities do not."""
+
+    source = """\
+def public_fn():
+    pass
+
+
+def _private_fn():
+    pass
+
+
+def main():
+    pass
+
+
+def test_thing():
+    assert True
+
+
+class PublicClass:
+    def method(self):
+        pass
+
+
+class _PrivateClass:
+    pass
+
+
+class TestThing:
+    pass
+"""
+    entities, _ = extract(source, "lib.py")
+    by_id = {e["id"]: e for e in entities}
+
+    def tags(entity_id: str) -> list[str]:
+        return by_id[entity_id].get("tags", [])
+
+    # Public module-level def/class → public-surface, never exported-api
+    # (nothing was *declared*).
+    assert "public-surface" in tags("python:function:lib.public_fn")
+    assert "exported-api" not in tags("python:function:lib.public_fn")
+    assert "public-surface" in tags("python:class:lib.PublicClass")
+
+    # A no-__all__ module-level `main` is both an entry-point and public surface;
+    # the two roots coexist (pinned so a future reader does not assume exclusivity).
+    assert "entry-point" in tags("python:function:lib.main")
+    assert "public-surface" in tags("python:function:lib.main")
+
+    # Underscore-prefixed names are non-public by convention → no root.
+    assert "public-surface" not in tags("python:function:lib._private_fn")
+    assert "public-surface" not in tags("python:class:lib._PrivateClass")
+
+    # Nested defs are not module-level public surface.
+    assert "public-surface" not in tags("python:function:lib.PublicClass.method")
+
+    # Test entities are already roots via the ``test`` tag; they are not the
+    # library's public API and must not be double-tagged public-surface.
+    assert "test" in tags("python:function:lib.test_thing")
+    assert "public-surface" not in tags("python:function:lib.test_thing")
+    assert "test" in tags("python:class:lib.TestThing")
+    assert "public-surface" not in tags("python:class:lib.TestThing")
+
+
+def test_dunder_all_present_suppresses_public_surface_heuristic() -> None:
+    """clarion-4ec50f3d92: when ``__all__`` is declared it is authoritative —
+    only listed names are ``exported-api`` and the public-surface heuristic does
+    not fire for unlisted public names."""
+
+    source = """\
+__all__ = ["exported_fn", "ExportedClass"]
+
+
+def exported_fn():
+    pass
+
+
+def public_unlisted_fn():
+    pass
+
+
+class ExportedClass:
+    pass
+
+
+class UnlistedClass:
+    pass
+"""
+    entities, _ = extract(source, "lib.py")
+    by_id = {e["id"]: e for e in entities}
+
+    def tags(entity_id: str) -> list[str]:
+        return by_id[entity_id].get("tags", [])
+
+    assert "exported-api" in tags("python:function:lib.exported_fn")
+    assert "public-surface" not in tags("python:function:lib.exported_fn")
+    assert "exported-api" in tags("python:class:lib.ExportedClass")
+    # exported-api and public-surface are mutually exclusive for a listed name.
+    assert "public-surface" not in tags("python:function:lib.exported_fn")
+    assert "public-surface" not in tags("python:class:lib.ExportedClass")
+
+    # A declared __all__ means unlisted public names are deliberately not API.
+    assert "exported-api" not in tags("python:function:lib.public_unlisted_fn")
+    assert "public-surface" not in tags("python:function:lib.public_unlisted_fn")
+    assert "exported-api" not in tags("python:class:lib.UnlistedClass")
+    assert "public-surface" not in tags("python:class:lib.UnlistedClass")
+
+
+def test_annotated_dunder_all_is_a_declaration() -> None:
+    """clarion-4ec50f3d92 (review follow-up): an annotated ``__all__: list[str] =
+    [...]`` is a declaration like a plain assignment — listed names get
+    ``exported-api`` and the public-surface heuristic does not fire for unlisted
+    public names. Pins the ``ast.AnnAssign`` branch of ``_module_export_names``."""
+
+    source = """\
+__all__: list[str] = ["exported_fn"]
+
+
+def exported_fn():
+    pass
+
+
+def public_unlisted_fn():
+    pass
+"""
+    entities, _ = extract(source, "lib.py")
+    by_id = {e["id"]: e for e in entities}
+
+    def tags(entity_id: str) -> list[str]:
+        return by_id[entity_id].get("tags", [])
+
+    assert "exported-api" in tags("python:function:lib.exported_fn")
+    assert "public-surface" not in tags("python:function:lib.exported_fn")
+    # __all__ is declared (just annotated) → heuristic suppressed for unlisted.
+    assert "exported-api" not in tags("python:function:lib.public_unlisted_fn")
+    assert "public-surface" not in tags("python:function:lib.public_unlisted_fn")
+
+
+def test_annotated_empty_dunder_all_declares_empty_surface() -> None:
+    """clarion-4ec50f3d92 (review follow-up): annotated ``__all__: list[str] = []``
+    is an explicit empty surface, identical to the plain empty case — no
+    public-surface."""
+
+    source = """\
+__all__: list[str] = []
+
+
+def public_fn():
+    pass
+"""
+    entities, _ = extract(source, "lib.py")
+    by_id = {e["id"]: e for e in entities}
+    fn_tags = by_id["python:function:lib.public_fn"].get("tags", [])
+    assert "public-surface" not in fn_tags
+    assert "exported-api" not in fn_tags
+
+
+def test_empty_dunder_all_declares_empty_public_surface() -> None:
+    """clarion-4ec50f3d92: ``__all__ = []`` is an *explicit* empty public
+    surface — distinct from the absence of ``__all__`` — so the public-surface
+    heuristic must not fire."""
+
+    source = """\
+__all__ = []
+
+
+def public_fn():
+    pass
+"""
+    entities, _ = extract(source, "lib.py")
+    by_id = {e["id"]: e for e in entities}
+    fn_tags = by_id["python:function:lib.public_fn"].get("tags", [])
+
+    assert "public-surface" not in fn_tags
+    assert "exported-api" not in fn_tags
+
+
+def test_dunder_all_membership_is_authoritative_over_test_name() -> None:
+    """clarion-4ec50f3d92 (review follow-up): a declared ``__all__`` is
+    authoritative. A ``Test``/``test_``-named name explicitly listed in
+    ``__all__`` keeps ``exported-api`` — the test-name heuristic gates only the
+    *inferred* ``public-surface`` fallback, never a declared export (mirrors
+    ADR-053's 'the declaration is authoritative' principle)."""
+
+    source = """\
+__all__ = ["TestableThing", "test_vector_exported"]
+
+
+class TestableThing:
+    pass
+
+
+def test_vector_exported():
+    pass
+
+
+class TestUnlisted:
+    pass
+"""
+    entities, _ = extract(source, "lib.py")
+    by_id = {e["id"]: e for e in entities}
+
+    def tags(entity_id: str) -> list[str]:
+        return by_id[entity_id].get("tags", [])
+
+    # Declared in __all__ → exported-api, even though test-named.
+    assert "exported-api" in tags("python:class:lib.TestableThing")
+    assert "exported-api" in tags("python:function:lib.test_vector_exported")
+    # Still also classified as tests (both are reachability roots, no conflict).
+    assert "test" in tags("python:class:lib.TestableThing")
+    assert "test" in tags("python:function:lib.test_vector_exported")
+    # A test-named class NOT in __all__ gets neither exported-api nor public-surface.
+    assert "exported-api" not in tags("python:class:lib.TestUnlisted")
+    assert "public-surface" not in tags("python:class:lib.TestUnlisted")
+
+
 def _wardline_vocabulary(
     *,
     confidence_basis: Literal["descriptor", "descriptor_version_skew"] = "descriptor",

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.4.0}/tests/test_package.py

@@ -17,7 +17,7 @@ def _read_toml(path: Path) -> dict[str, Any]:
 
 
 def test_package_version_matches_pyproject() -> None:
-    assert loomweave_plugin_python.__version__ == "1.3.1"
+    assert loomweave_plugin_python.__version__ == "1.4.0"
 
 
 def test_plugin_version_lockstep_across_pyproject_manifest_and_module() -> None:
@@ -42,12 +42,12 @@ def test_plugin_version_lockstep_across_pyproject_manifest_and_module() -> None:
 def test_manifest_declares_current_v1_ontology_only() -> None:
     manifest = _read_toml(_PLUGIN_ROOT / "plugin.toml")
 
-    assert manifest["plugin"]["version"] == "1.3.1"
+    assert manifest["plugin"]["version"] == "1.4.0"
     assert manifest["capabilities"]["runtime"]["wardline_aware"] is True
     assert manifest["integrations"]["wardline"]["expected_descriptor_version"] == (
         EXPECTED_DESCRIPTOR_VERSION
     )
-    assert manifest["ontology"]["ontology_version"] == "0.8.0"
+    assert manifest["ontology"]["ontology_version"] == "0.9.0"
     assert manifest["ontology"]["entity_kinds"] == ["function", "class", "module"]
     assert manifest["ontology"]["edge_kinds"] == [
         "contains",

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.4.0}/tests/test_server.py

@@ -86,8 +86,8 @@ def test_initialize_roundtrip() -> None:
         assert response["id"] == 1
         result = response["result"]
         assert result["name"] == "loomweave-plugin-python"
-        assert result["version"] == "1.3.1"
-        assert result["ontology_version"] == "0.8.0"
+        assert result["version"] == "1.4.0"
+        assert result["ontology_version"] == "0.9.0"
         assert set(result["capabilities"]) == {"wardline"}
         assert result["capabilities"]["wardline"]["status"] in {
             "absent",

loomweave_plugin_python-1.4.0/tests/test_wardline_vocabulary_descriptor_conformance.py

@@ -0,0 +1,309 @@
+"""Wardline → Loomweave trust-vocabulary descriptor wire conformance oracle.
+
+The CONSUMER side of the cross-repo "Vocabulary descriptor (trust-vocab)" seam.
+Wardline AUTHORS the NG-25 trust-vocabulary descriptor — it OWNS the vocabulary
+via ``wardline.core.registry.REGISTRY`` and serialises it through
+``wardline.core.descriptor.build_vocabulary_descriptor`` / ``descriptor_to_yaml``
+to ``.weft/wardline/vocabulary.yaml`` (``{schema: wardline.vocabulary/v1,
+version, entries:[{canonical_name, group, attrs}]}``). Loomweave's Python plugin
+is the real CONSUMER: ``loomweave_plugin_python.wardline_descriptor
+.load_wardline_descriptor`` byte-reads that file (it NEVER imports wardline),
+version-gates on ``EXPECTED_DESCRIPTOR_VERSION == "wardline-generic-2"``, and
+parses ``entries`` into a ``WardlineVocabulary`` that the extractor threads into
+``wardline:external_boundary`` / ``wardline:trusted`` entity tags.
+
+This oracle pins that the bytes Wardline produces are accepted + correctly
+interpreted by Loomweave's REAL consumer code path. It mirrors the layering of
+the taint-fact storage oracle
+(``crates/loomweave-storage/tests/wardline_taint_fact_conformance_oracle.rs``):
+
+  * Layer 1 — a byte-pin (``test_vendored_golden_matches_byte_pin``): the
+    git-blob SHA-1 of the vendored golden, asserted against a const. If the
+    vendored fixture drifts by a single byte the pin reds. The SHA mirrors
+    wardline's own ``UPSTREAM_BLOB_SHA`` byte-pin idiom
+    (``wardline/tests/conformance/test_vocabulary_descriptor_wire_golden.py``)
+    so the two repos pin the SAME 40 hex chars. On its OWN this is circular
+    (it pins the vendored bytes against themselves); the non-circular breaks
+    are the consumer oracle below + the Layer-2 drift recheck.
+
+  * A NON-CIRCULAR consumer oracle: the vendored golden bytes are written to a
+    project descriptor location and fed through Loomweave's REAL
+    ``load_wardline_descriptor`` (resolve → read → ``yaml.safe_load`` → parse →
+    version-gate), asserting Loomweave ACCEPTS them (version accepted →
+    ``enabled``; entries → ``WardlineVocabulary`` with the expected
+    canonical_names / groups; the ``external_boundary`` / ``trusted`` decorator
+    attrs derive correctly). It then drives the REAL extractor
+    (``extractor.extract``) with that parsed-from-golden vocabulary to prove the
+    ``wardline:external_boundary`` / ``wardline:trusted`` TAGS derive correctly
+    end to end — not just that the lookup table parses. A version-skew copy
+    (only the ``version`` string bumped, every other byte the golden's) is fed
+    through the SAME real loader to prove the version gate is real, not
+    cosmetic: ``enabled`` flips to ``version_skew``. All assertions are driven
+    off the consumer's returned state, NOT off the golden restated against
+    itself.
+
+  * Layer 2 — a drift recheck (``test_vendored_golden_matches_wardline_authority``):
+    the vendored fixture bytes are compared against the authority golden in the
+    Wardline repo
+    (``$WARDLINE_REPO/tests/conformance/fixtures/wardline-vocabulary-descriptor.golden.yaml``,
+    ``WARDLINE_REPO`` defaulting to ``/home/john/wardline``). Skip-clean when the
+    sibling repo is absent (CI / detached checkout); fail-closed on any
+    divergence.
+
+── Scope / honesty caveat ──
+This drives the consumer parse + gate (``load_wardline_descriptor``) and the
+consumer tag-derivation (``extractor.extract`` with the parsed vocabulary) — the
+same two code paths the plugin server runs: ``server.handle_initialize`` calls
+``load_wardline_descriptor`` and stashes ``.vocabulary`` on its state, and
+``server.handle_analyze_file`` threads that vocabulary into ``extract`` as
+``wardline_vocabulary=``. It does NOT spin up the JSON-RPC server loop itself;
+the server's own tests cover that wiring. The non-circular guarantee comes from
+driving the REAL parse/gate/derive on the producer-authored bytes, never the
+golden against itself.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+
+import pytest
+
+from loomweave_plugin_python.extractor import extract
+from loomweave_plugin_python.wardline_descriptor import (
+    EXPECTED_DESCRIPTOR_VERSION,
+    WardlineVocabulary,
+    load_wardline_descriptor,
+)
+
+# The vendored copy of wardline's authority golden, BYTE-IDENTICAL to
+# wardline/tests/conformance/fixtures/wardline-vocabulary-descriptor.golden.yaml
+# (confirmed via `cmp`). Read as bytes so the byte-pin sees the exact on-disk
+# bytes wardline ships, not a yaml.safe_load round-trip.
+GOLDEN_PATH = Path(__file__).parent / "fixtures" / "wardline-vocabulary-descriptor.golden.yaml"
+
+# Layer-1 byte-pin: the git-blob SHA-1 of the vendored golden. This is the SAME
+# 40 hex chars wardline pins as UPSTREAM_BLOB_SHA on the producer side
+# (wardline/tests/conformance/test_vocabulary_descriptor_wire_golden.py) — the
+# two repos pin identical bytes, so a one-sided re-vendor reds both suites.
+# Recomputed below as sha1(b"blob %d\0" % len(data) + data). Any edit to the
+# vendored golden without a matching re-pin reds this test.
+UPSTREAM_BLOB_SHA = "f5ad8d2346ffb6ea75aa469e423c6c7cfd16d40a"
+
+# The canonical decorator names the producer authors (group 1) and the attrs the
+# consumer must surface for the trust-tier markers. Asserting on these proves the
+# consumer parses the real authored format — including the trust-tier `attrs`
+# that the existing inline-string unit tests cover but which here come straight
+# off the producer's own bytes.
+EXPECTED_CANONICAL_NAMES = ("external_boundary", "trust_boundary", "trusted")
+EXPECTED_ATTRS = {
+    "external_boundary": {},
+    "trust_boundary": {"_wardline_to_level": "TaintState"},
+    "trusted": {"_wardline_level": "TaintState"},
+}
+
+
+def _write_project_descriptor(project_root: Path, text: str) -> None:
+    """Place descriptor bytes at the real .weft/wardline/ project location the
+    consumer reads (ADR-046)."""
+    descriptor = project_root / ".weft" / "wardline" / "vocabulary.yaml"
+    descriptor.parent.mkdir(parents=True, exist_ok=True)
+    descriptor.write_text(text, encoding="utf-8")
+
+
+# ── Layer 1 — byte-pin ───────────────────────────────────────────────────────
+
+
+def test_vendored_golden_matches_byte_pin() -> None:
+    """Layer-1: the vendored wardline-authored descriptor golden byte-pins to its
+    git-blob SHA-1. ANY edit to the vendored fixture without a matching re-pin
+    reds here. On its OWN this is circular (vendored bytes pinned against
+    themselves); the non-circular protection is the consumer oracle + the Layer-2
+    drift recheck below.
+
+    Tamper proof (verified out-of-band): a one-byte-tampered copy of the fixture
+    hashes to a DIFFERENT git-blob SHA-1, so this assert reds — the pin is
+    load-bearing, not decorative.
+    """
+    assert len(UPSTREAM_BLOB_SHA) == 40, (
+        f"UPSTREAM_BLOB_SHA must be a 40-char git blob SHA-1: {UPSTREAM_BLOB_SHA!r}"
+    )
+    assert set(UPSTREAM_BLOB_SHA) <= set("0123456789abcdef"), (
+        f"UPSTREAM_BLOB_SHA must be lowercase hex (a git blob SHA-1): {UPSTREAM_BLOB_SHA!r}"
+    )
+    data = GOLDEN_PATH.read_bytes()
+    actual = hashlib.sha1(b"blob %d\x00" % len(data) + data).hexdigest()  # noqa: S324 - git blob id, not a security hash
+    assert actual == UPSTREAM_BLOB_SHA, (
+        f"the vendored vocabulary-descriptor golden changed (git blob {actual}, "
+        f"pinned {UPSTREAM_BLOB_SHA}) — if this was a deliberate re-vendor, re-copy "
+        "BYTE-IDENTICAL from wardline "
+        "(tests/conformance/fixtures/wardline-vocabulary-descriptor.golden.yaml), "
+        "confirm with `cmp`, and update UPSTREAM_BLOB_SHA in the SAME commit; if not, "
+        "revert the edit."
+    )
+
+
+# ── NON-CIRCULAR consumer oracle ─────────────────────────────────────────────
+
+
+def test_consumer_accepts_golden_and_parses_vocabulary(tmp_path: Path) -> None:
+    """The vendored golden bytes (schema line included) fed through the REAL
+    ``load_wardline_descriptor`` are ACCEPTED: version-gated to ``enabled`` and
+    parsed into a ``WardlineVocabulary`` whose canonical_names / groups / attrs
+    match the producer-authored format. Driven off the consumer's returned state,
+    never the golden against itself."""
+    golden_text = GOLDEN_PATH.read_text("utf-8")
+    _write_project_descriptor(tmp_path, golden_text)
+
+    state = load_wardline_descriptor(tmp_path)
+
+    # Version accepted — the gate passed, so the descriptor is enabled.
+    assert state.status == "enabled", (
+        f"consumer rejected the producer-authored golden: status={state.status!r} "
+        f"reason={state.reason!r}"
+    )
+    assert state.source == "project"
+    assert state.descriptor_version == EXPECTED_DESCRIPTOR_VERSION
+
+    vocab = state.vocabulary
+    assert isinstance(vocab, WardlineVocabulary)
+    assert vocab.version == EXPECTED_DESCRIPTOR_VERSION
+    assert vocab.confidence_basis == "descriptor"
+
+    # entries → WardlineVocabulary with the expected canonical_names.
+    assert tuple(sorted(vocab.entries_by_name)) == tuple(sorted(EXPECTED_CANONICAL_NAMES))
+
+    # Each entry's group + attrs survive parse exactly. The trust-tier attrs
+    # (_wardline_to_level / _wardline_level) are the real cross-tool delta the
+    # inline-string unit tests duplicate but which here come off producer bytes.
+    for name in EXPECTED_CANONICAL_NAMES:
+        entry = vocab.entries_by_name[name]
+        assert entry.canonical_name == name
+        assert entry.group == 1, f"{name} must be a group-1 marker, got {entry.group}"
+        assert entry.attrs == EXPECTED_ATTRS[name], (
+            f"{name} attrs drifted: {entry.attrs!r} != {EXPECTED_ATTRS[name]!r}"
+        )
+
+    # entry_for_decorator (the real lookup the extractor calls) resolves the
+    # last dotted segment to the right entry — the external_boundary / trusted
+    # markers derive from the parsed table, not a restated f-string.
+    eb = vocab.entry_for_decorator("weft_markers.external_boundary")
+    assert eb is not None
+    assert eb.canonical_name == "external_boundary"
+    tr = vocab.entry_for_decorator("trusted")
+    assert tr is not None
+    assert tr.canonical_name == "trusted"
+
+
+def test_consumer_derives_external_boundary_and_trusted_tags_through_extractor(
+    tmp_path: Path,
+) -> None:
+    """End-to-end consumer derivation: parse the golden through the REAL
+    ``load_wardline_descriptor``, then thread the parsed vocabulary into the REAL
+    ``extractor.extract``. This proves the ``wardline:external_boundary`` /
+    ``wardline:trusted`` TAGS derive correctly through the full consumer path —
+    not merely that the lookup table parsed."""
+    golden_text = GOLDEN_PATH.read_text("utf-8")
+    _write_project_descriptor(tmp_path, golden_text)
+
+    state = load_wardline_descriptor(tmp_path)
+    assert state.status == "enabled"
+    vocabulary = state.vocabulary
+    assert vocabulary is not None
+
+    source = """\
+from weft_markers import external_boundary, trust_boundary, trusted
+
+@external_boundary
+def read_body():
+    return ""
+
+@weft_markers.trust_boundary(to_level="ASSURED")
+@trusted(level="INTEGRAL")
+class Sanitizer:
+    pass
+"""
+
+    entities, _edges = extract(source, "service.py", wardline_vocabulary=vocabulary)
+
+    read_body = next(e for e in entities if e["id"] == "python:function:service.read_body")
+    sanitizer = next(e for e in entities if e["id"] == "python:class:service.Sanitizer")
+
+    # external_boundary tag derives from the golden-parsed vocabulary.
+    assert "wardline" in read_body["tags"]
+    assert "wardline:external_boundary" in read_body["tags"]
+    assert read_body["wardline"]["descriptor_version"] == EXPECTED_DESCRIPTOR_VERSION
+    assert read_body["wardline"]["confidence_basis"] == "descriptor"
+    eb_decorators = read_body["wardline"]["decorators"]
+    assert [d["canonical_name"] for d in eb_decorators] == ["external_boundary"]
+    assert eb_decorators[0]["attrs"] == {}
+
+    # trust_boundary + trusted tags derive, carrying the trust-tier attrs.
+    assert "wardline:trust_boundary" in sanitizer["tags"]
+    assert "wardline:trusted" in sanitizer["tags"]
+    san_attrs = {d["canonical_name"]: d["attrs"] for d in sanitizer["wardline"]["decorators"]}
+    assert san_attrs["trust_boundary"] == {"_wardline_to_level": "TaintState"}
+    assert san_attrs["trusted"] == {"_wardline_level": "TaintState"}
+
+
+def test_consumer_version_gate_rejects_skew_copy(tmp_path: Path) -> None:
+    """The version gate is REAL, not cosmetic: the SAME golden bytes with ONLY
+    the ``version`` string bumped flip the consumer from ``enabled`` to
+    ``version_skew`` through the REAL ``load_wardline_descriptor``. The contrast
+    with ``test_consumer_accepts_golden_and_parses_vocabulary`` (identical bytes
+    bar the version) is the proof that the gate fires on version alone."""
+    golden_text = GOLDEN_PATH.read_text("utf-8")
+    assert EXPECTED_DESCRIPTOR_VERSION in golden_text, (
+        "the golden must carry the expected version for the skew derivation to be a "
+        "single-field perturbation"
+    )
+    skewed = golden_text.replace(EXPECTED_DESCRIPTOR_VERSION, "wardline-generic-3")
+    assert skewed != golden_text, "version-skew copy must differ from the golden"
+    _write_project_descriptor(tmp_path, skewed)
+
+    state = load_wardline_descriptor(tmp_path)
+
+    # The gate fired: a one-field version bump is REJECTED as skew.
+    assert state.status == "version_skew", (
+        f"version gate failed to fire on a skewed descriptor: status={state.status!r}"
+    )
+    assert state.descriptor_version == "wardline-generic-3"
+    assert state.expected_version == EXPECTED_DESCRIPTOR_VERSION
+    # The vocabulary still parses (entries are valid) but is flagged degraded —
+    # proving the gate keys on version, not on a parse failure.
+    assert state.vocabulary is not None
+    assert state.vocabulary.confidence_basis == "descriptor_version_skew"
+    assert tuple(sorted(state.vocabulary.entries_by_name)) == tuple(
+        sorted(EXPECTED_CANONICAL_NAMES)
+    )
+
+
+# ── Layer 2 — drift recheck vs the Wardline source of truth ──────────────────
+
+
+def test_vendored_golden_matches_wardline_authority() -> None:
+    """Layer-2: the vendored fixture bytes must equal the authority golden in the
+    Wardline repo. Skip-clean when the sibling repo is absent (CI / detached
+    checkout) — the vendored copy + Layer-1 pin still hold; fail-closed on any
+    divergence."""
+    repo = os.environ.get("WARDLINE_REPO", "/home/john/wardline")
+    authority = (
+        Path(repo)
+        / "tests"
+        / "conformance"
+        / "fixtures"
+        / "wardline-vocabulary-descriptor.golden.yaml"
+    )
+    if not authority.exists():
+        pytest.skip(
+            f"wardline authority golden not found at {authority} — skipping Layer-2 drift "
+            "recheck (set WARDLINE_REPO to enable)"
+        )
+
+    authority_bytes = authority.read_bytes()
+    vendored_bytes = GOLDEN_PATH.read_bytes()
+    assert authority_bytes == vendored_bytes, (
+        f"the vendored golden has DRIFTED from the Wardline authority at {authority}; "
+        "re-vendor BYTE-IDENTICAL (cmp must show no difference) and re-pin UPSTREAM_BLOB_SHA"
+    )

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.4.0}/uv.lock

@@ -464,7 +464,7 @@ wheels = [
 
 [[package]]
 name = "loomweave-plugin-python"
-version = "1.3.1"
+version = "1.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "packaging" },