sum-engine 0.4.1__tar.gz → 0.5.0__tar.gz

{sum_engine-0.4.1 → sum_engine-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sum-engine
-Version: 0.4.1
+Version: 0.5.0
 Summary: SUM — bidirectional knowledge distillation with optional cryptographic attestation. Pipe prose, get a CanonicalBundle (HMAC / Ed25519 / W3C VC 2.0), verify anywhere.
 Author: ototao
 License: Apache-2.0
@@ -35,6 +35,9 @@ Provides-Extra: receipt-verify
 Requires-Dist: joserfc>=1.0.0; extra == "receipt-verify"
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: research
+Requires-Dist: numpy>=1.24.0; extra == "research"
+Requires-Dist: scipy>=1.10.0; extra == "research"
 Provides-Extra: omni-format
 Requires-Dist: markitdown==0.1.5; extra == "omni-format"
 Provides-Extra: dev
@@ -106,7 +109,7 @@ A minimal Node verifier using `jose` + `canonicalize` is in [`docs/RENDER_RECEIP
 
 | Surface | Status | Verifies |
 |---|---|---|
-| `pip install 'sum-engine[sieve]'` — `sum attest` / `sum verify` / `sum render` / `sum resolve` / `sum ledger` / `sum inspect` / `sum schema` | shipped on `main` (PyPI 0.3.0 stale; 0.4.0 cut on the operator queue) | structural reconstruction; HMAC-SHA256 + Ed25519 signatures (W3C VC 2.0 `eddsa-jcs-2022`); bidirectional `sum attest` ↔ `sum render` symmetry from the shell |
+| `pip install 'sum-engine[sieve]'` — `sum attest` / `sum verify` / `sum render` / `sum resolve` / `sum ledger` / `sum inspect` / `sum schema` | shipped on PyPI ≥ 0.4.1 | structural reconstruction; HMAC-SHA256 + Ed25519 signatures (W3C VC 2.0 `eddsa-jcs-2022`); bidirectional `sum attest` ↔ `sum render` symmetry from the shell |
 | Cloudflare Worker at `sum-demo.ototao.workers.dev` | shipped | `/api/render` → tome + `render_receipt`; `/.well-known/jwks.json` → JWKS; `/api/qid` → Wikidata resolver |
 | Single-file browser demo (`single_file_demo/index.html`) | shipped | paste prose → in-browser attest → CanonicalBundle JSON; same bytes verify under `node standalone_verifier/verify.js` (Chrome / Firefox / Safari with WebCrypto Ed25519 support) |
 | Cross-runtime trust triangle | locked by CI (`make xruntime`) | K1 / K1-mw / K2 / K3 / K4 — Python ↔ Node ↔ Browser agree byte-for-byte on valid bundles. `make xruntime-adversarial` adds A1–A6 rejection-class equivalence. |

{sum_engine-0.4.1 → sum_engine-0.5.0}/README.md

@@ -48,7 +48,7 @@ A minimal Node verifier using `jose` + `canonicalize` is in [`docs/RENDER_RECEIP
 
 | Surface | Status | Verifies |
 |---|---|---|
-| `pip install 'sum-engine[sieve]'` — `sum attest` / `sum verify` / `sum render` / `sum resolve` / `sum ledger` / `sum inspect` / `sum schema` | shipped on `main` (PyPI 0.3.0 stale; 0.4.0 cut on the operator queue) | structural reconstruction; HMAC-SHA256 + Ed25519 signatures (W3C VC 2.0 `eddsa-jcs-2022`); bidirectional `sum attest` ↔ `sum render` symmetry from the shell |
+| `pip install 'sum-engine[sieve]'` — `sum attest` / `sum verify` / `sum render` / `sum resolve` / `sum ledger` / `sum inspect` / `sum schema` | shipped on PyPI ≥ 0.4.1 | structural reconstruction; HMAC-SHA256 + Ed25519 signatures (W3C VC 2.0 `eddsa-jcs-2022`); bidirectional `sum attest` ↔ `sum render` symmetry from the shell |
 | Cloudflare Worker at `sum-demo.ototao.workers.dev` | shipped | `/api/render` → tome + `render_receipt`; `/.well-known/jwks.json` → JWKS; `/api/qid` → Wikidata resolver |
 | Single-file browser demo (`single_file_demo/index.html`) | shipped | paste prose → in-browser attest → CanonicalBundle JSON; same bytes verify under `node standalone_verifier/verify.js` (Chrome / Firefox / Safari with WebCrypto Ed25519 support) |
 | Cross-runtime trust triangle | locked by CI (`make xruntime`) | K1 / K1-mw / K2 / K3 / K4 — Python ↔ Node ↔ Browser agree byte-for-byte on valid bundles. `make xruntime-adversarial` adds A1–A6 rejection-class equivalence. |

{sum_engine-0.4.1 → sum_engine-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sum-engine"
-version = "0.4.1"
+version = "0.5.0"
 description = "SUM — bidirectional knowledge distillation with optional cryptographic attestation. Pipe prose, get a CanonicalBundle (HMAC / Ed25519 / W3C VC 2.0), verify anywhere."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -60,6 +60,16 @@ receipt-verify = ["joserfc>=1.0.0"]
 # `mcp` package is the official Python SDK; FastMCP is its
 # decorator-style high-level API. See docs/MCP_INTEGRATION.md.
 mcp = ["mcp>=1.0.0"]
+# Research-grade modules under sum_engine_internal/research/. NOT on
+# the production install path; APIs may change between minor releases
+# without backwards-compatibility guarantees. Currently provides the
+# v1 sheaf-Laplacian hallucination detector grounded in Gebhart,
+# Hansen & Schrater (2023, AISTATS, arXiv:2110.03789) and the
+# sheaf-Laplacian theory of Hansen & Ghrist (2019). See
+# docs/SHEAF_HALLUCINATION_DETECTOR.md for the spec, including
+# verified blindspots (predicate-flip, off-graph fact-fabrication,
+# empty-render false negative).
+research = ["numpy>=1.24.0", "scipy>=1.10.0"]
 # Omni-format adapter. Markdown is the canonical pivot for the
 # attest pipeline: any input format -> markdown -> existing
 # extract/state/bundle path. Source URI anchors to the original

{sum_engine-0.4.1 → sum_engine-0.5.0}/sum_engine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sum-engine
-Version: 0.4.1
+Version: 0.5.0
 Summary: SUM — bidirectional knowledge distillation with optional cryptographic attestation. Pipe prose, get a CanonicalBundle (HMAC / Ed25519 / W3C VC 2.0), verify anywhere.
 Author: ototao
 License: Apache-2.0
@@ -35,6 +35,9 @@ Provides-Extra: receipt-verify
 Requires-Dist: joserfc>=1.0.0; extra == "receipt-verify"
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: research
+Requires-Dist: numpy>=1.24.0; extra == "research"
+Requires-Dist: scipy>=1.10.0; extra == "research"
 Provides-Extra: omni-format
 Requires-Dist: markitdown==0.1.5; extra == "omni-format"
 Provides-Extra: dev
@@ -106,7 +109,7 @@ A minimal Node verifier using `jose` + `canonicalize` is in [`docs/RENDER_RECEIP
 
 | Surface | Status | Verifies |
 |---|---|---|
-| `pip install 'sum-engine[sieve]'` — `sum attest` / `sum verify` / `sum render` / `sum resolve` / `sum ledger` / `sum inspect` / `sum schema` | shipped on `main` (PyPI 0.3.0 stale; 0.4.0 cut on the operator queue) | structural reconstruction; HMAC-SHA256 + Ed25519 signatures (W3C VC 2.0 `eddsa-jcs-2022`); bidirectional `sum attest` ↔ `sum render` symmetry from the shell |
+| `pip install 'sum-engine[sieve]'` — `sum attest` / `sum verify` / `sum render` / `sum resolve` / `sum ledger` / `sum inspect` / `sum schema` | shipped on PyPI ≥ 0.4.1 | structural reconstruction; HMAC-SHA256 + Ed25519 signatures (W3C VC 2.0 `eddsa-jcs-2022`); bidirectional `sum attest` ↔ `sum render` symmetry from the shell |
 | Cloudflare Worker at `sum-demo.ototao.workers.dev` | shipped | `/api/render` → tome + `render_receipt`; `/.well-known/jwks.json` → JWKS; `/api/qid` → Wikidata resolver |
 | Single-file browser demo (`single_file_demo/index.html`) | shipped | paste prose → in-browser attest → CanonicalBundle JSON; same bytes verify under `node standalone_verifier/verify.js` (Chrome / Firefox / Safari with WebCrypto Ed25519 support) |
 | Cross-runtime trust triangle | locked by CI (`make xruntime`) | K1 / K1-mw / K2 / K3 / K4 — Python ↔ Node ↔ Browser agree byte-for-byte on valid bundles. `make xruntime-adversarial` adds A1–A6 rejection-class equivalence. |

{sum_engine-0.4.1 → sum_engine-0.5.0}/sum_engine.egg-info/SOURCES.txt

@@ -69,5 +69,7 @@ sum_engine_internal/merkle_sidecar/__init__.py
 sum_engine_internal/merkle_sidecar/tree.py
 sum_engine_internal/render_receipt/__init__.py
 sum_engine_internal/render_receipt/verifier.py
+sum_engine_internal/research/__init__.py
+sum_engine_internal/research/sheaf_laplacian.py
 sum_engine_internal/trust_root/__init__.py
 sum_engine_internal/trust_root/verifier.py

{sum_engine-0.4.1 → sum_engine-0.5.0}/sum_engine.egg-info/requires.txt

@@ -37,5 +37,9 @@ markitdown==0.1.5
 [receipt-verify]
 joserfc>=1.0.0
 
+[research]
+numpy>=1.24.0
+scipy>=1.10.0
+
 [sieve]
 spacy>=3.7.0

{sum_engine-0.4.1 → sum_engine-0.5.0}/sum_engine_internal/mcp_server/server.py

@@ -92,7 +92,7 @@ def build_server() -> FastMCP:
         name="sum",
         instructions=(
             "SUM verifiable knowledge distillation engine (v2 hardened). "
-            "Tools: extract / attest / verify / inspect / schema. "
+            "Tools: extract / attest / verify / inspect / render / schema. "
             "Default extractor is offline-only (sieve). The LLM extractor "
             "is disabled unless SUM_MCP_ALLOW_NETWORK=1 was set when the "
             "server started. Every tool returns either a tool-specific "
@@ -472,6 +472,155 @@ def build_server() -> FastMCP:
                 "inspect", t0, ErrorClass.INTERNAL, type(exc).__name__
             )
 
+    # ------------------------------------------------------------------
+    # render
+    # ------------------------------------------------------------------
+
+    @mcp.tool()
+    async def render(
+        bundle: dict,
+        density: float = 1.0,
+        length: float = 0.5,
+        formality: float = 0.5,
+        audience: float = 0.5,
+        perspective: float = 0.5,
+        title: str = "Rendered Tome",
+    ) -> dict:
+        """Render a CanonicalBundle's axioms back into prose under
+        explicit slider control. The MCP analogue of ``sum render``.
+
+        Local-only path: actions the density slider deterministically
+        (lex-prefix subsetting); non-neutral length / formality /
+        audience / perspective return ``error_class="schema"`` because
+        the LLM-conditioned axes require a Worker, which the MCP
+        server does not currently broker (see
+        ``docs/MCP_INTEGRATION.md`` for the rationale — keeping the
+        MCP server fully offline by default preserves the
+        ``SUM_MCP_ALLOW_NETWORK`` opt-in property).
+
+        Args:
+            bundle: CanonicalBundle dict (same shape ``verify`` accepts).
+            density: Axiom-coverage slider in [0, 1]. 1.0 keeps all
+                axioms (default); 0.0 keeps none.
+            length / formality / audience / perspective: 0.5 = neutral
+                (default). Non-0.5 rejected with a SCHEMA error
+                pointing at the local-only constraint.
+            title: Tome title. Default: "Rendered Tome".
+
+        Returns:
+            Success: ``{tome, sliders, mode, axiom_count_input, title}``.
+            Failure: ``{error_class, errors}``.
+        """
+        t0 = time.perf_counter()
+        try:
+            if not isinstance(bundle, dict):
+                return error_result(
+                    "render", t0, ErrorClass.SCHEMA,
+                    f"bundle must be a dict, got {type(bundle).__name__}",
+                )
+
+            for field in ("canonical_tome", "canonical_format_version"):
+                if field not in bundle:
+                    return error_result(
+                        "render", t0, ErrorClass.SCHEMA,
+                        f"bundle missing required field: {field}",
+                    )
+
+            ver = str(bundle["canonical_format_version"])
+            if not ver.startswith("1."):
+                return error_result(
+                    "render", t0, ErrorClass.SCHEMA,
+                    f"unsupported canonical_format_version {ver!r} "
+                    f"(this server speaks {_SUPPORTED_CANONICAL_FORMAT})",
+                )
+
+            tome_str = bundle["canonical_tome"]
+            if not isinstance(tome_str, str) or len(tome_str) > MAX_TOME_CHARS:
+                return error_result(
+                    "render", t0, ErrorClass.INPUT_TOO_LARGE,
+                    f"canonical_tome exceeds {MAX_TOME_CHARS} chars",
+                )
+
+            from sum_engine_internal.ensemble.tome_sliders import TomeSliders
+
+            try:
+                sliders = TomeSliders(
+                    density=density, length=length,
+                    formality=formality, audience=audience,
+                    perspective=perspective,
+                )
+            except (ValueError, TypeError) as e:
+                return error_result(
+                    "render", t0, ErrorClass.SCHEMA,
+                    f"invalid slider value: {e}",
+                )
+
+            if sliders.requires_extrapolator():
+                non_neutral = [
+                    f"{name}={getattr(sliders, name)}"
+                    for name in ("length", "formality", "audience", "perspective")
+                    if abs(getattr(sliders, name) - 0.5) > 1e-9
+                ]
+                return error_result(
+                    "render", t0, ErrorClass.SCHEMA,
+                    "non-neutral LLM-conditioned axes ("
+                    + ", ".join(non_neutral)
+                    + ") require an LLM extrapolator. The MCP server's "
+                    "render tool is local-only (deterministic density "
+                    "slider) — drop the affected sliders to 0.5, or "
+                    "use the Worker's POST /api/render endpoint for "
+                    "LLM-conditioned rendering.",
+                )
+
+            triples: list[tuple[str, str, str]] = []
+            for line in tome_str.splitlines():
+                m = _TOME_LINE_PATTERN.match(line.strip())
+                if m:
+                    if len(triples) >= MAX_AXIOM_COUNT:
+                        return error_result(
+                            "render", t0, ErrorClass.INPUT_TOO_LARGE,
+                            f"axiom count exceeds {MAX_AXIOM_COUNT}",
+                        )
+                    triples.append((m.group(1), m.group(2), m.group(3)))
+
+            if not triples:
+                return error_result(
+                    "render", t0, ErrorClass.STRUCTURAL,
+                    "bundle's canonical_tome contains zero parseable "
+                    "axiom lines — nothing to render.",
+                )
+
+            from sum_engine_internal.algorithms.semantic_arithmetic import GodelStateAlgebra
+            from sum_engine_internal.ensemble.tome_generator import AutoregressiveTomeGenerator
+
+            algebra = GodelStateAlgebra()
+            state = 1
+            for s, p, o in triples:
+                state = math.lcm(state, algebra.get_or_mint_prime(s, p, o))
+
+            tome_gen = AutoregressiveTomeGenerator(algebra)
+            tome_text = tome_gen.generate_controlled(state, sliders=sliders, title=title)
+
+            return success_result(
+                "render",
+                t0,
+                tome=tome_text,
+                sliders={
+                    "density": sliders.density,
+                    "length": sliders.length,
+                    "formality": sliders.formality,
+                    "audience": sliders.audience,
+                    "perspective": sliders.perspective,
+                },
+                mode="local-deterministic",
+                axiom_count_input=len(triples),
+                title=title,
+            )
+        except Exception as exc:
+            return error_result(
+                "render", t0, ErrorClass.INTERNAL, type(exc).__name__
+            )
+
     # ------------------------------------------------------------------
     # schema
     # ------------------------------------------------------------------

sum_engine-0.5.0/sum_engine_internal/research/__init__.py

@@ -0,0 +1,21 @@
+"""sum_engine_internal.research — research-grade modules.
+
+Modules in this package are NOT part of the production install path.
+They live behind the ``[research]`` extras flag in pyproject.toml so
+that ``pip install sum-engine`` does not pull research dependencies
+(numpy, scipy) by default. Use ``pip install 'sum-engine[research]'``.
+
+Modules:
+
+    sheaf_laplacian
+        v1 sheaf-Laplacian hallucination detector. Implements the
+        primitives specified in docs/SHEAF_HALLUCINATION_DETECTOR.md
+        §3.2 (1-dim presence stalks). Math is grounded in Gebhart,
+        Hansen & Schrater (2023, AISTATS, arXiv:2110.03789) Eq. 1
+        and the sheaf-Laplacian theory of Hansen & Ghrist (2019).
+
+Stability: research-grade. APIs may change between minor releases
+without backwards-compatibility guarantees. Production-stable
+counterparts will live elsewhere if/when the research artifacts
+benchmark sufficiently.
+"""

sum_engine-0.5.0/sum_engine_internal/research/sheaf_laplacian.py

@@ -0,0 +1,231 @@
+"""v1 sheaf-Laplacian hallucination detector.
+
+Faithful to docs/SHEAF_HALLUCINATION_DETECTOR.md §3.2 (v1, 1-dim
+presence stalks). Math grounded in Gebhart, Hansen & Schrater
+(2023, AISTATS, arXiv:2110.03789) Equation 1 and the sheaf-Laplacian
+theory of Hansen & Ghrist (2019).
+
+Every function below references the spec equation it implements.
+The v1 detector lives behind the ``[research]`` extras flag in
+``pyproject.toml`` — it is not on the production install path.
+
+v1 known blindspots (verified empirically by the synthetic
+micro-benchmark in scripts/research/sheaf_microbench.py and pinned
+by Tests/research/test_sheaf_laplacian.py):
+
+  - Predicate-flip perturbations (A2): invisible. Presence stalks
+    do not carry predicate information. v2 (learned-embedding stalks)
+    is required for predicate-sensitive detection.
+  - Off-graph fact-fabrication (A3): invisible. Entities not in the
+    source vertex set are silently ignored by ``cochain_from_extracted``.
+    v2 is required to flag fabricated entities.
+  - Empty-render false negative: a render that extracts zero triples
+    yields x = 0, hence x^T L x = 0 — the same score as a perfectly
+    consistent render. Callers should treat n_extracted == 0 as a
+    separate signal, not rely on the Laplacian alone.
+
+v1 verified-positive detection classes (6/6 detect rate, 100%
+top-1 localization accuracy on the synthetic micro-benchmark):
+
+  - Entity-swap (A1): one source entity replaced.
+  - Triple-drop (A4): one triple omitted; isolated endpoints vanish.
+  - Consistent-entity-swap (A5): the SAME swap applied across the
+    full render manifold. Caught by the *mean* Laplacian even though
+    per-render variance is zero. (The spec originally
+    mischaracterized this as a v1 blindspot; corrected in §6 to
+    distinguish A5-via-swap (caught) from A5-via-predicate-flip
+    (missed).)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import numpy as np
+
+
+Triple = tuple[str, str, str]
+
+
+@dataclass(frozen=True)
+class KnowledgeSheaf:
+    """A cellular sheaf on a knowledge graph (Gebhart et al. 2023, Def. 4).
+
+    For v1 (1-dim presence stalks):
+      F(v) = R for every vertex v
+      F(e) = R for every edge e
+      F_h⊵_h r = F_t⊵_t r = 1  (identity on R)
+
+    The vertex order is fixed at construction so cochains are
+    indexable as plain numpy arrays.
+
+    Note on ``stalk_dim``: v1 only supports ``stalk_dim=1``.
+    Construction with any other value is rejected at
+    ``__post_init__`` time so callers cannot build a sheaf they
+    can't use. v2 (text-embedding stalks) will lift this constraint;
+    until then, attempting to use higher-dimensional stalks should
+    fail loudly at the boundary — not silently surface as a
+    NotImplementedError mid-pipeline.
+    """
+    vertices: tuple[str, ...]
+    edges: tuple[Triple, ...]            # (subject, predicate, object)
+    vertex_index: dict[str, int]         # name → index into cochain vector
+    stalk_dim: int                       # = 1 for v1
+
+    def __post_init__(self) -> None:
+        if self.stalk_dim != 1:
+            raise ValueError(
+                f"v1 KnowledgeSheaf supports stalk_dim=1 only "
+                f"(got stalk_dim={self.stalk_dim}). v2 with text-"
+                f"embedding stalks (1536-dim) is the planned "
+                f"successor; see docs/SHEAF_HALLUCINATION_DETECTOR.md "
+                f"§5.3 for the v1 → v2 plan."
+            )
+
+    @classmethod
+    def from_triples(cls, triples: list[Triple], stalk_dim: int = 1) -> "KnowledgeSheaf":
+        seen: dict[str, None] = {}
+        for s, _, o in triples:
+            seen.setdefault(s, None)
+            seen.setdefault(o, None)
+        vertices = tuple(seen)
+        return cls(
+            vertices=vertices,
+            edges=tuple(triples),
+            vertex_index={v: i for i, v in enumerate(vertices)},
+            stalk_dim=stalk_dim,
+        )
+
+
+def coboundary_matrix(sheaf: KnowledgeSheaf) -> np.ndarray:
+    """δ : C^0 → C^1 as a matrix.
+
+    Spec §2.1 / Gebhart Def. 4: for an edge e: u → v with identity
+    restriction maps, (δx)_e = x_v - x_u. Each row of δ has
+    exactly two non-zeros: -1 at u's column, +1 at v's column.
+
+    Shape: (|E|, |V|) for stalk_dim=1; (|E|*d, |V|*d) when d>1
+    using a Kronecker product. v1 uses d=1, enforced at sheaf
+    construction time (see ``KnowledgeSheaf.__post_init__``).
+    """
+    # Defensive — should be unreachable since KnowledgeSheaf rejects
+    # non-1 stalk_dim at construction. Kept as an invariant so a
+    # future v2 KnowledgeSheaf subclass that lifts the restriction
+    # but forgets to override this function fails loudly here.
+    assert sheaf.stalk_dim == 1, (
+        f"coboundary_matrix v1 requires stalk_dim=1, got {sheaf.stalk_dim}"
+    )
+    n_v = len(sheaf.vertices)
+    n_e = len(sheaf.edges)
+    delta = np.zeros((n_e, n_v), dtype=np.float64)
+    for i, (s, _, o) in enumerate(sheaf.edges):
+        delta[i, sheaf.vertex_index[s]] = -1.0   # F_u⊵e applied to head
+        delta[i, sheaf.vertex_index[o]] = +1.0   # F_v⊵e applied to tail
+    return delta
+
+
+def sheaf_laplacian(sheaf: KnowledgeSheaf) -> np.ndarray:
+    """L_F = δ^T δ (Gebhart Eq. 1; Hansen-Ghrist 2019)."""
+    delta = coboundary_matrix(sheaf)
+    return delta.T @ delta
+
+
+def laplacian_quadratic_form(sheaf: KnowledgeSheaf, x: np.ndarray) -> float:
+    """x^T L_F x. Zero iff x is a global section.
+
+    For v1 1-dim stalks, x ∈ R^|V|; this measures sum over edges of
+    (x_v - x_u)^2.
+    """
+    L = sheaf_laplacian(sheaf)
+    return float(x @ L @ x)
+
+
+def per_edge_discrepancy(sheaf: KnowledgeSheaf, x: np.ndarray) -> list[tuple[Triple, float]]:
+    """Per-edge contribution to the Laplacian quadratic form.
+
+    Used for the localization claim (P2 in the spec). Returns
+    [(edge, |F_v⊵e x_v - F_u⊵e x_u|^2), ...] sorted descending.
+    """
+    delta = coboundary_matrix(sheaf)
+    edge_residual = delta @ x          # shape (|E|,)
+    contribs = [
+        (sheaf.edges[i], float(edge_residual[i] ** 2))
+        for i in range(len(sheaf.edges))
+    ]
+    contribs.sort(key=lambda kv: kv[1], reverse=True)
+    return contribs
+
+
+def cochain_from_extracted(
+    sheaf: KnowledgeSheaf,
+    extracted_triples: list[Triple],
+) -> np.ndarray:
+    """Build the 0-cochain x ∈ C^0(G; F_1d) from a render's
+    re-extracted triples (spec §3.2 step 3b).
+
+    x_v = 1 if v appears as subject or object in extracted_triples,
+    else 0. This is the 1-dim presence indicator.
+    """
+    mentioned: set[str] = set()
+    for s, _, o in extracted_triples:
+        mentioned.add(s)
+        mentioned.add(o)
+    x = np.zeros(len(sheaf.vertices), dtype=np.float64)
+    for v in mentioned:
+        if v in sheaf.vertex_index:
+            x[sheaf.vertex_index[v]] = 1.0
+    return x
+
+
+def consistency_profile(
+    source_triples: list[Triple],
+    rendered_extractions: list[list[Triple]],
+) -> dict:
+    """Mean & std of the Laplacian quadratic form across a render
+    manifold. Spec §3.2 step 5.
+
+    rendered_extractions: a list, one entry per rendering, each a
+    list of (s, p, o) triples extracted from that rendering.
+
+    Returns the consistency profile envelope shape from spec §3.5
+    (without the receipt-binding parts, which are v3). When the
+    render manifold is empty, returns a profile with explicit
+    null fields rather than a misleading zero score.
+    """
+    sheaf = KnowledgeSheaf.from_triples(source_triples, stalk_dim=1)
+
+    # Empty manifold has no signal to report; return explicit nulls
+    # so callers can branch on render_count == 0 without having to
+    # interpret a fabricated all-zero profile.
+    if not rendered_extractions:
+        return {
+            "render_count": 0,
+            "stalk_dim": sheaf.stalk_dim,
+            "version": "v1-presence-stalks",
+            "mean_laplacian": None,
+            "std_laplacian": None,
+            "max_per_render": None,
+            "argmax_render_idx": None,
+            "per_render_v": [],
+            "per_edge_top3_argmax_render": [],
+        }
+
+    per_render_v: list[float] = []
+    per_render_localization: list[list[tuple[Triple, float]]] = []
+    for triples_n in rendered_extractions:
+        x_n = cochain_from_extracted(sheaf, triples_n)
+        v_n = laplacian_quadratic_form(sheaf, x_n)
+        per_render_v.append(v_n)
+        per_render_localization.append(per_edge_discrepancy(sheaf, x_n))
+
+    arr = np.array(per_render_v)
+    argmax_idx = int(arr.argmax())
+    return {
+        "render_count": len(rendered_extractions),
+        "stalk_dim": sheaf.stalk_dim,
+        "version": "v1-presence-stalks",
+        "mean_laplacian": float(arr.mean()),
+        "std_laplacian": float(arr.std()),
+        "max_per_render": float(arr.max()),
+        "argmax_render_idx": argmax_idx,
+        "per_render_v": per_render_v,
+        "per_edge_top3_argmax_render": per_render_localization[argmax_idx][:3],
+    }