sourcecode 4.7.0__tar.gz → 4.9.0__tar.gz

{sourcecode-4.7.0 → sourcecode-4.9.0}/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 ## [Unreleased]
 
+## [4.9.0] — 2026-08-04
+
+### Added
+
+- **Custom AOP security gate audit.** `spring-audit` now emits `GATE-001` through
+  `GATE-004` for custom authorization gates detected by the security posture
+  authority: Spring AOP proxy bypass, fail-open advice, disabled/tautological
+  annotation attributes, and fragile positional/reflection binding.
+- **Deployment evidence for runtime posture.** `posture --resolve-environments`
+  accepts `--env-file FILE` and binds explicit deployment profile evidence to
+  `decided_case` while keeping repository defaults as lower-priority evidence.
+- **Bounded HTTP-input-to-sink flow in `risk`.** The `query_construction` factor
+  now distinguishes a proven bounded path from annotated HTTP input, through
+  positional calls in repository Java sources, into known concatenated query
+  sinks. General taint remains explicitly outside scope.
+- **SARIF triage table for `enrich`.** `enrich --table` now provides
+  auditor-facing filtering by scanner rule, composed band and top-N while
+  leaving JSON as the contract.
+- **Signed audit report bundle.** New experimental `audit-report` command packages
+  existing `risk` and `posture` evidence into JSON or Markdown, with optional
+  HMAC-SHA256 signing over the canonical JSON payload via `--sign-key`.
+
+### Documentation
+
+- README, user guide and root `ask --help` now list `audit-report`, the 4.9.0
+  version, `posture --env-file`, `enrich --table`, bounded `risk` flow and the
+  `GATE-*` rule family.
+
+## [4.8.0] — 2026-08-04
+
+### Fixed
+
+- **`risk` now gives MyBatis XML findings real reach.** `SEC-008` mapper XML
+  binds to the Java mapper interface named by the XML namespace, then walks that
+  interface's callers instead of publishing manufactured zero reach.
+- **`risk` now maps deployment descriptor controls to endpoint reach.**
+  `DEAD-001` in `web.xml` reads descriptor URL patterns and reports the
+  endpoint population they cover, or an explicit unknown reach reason when the
+  descriptor scope cannot be parsed.
+- **`migrate-check` no longer scores unresolved transitive Hibernate as ready.**
+  `spring-boot-starter-data-jpa` without a resolved Hibernate version now
+  degrades to unresolved transitive evidence instead of `hibernate_readiness:
+  100`.
+- **`impact-chain` names caller-count units.** List entries, distinct symbols and
+  distinct classes are published separately so truncation warnings and metadata
+  no longer reuse one ambiguous "direct callers" phrase.
+- **Expensive semantic passes warn about repository contention.** `spring-audit`,
+  `risk`, `migrate-check` and `verify` register an advisory analysis scope and
+  warn interactive users when another expensive `ask` process is already running
+  against the same repository.
+- **Cache context stats publish lookup distributions.** `cache context-stats`
+  now includes lookup/build p50/p95 and context-layer payload sizes so cache-hit
+  cost can be budgeted instead of inferred.
+- **Cache command grammar is consistent.** `ask cache model [path]` accepts a
+  repository path like sibling cache commands.
+
+### Added
+
+- **Human-scale table triage for large audits.** `spring-audit`, `risk` and
+  `migrate-check` now support table renderers with direct filtering:
+  `--table`, `--rule`/`--only`, `--band` where applicable, and `--top-n`.
+
+### Documentation
+
+- README and user guide examples now report `4.8.0`.
+- The development roadmap records the saint-server field-evaluation fixes and
+  future feature queue.
+
 ## [4.7.0] — 2026-08-04
 
 ### Fixed

{sourcecode-4.7.0 → sourcecode-4.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.7.0
+Version: 4.9.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.7.0-blue)
+![Version](https://img.shields.io/badge/version-4.9.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -97,7 +97,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.7.0 — and, on a build that has aged,
+ask version                    # ask 4.9.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -260,10 +260,10 @@ figures and the authority behind each — and an axis this build cannot measure
 weighted 1.0 and named in `blind_axes` rather than silently treated as safe. Measured on a
 field case: a defect both `spring-audit` and `impact-chain` called *medium* composes to
 **high (8.06)** once *reachable unauthenticated* and *writes to the database* are in it.
-The last two factors describe the input path — a query assembled by concatenation, a route
-accepting a body with no declared constraint. They are **adjacencies, not dataflow**: no
-value is followed from a request to a sink, which is `NC-001` and is published in the
-payload's own `non_coverage` block.
+The last two factors describe the input path: a query assembled by concatenation, a bounded
+HTTP-input-to-query-sink path when ASK can prove one, and a route accepting a body with no
+declared constraint. General taint remains `NC-001` and is published in the payload's own
+`non_coverage` block.
 `ask risk .` · `ask risk . --min-band high` · `ask risk . --limit 10`
 → [reference](docs/USER_GUIDE.md)
 
@@ -289,7 +289,7 @@ experimental: both are true, and they are two different facts.
 |---|---|---|
 | **core** | contract stable within a major — safe to gate CI on | `endpoints` · `spring-audit` · `migrate-check` · `impact` · `impact-chain` · `pr-impact` · `verify` |
 | **supported** | maintained; fields are added, never removed without a major | every command not named in another row |
-| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `data-exposure` · `migrate-recipe` · `posture` · `archetype` |
+| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `audit-report` · `data-exposure` · `migrate-recipe` · `posture` · `archetype` |
 | **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
@@ -306,13 +306,14 @@ from it.
 | Command | Tier | Answers | Note |
 |---|---|---|---|
 | `posture` | experimental | which beans a profile set wires, and how effective endpoint access differs between two sets | the most differentiated capability here |
-| `risk` | experimental | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority |
-| `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; the same composition as `risk`, with the scanner as the severity authority |
+| `risk` | experimental | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
+| `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; same composition as `risk`, with `--table --rule <id> --band high --top-n 20` for triage |
+| `audit-report` | experimental | human audit bundle over existing `risk` + `posture` evidence, optionally signed | `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
 | `migrate-recipe` | experimental | the migration report as the OpenRewrite recipe that applies it | only recipes a finding named; the manual remainder published beside them; writes nothing without `--write`, and never a runnable command for an empty recipe list |
 | `data-exposure` | experimental | which routes can carry the data you labelled, and who reaches them | labels declared in `sourcecode.config.json` — never inferred from a name; `signature` and `call_reach` evidence published apart, field-level flow out of scope (NC-008). With nothing declared, `ask data-exposure /path/to/repo` answers `answered: false` and hands back the file, the key and an example to declare — it never reports zero exposed routes |
 | `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators). `--compact` answers the exposure census without the rows; `--servlets` lists the servlet-mounted surface as its own population; `--client-usage` says which routes the TS/JS client in this repository actually calls |
-| `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment` |
-| `migrate-check` | core | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan |
+| `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
+| `migrate-check` | core | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
 | `impact` / `impact-chain` | core | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
 | `pr-impact` | core | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
 | `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
@@ -328,7 +329,7 @@ from it.
 | `retrieve` | parked | typed knowledge queries over the model | |
 | `archetype` | experimental | evidence-based architectural archetype | |
 | `rename-class` / `chunk-file` | supported | word-boundary Java rename; split a large file for an agent | |
-| `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `activate` too |
+| `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `cache model [path]` explains what a warm buys per command; `activate` too |
 
 ---
 
@@ -356,7 +357,7 @@ reading JSON sees the same boundary a buyer reads here.
 
 | Not covered | Why | What answers it |
 |---|---|---|
-| **Whether request input reaches a sink — no dataflow or taint analysis.** | This engine resolves structure and wiring without compiling. Taint needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL). What this product adds on top is reachability: which of that tool's findings sit behind an endpoint that is reachable unauthenticated. |
+| **General request-input-to-sink taint analysis.** | `ask risk` includes a bounded slice for annotated HTTP parameters, positional calls in repository Java sources and known query sinks. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the bounded slice, whether an annotated HTTP input reaches a known concatenated query sink. |
 | **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
 | **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |

{sourcecode-4.7.0 → sourcecode-4.9.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.7.0-blue)
+![Version](https://img.shields.io/badge/version-4.9.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -59,7 +59,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.7.0 — and, on a build that has aged,
+ask version                    # ask 4.9.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -222,10 +222,10 @@ figures and the authority behind each — and an axis this build cannot measure
 weighted 1.0 and named in `blind_axes` rather than silently treated as safe. Measured on a
 field case: a defect both `spring-audit` and `impact-chain` called *medium* composes to
 **high (8.06)** once *reachable unauthenticated* and *writes to the database* are in it.
-The last two factors describe the input path — a query assembled by concatenation, a route
-accepting a body with no declared constraint. They are **adjacencies, not dataflow**: no
-value is followed from a request to a sink, which is `NC-001` and is published in the
-payload's own `non_coverage` block.
+The last two factors describe the input path: a query assembled by concatenation, a bounded
+HTTP-input-to-query-sink path when ASK can prove one, and a route accepting a body with no
+declared constraint. General taint remains `NC-001` and is published in the payload's own
+`non_coverage` block.
 `ask risk .` · `ask risk . --min-band high` · `ask risk . --limit 10`
 → [reference](docs/USER_GUIDE.md)
 
@@ -251,7 +251,7 @@ experimental: both are true, and they are two different facts.
 |---|---|---|
 | **core** | contract stable within a major — safe to gate CI on | `endpoints` · `spring-audit` · `migrate-check` · `impact` · `impact-chain` · `pr-impact` · `verify` |
 | **supported** | maintained; fields are added, never removed without a major | every command not named in another row |
-| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `data-exposure` · `migrate-recipe` · `posture` · `archetype` |
+| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `audit-report` · `data-exposure` · `migrate-recipe` · `posture` · `archetype` |
 | **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
@@ -268,13 +268,14 @@ from it.
 | Command | Tier | Answers | Note |
 |---|---|---|---|
 | `posture` | experimental | which beans a profile set wires, and how effective endpoint access differs between two sets | the most differentiated capability here |
-| `risk` | experimental | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority |
-| `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; the same composition as `risk`, with the scanner as the severity authority |
+| `risk` | experimental | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
+| `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; same composition as `risk`, with `--table --rule <id> --band high --top-n 20` for triage |
+| `audit-report` | experimental | human audit bundle over existing `risk` + `posture` evidence, optionally signed | `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
 | `migrate-recipe` | experimental | the migration report as the OpenRewrite recipe that applies it | only recipes a finding named; the manual remainder published beside them; writes nothing without `--write`, and never a runnable command for an empty recipe list |
 | `data-exposure` | experimental | which routes can carry the data you labelled, and who reaches them | labels declared in `sourcecode.config.json` — never inferred from a name; `signature` and `call_reach` evidence published apart, field-level flow out of scope (NC-008). With nothing declared, `ask data-exposure /path/to/repo` answers `answered: false` and hands back the file, the key and an example to declare — it never reports zero exposed routes |
 | `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators). `--compact` answers the exposure census without the rows; `--servlets` lists the servlet-mounted surface as its own population; `--client-usage` says which routes the TS/JS client in this repository actually calls |
-| `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment` |
-| `migrate-check` | core | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan |
+| `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
+| `migrate-check` | core | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
 | `impact` / `impact-chain` | core | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
 | `pr-impact` | core | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
 | `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
@@ -290,7 +291,7 @@ from it.
 | `retrieve` | parked | typed knowledge queries over the model | |
 | `archetype` | experimental | evidence-based architectural archetype | |
 | `rename-class` / `chunk-file` | supported | word-boundary Java rename; split a large file for an agent | |
-| `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `activate` too |
+| `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `cache model [path]` explains what a warm buys per command; `activate` too |
 
 ---
 
@@ -318,7 +319,7 @@ reading JSON sees the same boundary a buyer reads here.
 
 | Not covered | Why | What answers it |
 |---|---|---|
-| **Whether request input reaches a sink — no dataflow or taint analysis.** | This engine resolves structure and wiring without compiling. Taint needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL). What this product adds on top is reachability: which of that tool's findings sit behind an endpoint that is reachable unauthenticated. |
+| **General request-input-to-sink taint analysis.** | `ask risk` includes a bounded slice for annotated HTTP parameters, positional calls in repository Java sources and known query sinks. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the bounded slice, whether an annotated HTTP input reaches a known concatenated query sink. |
 | **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
 | **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |

{sourcecode-4.7.0 → sourcecode-4.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "4.7.0"
+version = "4.9.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-4.7.0 → sourcecode-4.9.0}/src/sourcecode/__init__.py

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

sourcecode-4.9.0/src/sourcecode/audit_report.py

@@ -0,0 +1,147 @@
+"""Signed audit report over existing ASK evidence.
+
+This module packages facts other commands already publish. It does not score ROI,
+choose a fix, or introduce a second judgement layer: the report summary is a
+reader-friendly index over the embedded evidence blocks.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from sourcecode import __version__
+
+AUDIT_REPORT_SCHEMA = "audit-report-v1"
+
+
+def _canonical_json(data: dict[str, Any]) -> bytes:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def _sign(payload: dict[str, Any], key: bytes) -> dict[str, str]:
+    canonical = _canonical_json(payload)
+    return {
+        "algorithm": "hmac-sha256",
+        "payload_sha256": hashlib.sha256(canonical).hexdigest(),
+        "key_id": hashlib.sha256(key).hexdigest()[:12],
+        "signature": hmac.new(key, canonical, hashlib.sha256).hexdigest(),
+    }
+
+
+def build_audit_report(
+    root: Path,
+    *,
+    profiles: Optional[set[str]] = None,
+    sign_key: Optional[bytes] = None,
+    risk_limit: int = 10,
+) -> dict[str, Any]:
+    """Build the buyer-readable audit bundle from existing command payloads."""
+    from sourcecode.posture import build_posture
+    from sourcecode.risk import build_risk
+
+    root = Path(root).resolve()
+    risk = build_risk(root, limit=risk_limit, min_band="low", profiles=profiles)
+    posture = build_posture(root, profiles or set())
+    top_risks = risk.get("risks", [])[:risk_limit]
+    access = ((posture.get("endpoints") or {}).get("effective_access") or {})
+
+    unsigned: dict[str, Any] = {
+        "schema_version": AUDIT_REPORT_SCHEMA,
+        "tool": {"name": "ask", "version": __version__},
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "repository": {"path": str(root)},
+        **({"profile_set": sorted(profiles)} if profiles else {}),
+        "summary": {
+            "risk_model": risk.get("model"),
+            "total_defects": risk.get("total_defects"),
+            "total_findings": risk.get("total_findings"),
+            "risk_bands": risk.get("by_band", {}),
+            "top_risks_shown": len(top_risks),
+            "endpoint_access": access.get("summary", {}),
+            "unresolved_beans": len(posture.get("unresolved") or []),
+        },
+        "top_risks": top_risks,
+        "evidence": {
+            "risk": risk,
+            "posture": posture,
+        },
+        "limits": {
+            "statement": (
+                "This report packages existing ASK evidence. It does not certify "
+                "compliance, choose fixes, assign ROI, or replace a human audit decision."
+            ),
+            "non_coverage": (risk.get("non_coverage") or {}).get("items", []),
+        },
+    }
+    # Sign and publish the same JSON-normalized material. Some embedded evidence
+    # may contain tuples or other JSON-coercible values; normalizing before signing
+    # avoids a signature over an in-memory shape the user never receives.
+    normalized = json.loads(_canonical_json(unsigned).decode("utf-8"))
+    if sign_key:
+        normalized["signature"] = _sign(normalized, sign_key)
+    return normalized
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+    """Human report renderer over the JSON contract."""
+    summary = report.get("summary") or {}
+    repo = (report.get("repository") or {}).get("path", "")
+    profile = ", ".join(report.get("profile_set") or []) or "default"
+    lines = [
+        "# ASK Audit Report",
+        "",
+        f"- Repository: `{repo}`",
+        f"- ASK version: `{(report.get('tool') or {}).get('version', '')}`",
+        f"- Profile set: `{profile}`",
+        f"- Total defects: `{summary.get('total_defects')}`",
+        f"- Risk bands: `{summary.get('risk_bands')}`",
+        f"- Endpoint access: `{summary.get('endpoint_access')}`",
+        "",
+        "## Top Risks",
+        "",
+    ]
+    risks = report.get("top_risks") or []
+    if not risks:
+        lines.append("No composed risks were reported.")
+    else:
+        lines.extend([
+            "| Band | Score | Rules | File | Line | Title |",
+            "|---|---:|---|---|---:|---|",
+        ])
+        for row in risks:
+            rules = ", ".join(str(r) for r in row.get("rule_ids", []))
+            lines.append(
+                "| "
+                + " | ".join([
+                    str(row.get("band", "")),
+                    str(row.get("severity_effective", "")),
+                    rules,
+                    str(row.get("source_file", "")),
+                    str(row.get("first_line", "")),
+                    str(row.get("title", "")).replace("|", "\\|"),
+                ])
+                + " |"
+            )
+    lines.extend([
+        "",
+        "## Limits",
+        "",
+        str((report.get("limits") or {}).get("statement", "")),
+    ])
+    signature = report.get("signature")
+    if isinstance(signature, dict):
+        lines.extend([
+            "",
+            "## Signature",
+            "",
+            f"- Algorithm: `{signature.get('algorithm')}`",
+            f"- Payload SHA-256: `{signature.get('payload_sha256')}`",
+            f"- Key ID: `{signature.get('key_id')}`",
+            f"- Signature: `{signature.get('signature')}`",
+        ])
+    return "\n".join(lines) + "\n"