sourcecode 1.30.14__tar.gz → 1.30.16__tar.gz

{sourcecode-1.30.14 → sourcecode-1.30.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.30.14
+Version: 1.30.16
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -221,7 +221,7 @@ Description-Content-Type: text/markdown
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.14-blue)
+![Version](https://img.shields.io/badge/version-1.30.16-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -257,7 +257,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.14
+# sourcecode 1.30.16
 ```
 
 ---
@@ -353,6 +353,7 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 |--------|-------------|
 | `--since REF` | Git ref for `delta` task (e.g. `HEAD~3`, `main`, `v1.2.0`). Required for `delta`; ignored for other tasks. |
 | `--symptom TEXT` | *(fix-bug only)* Keyword hint for the bug — boosts matching files and surfaces related code notes. |
+| `--format TEXT` | Output format: `json` (default) \| `github-comment` (Markdown PR comment, `review-pr` only). |
 | `--llm-prompt` | Append a ready-to-use LLM prompt to the output. |
 | `--dry-run` | Show what would be analyzed without running it. |
 | `--copy` / `-c` | Copy output to clipboard after a successful run. |
@@ -374,6 +375,9 @@ sourcecode prepare-context delta . --since main
 # Onboard with a ready-to-paste LLM prompt
 sourcecode prepare-context onboard --llm-prompt
 
+# PR analysis as a GitHub Markdown comment (paste directly into PR)
+sourcecode prepare-context review-pr --since main --format github-comment
+
 # List all tasks
 sourcecode prepare-context --task-help
 ```
@@ -444,22 +448,25 @@ sourcecode prepare-context review-pr
       "name": "Order",
       "entry_point": {
         "step": "OrderController.createOrder",
-        "notes": ["condition: authorization check present (@PreAuthorize / @Secured)"]
+        "notes": [
+          { "note": "condition: authorization check present (@PreAuthorize / @Secured)",
+            "epistemic_level": "STRUCTURAL SIGNAL" }
+        ]
       },
       "path": [
         {
           "step": "ShippingService.process",
           "notes": [
-            "branch: Spring cache may short-circuit downstream call",
-            "async: runs in separate thread (@Async)"
+            { "note": "branch: Spring cache annotation present — downstream call may be short-circuited",
+              "epistemic_level": "STRUCTURAL SIGNAL" },
+            { "note": "async: @Async annotation present — runs in separate thread",
+              "epistemic_level": "STRUCTURAL SIGNAL" }
           ]
         },
-        {
-          "step": "OrderRepository.save",
-          "notes": []
-        }
+        { "step": "OrderRepository.save", "notes": [] }
       ],
-      "end_state": "DB write"
+      "end_state": "DB write",
+      "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)"
     }
   ]
 }
@@ -474,17 +481,33 @@ sourcecode prepare-context review-pr
 
 **Runtime signals detected per step:**
 
-| Signal | Example code | Note emitted |
-|--------|-------------|--------------|
-| Auth guard | `@PreAuthorize`, `@Secured`, `isAuthenticated()` | `condition: authorization check present` |
-| Feature flag | `featureFlag.isEnabled()`, `FeatureToggle` | `condition: feature flag gates execution` |
-| Null/empty guard | `if (x == null) return` | `condition: null/empty guard with early return` |
-| Spring cache | `@Cacheable`, `@CacheEvict` | `branch: Spring cache may short-circuit downstream call` |
-| Optional absence | `Optional<>`, `.orElseThrow()` | `branch: result may be absent (Optional)` |
-| Async thread | `@Async`, `CompletableFuture` | `async: runs in separate thread (@Async)` |
-| Event publishing | `publishEvent()`, `applicationEventPublisher` | `async: Spring application event emitted` |
-| Kafka | `kafkaTemplate.send()` | `async: Kafka message produced` |
-| RabbitMQ | `rabbitTemplate.send()` | `async: RabbitMQ message sent` |
+| Signal | Example code | Note emitted | Epistemic level |
+|--------|-------------|--------------|-----------------|
+| Auth guard | `@PreAuthorize`, `@Secured` | `condition: authorization check present (@PreAuthorize / @Secured)` | `STRUCTURAL SIGNAL` |
+| Auth context read | `isAuthenticated()`, `SecurityContextHolder` | `condition: reads authentication context` | `STRUCTURAL SIGNAL` |
+| Feature flag | `featureFlag.isEnabled()`, `FeatureToggle` | `condition: feature flag gates execution` | `INFERRED (LOW CONFIDENCE)` |
+| Null/empty guard | `if (x == null) return` | `condition: null/empty guard with early return` | `STRUCTURAL SIGNAL` |
+| Spring cache | `@Cacheable`, `@CacheEvict` | `branch: Spring cache annotation present — downstream call may be short-circuited` | `STRUCTURAL SIGNAL` |
+| Manual cache | `cache.get()`, `cacheManager.` | `branch: manual cache lookup detected — downstream call may be short-circuited` | `INFERRED (LOW CONFIDENCE)` |
+| Optional absence | `Optional<>`, `.orElseThrow()` | `branch: Optional type in use — result may be absent` | `STRUCTURAL SIGNAL` |
+| Async thread | `@Async` | `async: @Async annotation present — runs in separate thread` | `STRUCTURAL SIGNAL` |
+| CompletableFuture | `CompletableFuture`, `.supplyAsync()` | `async: CompletableFuture detected — non-blocking execution` | `STRUCTURAL SIGNAL` |
+| Event publishing | `publishEvent()`, `applicationEventPublisher` | `async: Spring application event emitted` | `STRUCTURAL SIGNAL` |
+| Kafka | `kafkaTemplate.`, `KafkaProducer` | `async: Kafka producer detected` | `STRUCTURAL SIGNAL` |
+| RabbitMQ | `rabbitTemplate.`, `amqpTemplate.` | `async: RabbitMQ producer detected` | `STRUCTURAL SIGNAL` |
+
+**Epistemic contract:**
+
+Every output field in `review-pr` carries an explicit `epistemic_level`:
+
+| Level | Meaning |
+|-------|---------|
+| `FACT` | Directly observed in diff (file present, config changed) |
+| `STRUCTURAL SIGNAL` | Annotation or type-system evidence in source (`@Service`, `@Transactional`, injection) |
+| `INFERRED (LOW CONFIDENCE)` | Heuristic pattern match — no full structural proof |
+| `OMITTED` | Insufficient evidence — field not emitted |
+
+No field blends certainty levels without labeling. `end_state` (e.g. `"DB write"`) is always accompanied by `end_state_epistemic_level: "INFERRED (LOW CONFIDENCE)"` — it is a keyword-match heuristic, not an AST-verified fact.
 
 **Other `review-pr` output fields:**
 
@@ -492,9 +515,9 @@ sourcecode prepare-context review-pr
 |-------|-------------|
 | `review_hotspots` | Top changed files ranked by impact score |
 | `suggested_review_order` | Security → API → Service → Persistence → Config |
-| `security_impact` | Changed files touching the security surface |
-| `transactional_impact` | Files crossing transaction boundaries |
-| `test_coverage_risk` | Changed source files with no corresponding test |
+| `security_impact` | Changed security-classified files (`epistemic_level: STRUCTURAL SIGNAL`) + risk note (`INFERRED (LOW CONFIDENCE)`) |
+| `transactional_impact` | Changed service/business-logic files with possible transaction boundary effect |
+| `test_coverage_risk` | Changed source files with no corresponding test (`epistemic_level: INFERRED (LOW CONFIDENCE)`) |
 | `affected_modules` | DDD domain modules touched by the change |
 
 ---

{sourcecode-1.30.14 → sourcecode-1.30.16}/README.md

@@ -2,7 +2,7 @@
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.14-blue)
+![Version](https://img.shields.io/badge/version-1.30.16-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -38,7 +38,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.14
+# sourcecode 1.30.16
 ```
 
 ---
@@ -134,6 +134,7 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 |--------|-------------|
 | `--since REF` | Git ref for `delta` task (e.g. `HEAD~3`, `main`, `v1.2.0`). Required for `delta`; ignored for other tasks. |
 | `--symptom TEXT` | *(fix-bug only)* Keyword hint for the bug — boosts matching files and surfaces related code notes. |
+| `--format TEXT` | Output format: `json` (default) \| `github-comment` (Markdown PR comment, `review-pr` only). |
 | `--llm-prompt` | Append a ready-to-use LLM prompt to the output. |
 | `--dry-run` | Show what would be analyzed without running it. |
 | `--copy` / `-c` | Copy output to clipboard after a successful run. |
@@ -155,6 +156,9 @@ sourcecode prepare-context delta . --since main
 # Onboard with a ready-to-paste LLM prompt
 sourcecode prepare-context onboard --llm-prompt
 
+# PR analysis as a GitHub Markdown comment (paste directly into PR)
+sourcecode prepare-context review-pr --since main --format github-comment
+
 # List all tasks
 sourcecode prepare-context --task-help
 ```
@@ -225,22 +229,25 @@ sourcecode prepare-context review-pr
       "name": "Order",
       "entry_point": {
         "step": "OrderController.createOrder",
-        "notes": ["condition: authorization check present (@PreAuthorize / @Secured)"]
+        "notes": [
+          { "note": "condition: authorization check present (@PreAuthorize / @Secured)",
+            "epistemic_level": "STRUCTURAL SIGNAL" }
+        ]
       },
       "path": [
         {
           "step": "ShippingService.process",
           "notes": [
-            "branch: Spring cache may short-circuit downstream call",
-            "async: runs in separate thread (@Async)"
+            { "note": "branch: Spring cache annotation present — downstream call may be short-circuited",
+              "epistemic_level": "STRUCTURAL SIGNAL" },
+            { "note": "async: @Async annotation present — runs in separate thread",
+              "epistemic_level": "STRUCTURAL SIGNAL" }
           ]
         },
-        {
-          "step": "OrderRepository.save",
-          "notes": []
-        }
+        { "step": "OrderRepository.save", "notes": [] }
       ],
-      "end_state": "DB write"
+      "end_state": "DB write",
+      "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)"
     }
   ]
 }
@@ -255,17 +262,33 @@ sourcecode prepare-context review-pr
 
 **Runtime signals detected per step:**
 
-| Signal | Example code | Note emitted |
-|--------|-------------|--------------|
-| Auth guard | `@PreAuthorize`, `@Secured`, `isAuthenticated()` | `condition: authorization check present` |
-| Feature flag | `featureFlag.isEnabled()`, `FeatureToggle` | `condition: feature flag gates execution` |
-| Null/empty guard | `if (x == null) return` | `condition: null/empty guard with early return` |
-| Spring cache | `@Cacheable`, `@CacheEvict` | `branch: Spring cache may short-circuit downstream call` |
-| Optional absence | `Optional<>`, `.orElseThrow()` | `branch: result may be absent (Optional)` |
-| Async thread | `@Async`, `CompletableFuture` | `async: runs in separate thread (@Async)` |
-| Event publishing | `publishEvent()`, `applicationEventPublisher` | `async: Spring application event emitted` |
-| Kafka | `kafkaTemplate.send()` | `async: Kafka message produced` |
-| RabbitMQ | `rabbitTemplate.send()` | `async: RabbitMQ message sent` |
+| Signal | Example code | Note emitted | Epistemic level |
+|--------|-------------|--------------|-----------------|
+| Auth guard | `@PreAuthorize`, `@Secured` | `condition: authorization check present (@PreAuthorize / @Secured)` | `STRUCTURAL SIGNAL` |
+| Auth context read | `isAuthenticated()`, `SecurityContextHolder` | `condition: reads authentication context` | `STRUCTURAL SIGNAL` |
+| Feature flag | `featureFlag.isEnabled()`, `FeatureToggle` | `condition: feature flag gates execution` | `INFERRED (LOW CONFIDENCE)` |
+| Null/empty guard | `if (x == null) return` | `condition: null/empty guard with early return` | `STRUCTURAL SIGNAL` |
+| Spring cache | `@Cacheable`, `@CacheEvict` | `branch: Spring cache annotation present — downstream call may be short-circuited` | `STRUCTURAL SIGNAL` |
+| Manual cache | `cache.get()`, `cacheManager.` | `branch: manual cache lookup detected — downstream call may be short-circuited` | `INFERRED (LOW CONFIDENCE)` |
+| Optional absence | `Optional<>`, `.orElseThrow()` | `branch: Optional type in use — result may be absent` | `STRUCTURAL SIGNAL` |
+| Async thread | `@Async` | `async: @Async annotation present — runs in separate thread` | `STRUCTURAL SIGNAL` |
+| CompletableFuture | `CompletableFuture`, `.supplyAsync()` | `async: CompletableFuture detected — non-blocking execution` | `STRUCTURAL SIGNAL` |
+| Event publishing | `publishEvent()`, `applicationEventPublisher` | `async: Spring application event emitted` | `STRUCTURAL SIGNAL` |
+| Kafka | `kafkaTemplate.`, `KafkaProducer` | `async: Kafka producer detected` | `STRUCTURAL SIGNAL` |
+| RabbitMQ | `rabbitTemplate.`, `amqpTemplate.` | `async: RabbitMQ producer detected` | `STRUCTURAL SIGNAL` |
+
+**Epistemic contract:**
+
+Every output field in `review-pr` carries an explicit `epistemic_level`:
+
+| Level | Meaning |
+|-------|---------|
+| `FACT` | Directly observed in diff (file present, config changed) |
+| `STRUCTURAL SIGNAL` | Annotation or type-system evidence in source (`@Service`, `@Transactional`, injection) |
+| `INFERRED (LOW CONFIDENCE)` | Heuristic pattern match — no full structural proof |
+| `OMITTED` | Insufficient evidence — field not emitted |
+
+No field blends certainty levels without labeling. `end_state` (e.g. `"DB write"`) is always accompanied by `end_state_epistemic_level: "INFERRED (LOW CONFIDENCE)"` — it is a keyword-match heuristic, not an AST-verified fact.
 
 **Other `review-pr` output fields:**
 
@@ -273,9 +296,9 @@ sourcecode prepare-context review-pr
 |-------|-------------|
 | `review_hotspots` | Top changed files ranked by impact score |
 | `suggested_review_order` | Security → API → Service → Persistence → Config |
-| `security_impact` | Changed files touching the security surface |
-| `transactional_impact` | Files crossing transaction boundaries |
-| `test_coverage_risk` | Changed source files with no corresponding test |
+| `security_impact` | Changed security-classified files (`epistemic_level: STRUCTURAL SIGNAL`) + risk note (`INFERRED (LOW CONFIDENCE)`) |
+| `transactional_impact` | Changed service/business-logic files with possible transaction boundary effect |
+| `test_coverage_risk` | Changed source files with no corresponding test (`epistemic_level: INFERRED (LOW CONFIDENCE)`) |
 | `affected_modules` | DDD domain modules touched by the change |
 
 ---

{sourcecode-1.30.14 → sourcecode-1.30.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.30.14"
+version = "1.30.16"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.30.14 → sourcecode-1.30.16}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.30.14"
+__version__ = "1.30.16"

{sourcecode-1.30.14 → sourcecode-1.30.16}/src/sourcecode/cli.py

@@ -161,7 +161,7 @@ Compressed AI-ready context for Java/Spring enterprise codebases.
 # Known subcommand names — tokens matching these are routed as subcommands,
 # not consumed as a repository path.
 _SUBCOMMANDS: frozenset[str] = frozenset(
-    {"telemetry", "prepare-context", "version", "config", "analyze"}
+    {"telemetry", "prepare-context", "version", "config", "analyze", "repo-ir"}
 )
 
 # Mutable container holding the path extracted by _preprocess_argv().
@@ -1513,10 +1513,31 @@ def main(
             data = redact_dict(data)
         content = json.dumps(data, indent=2, ensure_ascii=False)
     elif compact:
+        if changed_only and _allowed_changed_files:
+            sm = _replace(sm,
+                file_paths=[p for p in sm.file_paths if p in _allowed_changed_files],
+                entry_points=[ep for ep in sm.entry_points if ep.path in _allowed_changed_files],
+                code_notes=[n for n in sm.code_notes if n.path in _allowed_changed_files],
+            )
         data = compact_view(sm, no_tree=no_tree, full=full)
         if not no_redact:
             data = redact_dict(data)
-        content = json.dumps(data, indent=2, ensure_ascii=False)
+        if format == "yaml":
+            from io import StringIO
+            from ruamel.yaml import YAML as _YAML
+            _yaml = _YAML()
+            _yaml.default_flow_style = False
+            _yaml.representer.add_representer(
+                type(None),
+                lambda dumper, data_val: dumper.represent_scalar(
+                    "tag:yaml.org,2002:null", "null"
+                ),
+            )
+            _stream = StringIO()
+            _yaml.dump(data, _stream)
+            content = _stream.getvalue()
+        else:
+            content = json.dumps(data, indent=2, ensure_ascii=False)
     else:
         raw_dict = standard_view(sm, include_tree=tree and not no_tree)
         if not no_redact:
@@ -1622,6 +1643,11 @@ def prepare_context_cmd(
         "--symptom",
         help="(fix-bug) Keyword hint for the bug: boosts matching files and surfaces related code notes.",
     ),
+    format: Optional[str] = typer.Option(
+        None,
+        "--format",
+        help="Output format: json (default) | github-comment (Markdown PR comment for review-pr task)",
+    ),
 ) -> None:
     """Task-specific context for AI coding agents.
 
@@ -1895,7 +1921,12 @@ def prepare_context_cmd(
     if llm_prompt:
         out["llm_prompt"] = builder.render_prompt(output)
 
-    _pc_content = json.dumps(out, indent=2, ensure_ascii=False)
+    if format == "github-comment" and task == "review-pr":
+        from sourcecode.pr_comment_renderer import render_github_comment
+        _pc_content = render_github_comment(out)
+    else:
+        _pc_content = json.dumps(out, indent=2, ensure_ascii=False)
+
     if output_path is not None:
         output_path.write_text(_pc_content, encoding="utf-8")
     else:

{sourcecode-1.30.14 → sourcecode-1.30.16}/src/sourcecode/flow_analyzer.py

@@ -33,43 +33,57 @@ _METHOD_NAME_RE = re.compile(
     r'(\w+)\s*\(',
 )
 
-# Runtime signal patterns: (compiled_regex, note_text)
-# Only signals with explicit code evidence — no inference.
-# Three categories: condition | branch | async
-_RUNTIME_SIGNALS: list[tuple[re.Pattern, str]] = [
+# Runtime signal patterns: (compiled_regex, note_text, epistemic_level)
+# epistemic_level follows the 4-value contract:
+#   STRUCTURAL SIGNAL  — annotation or type-system evidence directly observed in source
+#   INFERRED (LOW CONFIDENCE) — heuristic code-pattern match; no full structural proof
+_RUNTIME_SIGNALS: list[tuple[re.Pattern, str, str]] = [
     # ── Conditional / auth guards ─────────────────────────────────────────────
     (re.compile(r'@PreAuthorize|@Secured|@RolesAllowed', re.IGNORECASE),
-     "condition: authorization check present (@PreAuthorize / @Secured)"),
+     "condition: authorization check present (@PreAuthorize / @Secured)",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'isAuthenticated\(\)|hasRole\(|hasAuthority\(|SecurityContextHolder', re.IGNORECASE),
-     "condition: reads authentication context"),
+     "condition: reads authentication context",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'featureFlag|FeatureToggle|\.isEnabled\s*\(|\.isActive\s*\(', re.IGNORECASE),
-     "condition: feature flag gates execution"),
+     "condition: feature flag gates execution",
+     "INFERRED (LOW CONFIDENCE)"),
     # Null/empty guard with early return — matches if (...null/empty...) return/throw on same line
     (re.compile(r'if\s*\([^)]*(?:==\s*null|!=\s*null|isEmpty\s*\(\)|isBlank\s*\(\))[^)]*\)'
                 r'\s*(?:\{?\s*)?(?:return|throw)\b', re.IGNORECASE),
-     "condition: null/empty guard with early return"),
+     "condition: null/empty guard with early return",
+     "STRUCTURAL SIGNAL"),
 
     # ── Optional execution / branching ────────────────────────────────────────
     (re.compile(r'@Cacheable|@CacheEvict|@CachePut', re.IGNORECASE),
-     "branch: Spring cache may short-circuit downstream call"),
+     "branch: Spring cache annotation present — downstream call may be short-circuited",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'\.getIfPresent\s*\(|cache\.get\s*\(|cacheManager\.', re.IGNORECASE),
-     "branch: manual cache lookup may short-circuit"),
+     "branch: manual cache lookup detected — downstream call may be short-circuited",
+     "INFERRED (LOW CONFIDENCE)"),
     (re.compile(r'Optional\s*<|\.orElseThrow\s*\(|\.orElseGet\s*\(|\.orElse\s*\(', re.IGNORECASE),
-     "branch: result may be absent (Optional)"),
+     "branch: Optional type in use — result may be absent",
+     "STRUCTURAL SIGNAL"),
 
     # ── Async / side effects ──────────────────────────────────────────────────
     (re.compile(r'@Async\b'),
-     "async: runs in separate thread (@Async)"),
+     "async: @Async annotation present — runs in separate thread",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'CompletableFuture|\.supplyAsync\s*\(|\.runAsync\s*\('),
-     "async: non-blocking future-based execution"),
+     "async: CompletableFuture detected — non-blocking execution",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'\basync\s+def\b|\bawait\b', re.IGNORECASE),
-     "async: non-blocking (async/await)"),
+     "async: async/await detected — non-blocking execution",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'publishEvent\s*\(|applicationEventPublisher|eventPublisher\.', re.IGNORECASE),
-     "async: Spring application event emitted"),
+     "async: Spring application event emitted",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'kafkaTemplate\.|KafkaProducer|@KafkaListener', re.IGNORECASE),
-     "async: Kafka message produced"),
+     "async: Kafka producer detected",
+     "STRUCTURAL SIGNAL"),
     (re.compile(r'rabbitTemplate\.|amqpTemplate\.|@RabbitListener', re.IGNORECASE),
-     "async: RabbitMQ message sent"),
+     "async: RabbitMQ producer detected",
+     "STRUCTURAL SIGNAL"),
 ]
 
 
@@ -98,18 +112,19 @@ def _read_safe(root: Path, rel_path: str) -> str:
         return ""
 
 
-def _collect_runtime_notes(content: str, lang: str) -> list[str]:
+def _collect_runtime_notes(content: str, lang: str) -> list[dict]:
     """Scan comment-stripped content for explicit runtime behavior signals.
 
     Returns only notes backed by a direct code pattern match.
+    Each entry: {note: str, epistemic_level: str}.
     Returns [] when no signals are found.
     """
     clean = _strip_comments(content, lang)
-    notes: list[str] = []
+    notes: list[dict] = []
     seen: set[str] = set()
-    for pattern, note in _RUNTIME_SIGNALS:
+    for pattern, note, epistemic_level in _RUNTIME_SIGNALS:
         if note not in seen and pattern.search(clean):
-            notes.append(note)
+            notes.append({"note": note, "epistemic_level": epistemic_level})
             seen.add(note)
     return notes
 
@@ -348,8 +363,11 @@ def analyze_execution_paths(
             "entry_point": {"step": entry_point_str, "notes": entry_notes},
             "path": path_items,
             "end_state": _detect_end_state([item["step"] for item in path_items]),
+            "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)",
         })
 
+    return result
+
 
 # ── Behavioral impact helpers ─────────────────────────────────────────────────
 
@@ -363,9 +381,13 @@ def _domain_from_class(class_name: str) -> str:
     return re.sub(r"(?<=[a-z])(?=[A-Z])", " ", stripped).strip().lower()
 
 
-def _impact_item(statement: str, support: str, certainty: str) -> dict:
-    truth_level = "observed" if certainty == "high" else "inferred"
-    return {"statement": statement, "support": support, "certainty": certainty, "truth_level": truth_level}
+def _impact_item(statement: str, support: str, certainty: str, *, epistemic_level: Optional[str] = None) -> dict:
+    if epistemic_level is None:
+        if certainty in ("high", "medium"):
+            epistemic_level = "STRUCTURAL SIGNAL"
+        else:
+            epistemic_level = "INFERRED (LOW CONFIDENCE)"
+    return {"statement": statement, "support": support, "epistemic_level": epistemic_level}
 
 
 def _impact_descriptions(
@@ -449,6 +471,7 @@ def _impact_descriptions_for_controller(
             "controller entry point modified",
             "controller entry point is in changed files (direct diff evidence)",
             certainty,
+            epistemic_level="FACT",
         ))
 
     if re.search(r"@PreAuthorize|@Secured|@RolesAllowed|hasRole\(|isAuthenticated", ctrl_clean, re.IGNORECASE):
@@ -541,6 +564,7 @@ def analyze_behavioral_impact(
             "affected_path": affected_path,
             "impact": _impact_descriptions_for_controller(affected_path, end_state, ctrl_clean, evidence_level),
             "end_state": end_state,
+            "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)",
             "confidence": confidence,
             "evidence_level": evidence_level,
             "trace": trace,
@@ -638,6 +662,7 @@ def analyze_behavioral_impact(
                 "affected_path": affected_path,
                 "impact": _impact_descriptions(changed_class, changed_type, end_state, ctrl_clean, evidence_level),
                 "end_state": end_state,
+                "end_state_epistemic_level": "INFERRED (LOW CONFIDENCE)",
                 "confidence": confidence,
                 "evidence_level": evidence_level,
                 "trace": trace,