feat(demo): show runtime effects across control layers

README.md

@@ -44,6 +44,7 @@ For a first pass, the most useful public-facing surfaces are:
 | --- | --- |
 | [`docs/product.md`](docs/product.md) | One-page product overview for the before / during / after control loop. |
 | [`docs/quickstart.md`](docs/quickstart.md) | Minimal local session that writes a ledger and verifies proof. |
+| [`docs/runtime-effect-demo.md`](docs/runtime-effect-demo.md) | Shows the demo's before / during / after stages and L1-L5 control effects. |
 | [`docs/evaluation.md`](docs/evaluation.md) | Explains what the built-in benchmarks measure and what they do not claim. |
 | [`examples/`](examples/) | Small runnable examples before running the larger demos. |
 
@@ -152,6 +153,7 @@ Open the local docs:
 - [API and SDK](docs/api-sdk.md)
 - [Architecture](docs/architecture.md)
 - [Examples](docs/examples.md)
+- [Runtime effect demo](docs/runtime-effect-demo.md)
 - [Evaluation](docs/evaluation.md)
 - [Open-source boundary](docs/open-source-boundary.md)
 - [Brand assets](assets/brand/README.md)

docs/README.md

@@ -20,6 +20,7 @@ Public pages:
 | CLI reference | [`cli-reference.md`](cli-reference.md) | [`html/cli-reference.html`](html/cli-reference.html) |
 | API and SDK | [`api-sdk.md`](api-sdk.md) | [`html/api-sdk.html`](html/api-sdk.html) |
 | Examples | [`examples.md`](examples.md) | [`html/examples.html`](html/examples.html) |
+| Runtime effect demo | [`runtime-effect-demo.md`](runtime-effect-demo.md) | [`html/runtime-effect-demo.html`](html/runtime-effect-demo.html) |
 | Architecture | [`architecture.md`](architecture.md) | [`html/architecture.html`](html/architecture.html) |
 | Evaluation | [`evaluation.md`](evaluation.md) | [`html/evaluation.html`](html/evaluation.html) |
 | Open-source boundary | [`open-source-boundary.md`](open-source-boundary.md) | [`html/open-source-boundary.html`](html/open-source-boundary.html) |

docs/architecture.md

@@ -17,6 +17,12 @@ Invart is not a plugin-only wrapper. Plugin and hook integration can improve cov
 | L4 Mediation Plane | Unified decision and outcome contract across surfaces. | control/mediation.py, control/approval.py, control/gate.py |
 | L5 Evidence Plane | Proof, replay, graph, audit, coverage, evidence bundle, release gate. | assurance/postruntime.py, assurance/replay.py, assurance/path_graph.py, assurance/evidence_bundle.py |
 
+## Demo Verification
+
+The [runtime effect demo](runtime-effect-demo.md) is the concrete verification surface for this model. It renders a stage × layer matrix in the final demo entrypoint and an action timeline in each container risk case audit page. The timeline connects agent intent/action, Invart observation, policy or mediation decision, outcome, and the artifact that proves the step.
+
+Coverage terms remain strict: observed, mediated, and enforced are not interchangeable. Unmanaged direct execution is shown as a coverage gap unless it enters a managed launcher, wrapper, hook, broker, or shim.
+
 ## Source Layout
 
 ```bash

docs/html/architecture.html

@@ -19,6 +19,11 @@ <h2>Layer Model</h2>
         <tr><td>L5 Evidence Plane</td><td>Proof, replay, graph, audit, coverage, evidence bundle, release gate.</td><td><code>assurance/postruntime.py</code>, <code>assurance/replay.py</code>, <code>assurance/path_graph.py</code>, <code>assurance/evidence_bundle.py</code></td></tr>
       </table>
     </section>
+    <section>
+      <h2>Demo Verification</h2>
+      <p><a href="runtime-effect-demo.html">Runtime Effect Demo</a> is the concrete verification surface for this architecture. It renders a stage × layer matrix in the final demo entrypoint and an action timeline in each container risk case audit page.</p>
+      <p>Coverage terms remain strict: <code>observed</code>, <code>mediated</code>, and <code>enforced</code> are not interchangeable. Unmanaged direct execution is shown as a coverage gap unless it enters a managed launcher, wrapper, hook, broker, or shim.</p>
+    </section>
     <section>
       <h2>Source Layout</h2>
       <pre>src/invart/core/       fact model, ledger, stable artifact helpers

docs/html/index.html

@@ -17,6 +17,7 @@ <h1>Agent Runtime Control Plane</h1>
       <a href="quickstart.html">Quickstart</a>
       <a href="cli-reference.html">CLI</a>
       <a href="api-sdk.html">API &amp; SDK</a>
+      <a href="runtime-effect-demo.html">Runtime Effects</a>
       <a href="architecture.html">Architecture</a>
       <a href="evaluation.html">Evaluation</a>
     </nav>
@@ -29,6 +30,7 @@ <h2>Start</h2>
         <div class="card"><h3><a href="product.html">Product Overview</a></h3><p>What Invart is, who it helps, and how the three-stage control loop works.</p></div>
         <div class="card"><h3><a href="quickstart.html">Quickstart</a></h3><p>Install locally, create a managed session, record one action, export proof, and verify it.</p></div>
         <div class="card"><h3><a href="examples.html">Examples</a></h3><p>Runnable examples for local sessions, policy profiles, risk demos, and containerized flows.</p></div>
+        <div class="card"><h3><a href="runtime-effect-demo.html">Runtime Effect Demo</a></h3><p>See before / during / after runtime mapped to L1-L5 with a matrix and action timeline.</p></div>
       </div>
     </section>
     <section>

docs/html/product.html

@@ -33,7 +33,7 @@ <h2>Why Invart Exists</h2>
         <h3>Quick Demo</h3>
         <pre>invart demo real-world-risk-cases \
   --out-dir .invart/real-world-risk-demo</pre>
-        <p class="muted">Outputs a safe risk demo with ledger, proof, replay, audit, and evidence artifacts.</p>
+        <p class="muted">Outputs a safe risk demo with ledger, proof, replay, audit, and evidence artifacts. For the clearest walkthrough, open <a href="runtime-effect-demo.html">Runtime Effect Demo</a>.</p>
       </div>
     </section>
     <section class="band">
@@ -67,6 +67,10 @@ <h2>What You Can Show A Team</h2>
         </div>
       </div>
     </section>
+    <section class="wrap">
+      <h2>How To Verify The Model In A Demo</h2>
+      <p>Run <code>invart demo pre-1.0-final --out-dir .invart/pre-1-demo-check</code>, then open <code>pre-1.0-final-demo.html</code>. The Runtime Effect Matrix maps before-runtime, during-runtime, and after-runtime to L1-L5, while each container case audit page shows agent intent, Invart observation, policy or mediation decision, outcome, and artifact.</p>
+    </section>
   </main>
 </body>
 </html>

docs/html/runtime-effect-demo.html

@@ -0,0 +1,70 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>Invart Runtime Effect Demo</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <header class="hero">
+    <span class="badge">Runtime Effect Demo</span>
+    <h1>See the three stages and five layers in one run.</h1>
+    <p>Invart's demo artifacts show what was discovered before runtime, mediated during runtime, and reconstructed after runtime.</p>
+    <nav class="nav">
+      <a href="index.html">Docs Home</a>
+      <a href="product.html">Product</a>
+      <a href="architecture.html">Architecture</a>
+      <a href="evaluation.html">Evaluation</a>
+    </nav>
+  </header>
+  <main class="wrap">
+    <section>
+      <h2>Run</h2>
+      <pre>PYTHONPATH=src python -m invart.cli demo pre-1.0-final \
+  --out-dir .invart/pre-1-demo-check
+
+scripts/container-demo.sh all .invart/container-risk-demo</pre>
+    </section>
+    <section>
+      <h2>Runtime Effect Matrix</h2>
+      <table>
+        <tr><th>Layer</th><th>Before runtime</th><th>During runtime</th><th>After runtime</th></tr>
+        <tr><td>L1 Execution Surface</td><td>Inventory agent config, skills, MCP, wrappers, launchers, and unmanaged surfaces.</td><td>Observe file, network, shell, content, skill, and tool activity.</td><td>Review where coverage was strong, weak, or missing.</td></tr>
+        <tr><td>L2 Runtime Fact Model</td><td>Bind principal, agent identity, credentials, grants, and session.</td><td>Normalize invocations with resources, taint, coverage, decisions, and outcomes.</td><td>Use the ledger as the fact source.</td></tr>
+        <tr><td>L3 Decision Plane</td><td>Load deterministic policy and path-aware risk rules.</td><td>Classify secret egress, unsafe deletion, external instruction, and suspicious skill paths.</td><td>Explain why an action was allowed, paused, denied, or blocked.</td></tr>
+        <tr><td>L4 Mediation Plane</td><td>Route covered surfaces through managed launchers, wrappers, hooks, or brokers.</td><td>Apply allow, audit, require approval, deny, enforced block, or fail-open alert.</td><td>Show unresolved approvals and coverage gaps truthfully.</td></tr>
+        <tr><td>L5 Evidence Plane</td><td>Record the demo claim boundary and artifact map.</td><td>Generate replay, coverage, path graph, and policy artifacts.</td><td>Export proof, audit, evidence bundle, and RC gate report.</td></tr>
+      </table>
+    </section>
+    <section>
+      <h2>Action Timeline</h2>
+      <div class="flow">
+        <span class="node">Agent intent/action</span><span class="arrow">-></span>
+        <span class="node">Invart observation</span><span class="arrow">-></span>
+        <span class="node">Policy / mediation decision</span><span class="arrow">-></span>
+        <span class="node">Outcome</span><span class="arrow">-></span>
+        <span class="node">Artifact</span>
+      </div>
+      <p>Each container risk case audit page renders this sequence as a table so a reviewer can trace the run without reading raw JSON first.</p>
+    </section>
+    <section>
+      <h2>Artifact Map</h2>
+      <table>
+        <tr><th>Artifact</th><th>Layer signal</th><th>Use it for</th></tr>
+        <tr><td><code>ledger.jsonl</code></td><td>L2 fact source</td><td>Verifying the append-only event chain.</td></tr>
+        <tr><td><code>proof.json</code></td><td>L5 portable summary</td><td>Answering who, what, why, policy, approval, outcome, and coverage.</td></tr>
+        <tr><td><code>replay.html</code></td><td>L4 mediation trace</td><td>Reading approvals, denials, raw evidence folds, and outcomes.</td></tr>
+        <tr><td><code>path-graph.html</code></td><td>L3 causal chain</td><td>Tracing risky paths such as secret read to network sink.</td></tr>
+        <tr><td><code>coverage.html</code></td><td>L4/L5 truthfulness</td><td>Checking observed, mediated, enforced, and fail-open claims.</td></tr>
+        <tr><td><code>audit-report.html</code></td><td>L5 reviewer report</td><td>Presenting the enterprise security review view.</td></tr>
+      </table>
+    </section>
+    <section>
+      <h2>Boundary</h2>
+      <p>The container demo uses safe equivalent trajectories. It does not install hostile packages or replay private incidents.</p>
+      <p><code>observed</code>, <code>mediated</code>, and <code>enforced</code> are separate claims. Unmanaged direct agent execution is shown as a coverage gap unless it enters a managed Invart surface.</p>
+    </section>
+  </main>
+</body>
+</html>

docs/index.md

@@ -23,6 +23,10 @@ Install locally, create a managed session, record one action, export proof, and
 
 Runnable examples for local sessions, policy profiles, risk demos, and containerized flows.
 
+### [Runtime Effect Demo](runtime-effect-demo.md)
+
+Read the demo matrix and action timeline that map before / during / after runtime to L1-L5.
+
 ## Understand
 
 ### [Core Concepts](concepts.md)

docs/product.md

@@ -20,6 +20,8 @@ invart demo real-world-risk-cases \
 
 Outputs a safe risk demo with ledger, proof, replay, audit, and evidence artifacts.
 
+For the clearest model walkthrough, open the [runtime effect demo](runtime-effect-demo.md). It maps each demo run across before-runtime, during-runtime, after-runtime and the L1-L5 control layers.
+
 ## Three Stages
 
 | Stage | Question | Invart Output |
@@ -63,3 +65,7 @@ Whether managed launchers, wrappers, hooks, and benchmark harnesses can run with
 ### Developers
 
 Low-risk commands continue automatically, while high-risk steps receive precise context instead of vague warnings.
+
+## How To Verify The Model In A Demo
+
+Run `invart demo pre-1.0-final --out-dir .invart/pre-1-demo-check`, then open `pre-1.0-final-demo.html`. The Runtime Effect Matrix shows the three lifecycle stages across L1-L5, and each container risk case audit page shows an action timeline from agent intent through Invart observation, policy or mediation decision, outcome, and artifact.

docs/runtime-effect-demo.md

@@ -0,0 +1,54 @@
+# Runtime effect demo
+
+[HTML version](html/runtime-effect-demo.html)
+
+This page explains how to see Invart's three runtime stages and five control layers in the demo artifacts.
+
+The short version: run a demo, open the HTML entrypoint, then read the matrix first and the timeline second.
+
+## Run The Demo
+
+```bash
+PYTHONPATH=src python -m invart.cli demo pre-1.0-final \
+  --out-dir .invart/pre-1-demo-check
+```
+
+For isolated per-risk-case runs:
+
+```bash
+scripts/container-demo.sh all .invart/container-risk-demo
+```
+
+## What To Look For
+
+| View | What it proves | Main artifact |
+| --- | --- | --- |
+| Runtime Effect Matrix | Before, during, and after runtime are mapped to L1-L5. | `pre-1.0-final-demo.html` |
+| Action Timeline | One case shows agent action, Invart observation, policy decision, outcome, and artifact. | `container-risk-audit.html` |
+| Path Graph | Risk chains such as secret read to external network sink can be traced. | `path-graph.html` |
+| Coverage Report | Observed, mediated, and enforced are reported as different claims. | `coverage.html` |
+| Audit Report | A reviewer can answer who, what, why, policy, approval, outcome, and coverage. | `audit-report.html` |
+
+## Three Runtime Stages
+
+| Stage | Demo signal |
+| --- | --- |
+| Before runtime | Surface inventory, unmanaged agent findings, identity binding, credential boundary, and grant setup. |
+| During runtime | File, network, shell, skill, content, and mediation events become ledger-backed facts. |
+| After runtime | Proof, replay, path graph, coverage, audit, and evidence bundles reconstruct what happened. |
+
+## Five Control Layers
+
+| Layer | Demo effect |
+| --- | --- |
+| L1 Execution Surface | Shows where commands, files, network, skills, MCP, launchers, and hooks enter the control plane. |
+| L2 Runtime Fact Model | Shows invocations, taint, identity, resources, coverage, outcomes, and ledger records. |
+| L3 Decision Plane | Shows deterministic rules, path-aware policy, and non-downgradable critical findings. |
+| L4 Mediation Plane | Shows allow, audit, require approval, deny, enforced block, and fail-open alert semantics. |
+| L5 Evidence Plane | Shows proof, replay, graph, coverage, audit, evidence bundle, and release gate outputs. |
+
+## Boundaries
+
+The container demo uses safe equivalent trajectories. It does not install hostile packages or replay private incidents.
+
+Coverage labels are intentionally strict. `observed`, `mediated`, and `enforced` are not interchangeable, and unmanaged direct agent execution is shown as a coverage gap unless it enters a managed Invart surface.