saidso 0.1.0__tar.gz

saidso-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+*.jsonl
+.env
+.DS_Store
+attestations.jsonl
+.claude/
+/tests
+/graphify-out

saidso-0.1.0/Docs/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 0.1.0
+
+First release. A grounding firewall for action-taking agents.
+
+### Core
+- `@grounded` decorator: per-argument grounding policies, block-and-steer on
+  failure, attestation on success. Sync **and** async tools.
+- Policies: `SPOKEN`, `CONFIRMED`, `CALLER_ID`, `INFERABLE`.
+- `Transcript` buffer, `call_context` plumbing (contextvars).
+- Deterministic matcher with number-word / year / date / phone / text
+  normalization. Uses `rapidfuzz` if installed, stdlib `difflib` otherwise
+  (zero required dependencies).
+- `AttestationLog`: in-memory + optional JSONL provenance ledger.
+- `SteerBack` return contract with auto-generated re-ask messages.
+- `saidso.testing.GroundingCase`: replay harness for CI gates.
+
+### Production hardening
+- **Fail-closed**: a matcher exception blocks the call and logs, never crashes
+  or lets it through.
+- **Decoration-time validation**: guarding a non-existent parameter raises
+  immediately (typos can't leave real args unguarded); unknown policy strings
+  and empty policy sets raise.
+- **No digit-substring over-matching**: numbers match as whole values only
+  (`"2"` is not grounded by `"20"`).
+- **No short-string fuzzy over-matching**: tokens shorter than 4 chars require
+  exact word matches; multi-token values require every token to match.
+- **Type coercion**: `date` / `datetime` / `int` / `float` / `bool` / `Decimal`
+  arguments are rendered deterministically before comparison.
+- **`CONFIRMED` tolerates filler/backchannel** turns between read-back and the
+  caller's "yes".
+- **Comma-grouped numbers** (`1,250`) parse correctly.
+- `VAR_KEYWORD` (`**kwargs`) functions: guarded args resolved from the kwargs
+  dict.
+- Observability via the `saidso` logger; `py.typed` ships type information.

saidso-0.1.0/Docs/DESIGN.md

@@ -0,0 +1,72 @@
+# saidso — design
+
+## The one primitive
+
+A checkpoint between an agent's "call `f(args)`" and the code that runs `f`. It
+refuses the call unless every guarded argument traces back to the transcript,
+and it keeps a receipt for the ones that pass.
+
+Everything else is packaging around that.
+
+## Module map
+
+| Module | Responsibility |
+|---|---|
+| `transcript.py` | Append-only, timestamped buffer of `Turn`s (user/agent/system). |
+| `normalize.py` | Deterministic normalization: number words, years, dates, phones, text. The make-or-break layer. |
+| `_fuzz.py` | Fuzzy match with `rapidfuzz` when present, `difflib` fallback. Zero required deps. |
+| `matcher.py` | Per-policy checkers (`SPOKEN`/`CONFIRMED`/`CALLER_ID`/`INFERABLE`) → `GroundingResult` + span. |
+| `policy.py` | `Policy` enum + default thresholds. |
+| `result.py` | `Span`, `GroundingResult`, `ArgFinding`, `SteerBack` (the block-and-steer contract). |
+| `context.py` | `CallContext` + `contextvars` so the decorator reads transcript/metadata implicitly. |
+| `attestation.py` | `Attestation` + `AttestationLog` (in-memory + optional JSONL). |
+| `grounding.py` | The `@grounded` decorator: bind args → check → block or run + attest. |
+
+## Control flow of a guarded call
+
+```
+call f(name=..., dob=...)
+   │  (decorator) bind args to names via inspect.signature
+   │  resolve CallContext (explicit override > contextvar > empty)
+   ▼
+for each guarded arg: matcher.check(value, policy, transcript, ctx)
+   │
+   ├─ any ungrounded ─► build SteerBack(failed, grounded) ─► return it
+   │                    (or raise GroundingBlocked if configured)
+   │
+   └─ all grounded ──► ledger.build(action, findings) ─► run f(...) ─► return
+```
+
+## Why deterministic-first
+
+The realtime voice loop has a hard latency ceiling. So matching is:
+
+1. **Normalize** the value and the transcript to the same shape (digits, ISO
+   dates, lowercased text).
+2. **Exact** (normalized substring) → high confidence.
+3. **Fuzzy** (`partial_ratio` ≥ threshold) → medium confidence, with the
+   matched turn as the span.
+
+A verifier-model escalation for genuinely ambiguous cases is a roadmap hook,
+not on the hot path.
+
+### Dates specifically
+
+Full date parsing of free speech is brittle, so `SPOKEN` for a date passes if
+**either** the whole turn parses to the same ISO date **or** all three
+components (year, month, day — in digit *or* spoken form) appear in one turn
+(`date_components_present`). The component check is the robust workhorse.
+
+## The trust trade-off
+
+This is a **hard firewall**: it can block a legitimate action if the matcher
+fails to recognize a real value (a false positive). That is the central risk
+and the thing to measure. Thresholds are tunable per policy via
+`GroundingConfig`. The steer-back design softens the cost: a wrong block just
+makes the agent re-ask, rather than crashing the call.
+
+## Anti-priming (why example values are absent)
+
+Tool descriptions and guard prompts deliberately never contain a placeholder
+"bad" value (e.g. a sample DOB). Putting an example value in the prompt teaches
+the model to emit it. The future prompt compiler enforces this automatically.

saidso-0.1.0/Docs/ROADMAP.md

@@ -0,0 +1,47 @@
+# saidso — roadmap
+
+The MVP is deliberately small and deterministic. These are the pieces that turn
+it from a useful decorator into a category-defining tool.
+
+## 1. Verifier-model escalation
+When deterministic matching lands in the ambiguous band (near the threshold),
+escalate that single argument to a tiny, fast model: "Did the caller say X?
+Quote the words." Keep it off the hot path; cache per-turn. Pluggable backend.
+
+## 2. Anti-priming prompt compiler
+Generate tool descriptions and guard prompts that enforce fidelity **without
+ever naming a bad example value** (example values teach the model to emit them).
+Input: the function signature + policies. Output: a description block + system
+guidance. This is a hard-won, little-known lesson baked into a generator.
+
+## 3. Hallucination regression harness
+A pytest-style harness: replay real or synthetic transcripts against guarded
+tools and assert **zero ungrounded commits** slipped through. Turns "we hope it
+doesn't fabricate" into a CI gate. Ships with a corpus format and fixtures.
+
+## 4. First-class framework adapters
+- **LiveKit** (priority — home turf): transcription events → `Transcript`,
+  auto `call_context` per session.
+- **Pipecat**, **Vapi**, **LangGraph** tool nodes.
+Keep each adapter thin; the core stays framework-neutral.
+
+## 5. Matcher precision/recall eval set
+A brutal labeled set of (transcript, value, expected verdict) — accents, ASR
+noise, spelled-out emails, partial confirmations. Publish precision/recall.
+**This is what determines whether anyone keeps the firewall on.** Build it
+before the launch tweet.
+
+## 6. Richer policies
+- `Policy.SPOKEN(type=...)` explicit type hints (date/phone/email/name).
+- `Policy.ONE_OF([...])` for enum-ish slots.
+- Composable policies (`SPOKEN | CONFIRMED`).
+- `email` normalization ("m as in mango, a, r, i, a, at gmail dot com").
+
+## 7. Provenance ledger as a product surface
+Exportable, signed attestation bundles ("authorized by these words at 00:42")
+for healthcare/finance/legal audit. The likely paid layer on top of the OSS
+core.
+
+## 8. Observability
+Per-call metrics: block rate, false-block feedback loop, latency budget, policy
+hit rates. A dashboard is downstream of this.

saidso-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 saidso contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

saidso-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: saidso
+Version: 0.1.0
+Summary: A grounding firewall for action-taking AI agents: refuse any tool argument the user never actually said, with a transcript-linked audit trail.
+Project-URL: Homepage, https://github.com/KarthikRommula/saidso
+Project-URL: Issues, https://github.com/KarthikRommula/saidso/issues
+Author: Karthik Rommula
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,audit,firewall,grounding,guardrails,hallucination,llm,provenance,tool-use,voice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: rapidfuzz>=3.0; extra == 'dev'
+Provides-Extra: fast
+Requires-Dist: rapidfuzz>=3.0; extra == 'fast'
+Description-Content-Type: text/markdown
+
+# saidso
+
+**A grounding firewall for action-taking AI agents.**
+
+`saidso` sits between an AI agent and its consequential tools (book, transfer,
+prescribe, refund, update a record) and **refuses to let the agent commit any
+argument that isn't grounded in what the user actually said** — with a
+transcript-linked audit trail for every action that does run.
+
+> The name is the whole idea: an action only goes through if the user *said so*.
+
+```python
+from saidso import grounded, Policy
+
+@grounded(
+    name=Policy.SPOKEN,      # must appear in the caller's speech
+    dob=Policy.SPOKEN,       # spoken naturally -> normalized to ISO
+    phone=Policy.CALLER_ID,  # comes from carrier metadata, not the mouth
+    visit_date=Policy.INFERABLE,  # "tomorrow" -> resolved from the clock
+)
+def register_patient(name, dob, phone, visit_date): ...
+```
+
+## The problem
+
+LLM voice/phone agents don't just talk — they *do things*. To do them, they
+call functions:
+
+```python
+register_patient(name="John Doe", dob="1990-01-01", ...)
+```
+
+Sometimes the model **fills in arguments the caller never said.** Today's
+frameworks (LiveKit, Vapi, Pipecat, LangGraph) execute the call anyway — and a
+fabricated name or date of birth lands in a real database.
+
+Prompting ("never make up a DOB") is best-effort. It's the *suspect judging
+itself*, it leaves no proof, and it silently degrades as you add tools.
+
+`saidso` is the backstop that runs in **code, not in the prompt**: it assumes
+the model *will* hallucinate and refuses to let the hallucination cause harm.
+
+## What it does, on every call
+
+1. **Block** — if an argument isn't grounded in the transcript, the function
+   body never runs.
+2. **Steer back** — instead of a dead error, it returns a structured message
+   that makes the agent *re-ask* the caller and try again, in-conversation.
+3. **Attest** — for every argument that does go through, it writes a receipt:
+   *this value came from these words, at this timestamp, with this confidence.*
+
+```text
+agent -> register_patient(name='John Doe', dob='1990-01-01')
+BLOCKED: body never ran.
+steer-back: "I don't have your name and your date of birth from what the
+             caller said. Ask the caller for your name and your date of
+             birth, then try again. Do not guess or fill in placeholder values."
+```
+
+## The policies
+
+| Policy | A value is grounded if… |
+|---|---|
+| `Policy.SPOKEN` | it appears in the caller's speech (digits/dates/names normalized, fuzzy-matched) |
+| `Policy.CONFIRMED` | the agent read it back **and** the caller affirmed it |
+| `Policy.CALLER_ID` | it matches trusted call metadata, not what was spoken |
+| `Policy.INFERABLE` | it's derivable from context ("tomorrow" + clock) or was spoken |
+
+## Install
+
+```bash
+pip install saidso          # zero required dependencies
+pip install saidso[fast]    # add rapidfuzz for faster matching
+```
+
+`saidso` works with no third-party packages (stdlib `difflib` fallback) and
+uses `rapidfuzz` automatically if it's installed.
+
+## Usage
+
+```python
+from saidso import grounded, Policy, Transcript, call_context, AttestationLog
+
+@grounded(name=Policy.SPOKEN, dob=Policy.SPOKEN)
+def register_patient(name, dob):
+    ...  # your real DB write
+
+# Feed the conversation as it happens:
+tr = Transcript()
+tr.add_user("Hi, I'd like to book an appointment.")
+
+log = AttestationLog(path="attestations.jsonl")  # optional audit trail
+
+with call_context(tr, ledger=log):
+    out = register_patient(name="John Doe", dob="1990-01-01")
+
+if getattr(out, "blocked", False):
+    say_to_caller(out.message)   # the agent re-asks; nothing was committed
+```
+
+When grounding passes, the body runs normally and an attestation is recorded.
+By default a block **returns** a `SteerBack` (so it slots straight into a
+tool-use loop); pass `GroundingConfig(raise_on_block=True)` to raise instead.
+
+### Plugging into your agent framework
+
+- **Raw OpenAI / Anthropic tool-use** — return `steer.to_tool_message()` as the
+  tool result so the model self-corrects. See
+  [`examples/openai_tooluse.py`](examples/openai_tooluse.py).
+- **LiveKit / Pipecat / Vapi** — keep a `Transcript` in sync with the
+  session's transcription events and open a `call_context`. See
+  [`examples/livekit_adapter.py`](examples/livekit_adapter.py).
+
+## Regression harness (CI gate)
+
+Assert that invented values are blocked and real ones commit — turn "we hope it
+doesn't fabricate" into a test:
+
+```python
+from saidso.testing import GroundingCase
+
+def test_invented_dob_is_blocked():
+    (GroundingCase(register_patient)
+        .user("Hi, I'd like an appointment")
+        .call(name="John Doe", dob="1990-01-01")
+        .assert_blocked("name", "dob"))
+
+def test_real_values_commit():
+    (GroundingCase(register_patient)
+        .user("It's Maria Gomez, born January first nineteen ninety")
+        .call(name="Maria Gomez", dob="1990-01-01")
+        .assert_grounded())
+```
+
+## Production behaviour
+
+- **Fail-closed.** If a grounding check ever raises, the argument is treated as
+  ungrounded (blocked) and the error is logged — a crash never opens the gate.
+- **Validated at import time.** A policy naming a non-existent parameter raises
+  immediately, so a typo can't silently leave a real argument unguarded.
+- **No silent over-matching.** Numbers must match as whole values (`"2"` is not
+  grounded by `"20"`); short names require exact word matches; `date`, `int`,
+  `float`, `bool` arguments are coerced deterministically.
+- **Observability.** Blocks and errors log under the `saidso` logger.
+
+Tune thresholds or switch to raising via `GroundingConfig`:
+
+```python
+from saidso import GroundingConfig, Policy
+cfg = GroundingConfig(thresholds={Policy.SPOKEN: 0.9}, raise_on_block=True)
+
+@grounded(cfg, name=Policy.SPOKEN)
+def book(name): ...
+```
+
+## Run the demo
+
+```bash
+python examples/john_doe_demo.py
+```
+
+## Roadmap
+
+The MVP is deterministic-first and intentionally small. Planned next:
+verifier-model escalation for ambiguous cases, the **anti-priming prompt
+compiler**, the **hallucination regression harness** (pytest-style CI gate),
+and first-class framework adapters. See [`Docs/ROADMAP.md`](Docs/ROADMAP.md).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

saidso-0.1.0/README.md

@@ -0,0 +1,178 @@
+# saidso
+
+**A grounding firewall for action-taking AI agents.**
+
+`saidso` sits between an AI agent and its consequential tools (book, transfer,
+prescribe, refund, update a record) and **refuses to let the agent commit any
+argument that isn't grounded in what the user actually said** — with a
+transcript-linked audit trail for every action that does run.
+
+> The name is the whole idea: an action only goes through if the user *said so*.
+
+```python
+from saidso import grounded, Policy
+
+@grounded(
+    name=Policy.SPOKEN,      # must appear in the caller's speech
+    dob=Policy.SPOKEN,       # spoken naturally -> normalized to ISO
+    phone=Policy.CALLER_ID,  # comes from carrier metadata, not the mouth
+    visit_date=Policy.INFERABLE,  # "tomorrow" -> resolved from the clock
+)
+def register_patient(name, dob, phone, visit_date): ...
+```
+
+## The problem
+
+LLM voice/phone agents don't just talk — they *do things*. To do them, they
+call functions:
+
+```python
+register_patient(name="John Doe", dob="1990-01-01", ...)
+```
+
+Sometimes the model **fills in arguments the caller never said.** Today's
+frameworks (LiveKit, Vapi, Pipecat, LangGraph) execute the call anyway — and a
+fabricated name or date of birth lands in a real database.
+
+Prompting ("never make up a DOB") is best-effort. It's the *suspect judging
+itself*, it leaves no proof, and it silently degrades as you add tools.
+
+`saidso` is the backstop that runs in **code, not in the prompt**: it assumes
+the model *will* hallucinate and refuses to let the hallucination cause harm.
+
+## What it does, on every call
+
+1. **Block** — if an argument isn't grounded in the transcript, the function
+   body never runs.
+2. **Steer back** — instead of a dead error, it returns a structured message
+   that makes the agent *re-ask* the caller and try again, in-conversation.
+3. **Attest** — for every argument that does go through, it writes a receipt:
+   *this value came from these words, at this timestamp, with this confidence.*
+
+```text
+agent -> register_patient(name='John Doe', dob='1990-01-01')
+BLOCKED: body never ran.
+steer-back: "I don't have your name and your date of birth from what the
+             caller said. Ask the caller for your name and your date of
+             birth, then try again. Do not guess or fill in placeholder values."
+```
+
+## The policies
+
+| Policy | A value is grounded if… |
+|---|---|
+| `Policy.SPOKEN` | it appears in the caller's speech (digits/dates/names normalized, fuzzy-matched) |
+| `Policy.CONFIRMED` | the agent read it back **and** the caller affirmed it |
+| `Policy.CALLER_ID` | it matches trusted call metadata, not what was spoken |
+| `Policy.INFERABLE` | it's derivable from context ("tomorrow" + clock) or was spoken |
+
+## Install
+
+```bash
+pip install saidso          # zero required dependencies
+pip install saidso[fast]    # add rapidfuzz for faster matching
+```
+
+`saidso` works with no third-party packages (stdlib `difflib` fallback) and
+uses `rapidfuzz` automatically if it's installed.
+
+## Usage
+
+```python
+from saidso import grounded, Policy, Transcript, call_context, AttestationLog
+
+@grounded(name=Policy.SPOKEN, dob=Policy.SPOKEN)
+def register_patient(name, dob):
+    ...  # your real DB write
+
+# Feed the conversation as it happens:
+tr = Transcript()
+tr.add_user("Hi, I'd like to book an appointment.")
+
+log = AttestationLog(path="attestations.jsonl")  # optional audit trail
+
+with call_context(tr, ledger=log):
+    out = register_patient(name="John Doe", dob="1990-01-01")
+
+if getattr(out, "blocked", False):
+    say_to_caller(out.message)   # the agent re-asks; nothing was committed
+```
+
+When grounding passes, the body runs normally and an attestation is recorded.
+By default a block **returns** a `SteerBack` (so it slots straight into a
+tool-use loop); pass `GroundingConfig(raise_on_block=True)` to raise instead.
+
+### Plugging into your agent framework
+
+- **Raw OpenAI / Anthropic tool-use** — return `steer.to_tool_message()` as the
+  tool result so the model self-corrects. See
+  [`examples/openai_tooluse.py`](examples/openai_tooluse.py).
+- **LiveKit / Pipecat / Vapi** — keep a `Transcript` in sync with the
+  session's transcription events and open a `call_context`. See
+  [`examples/livekit_adapter.py`](examples/livekit_adapter.py).
+
+## Regression harness (CI gate)
+
+Assert that invented values are blocked and real ones commit — turn "we hope it
+doesn't fabricate" into a test:
+
+```python
+from saidso.testing import GroundingCase
+
+def test_invented_dob_is_blocked():
+    (GroundingCase(register_patient)
+        .user("Hi, I'd like an appointment")
+        .call(name="John Doe", dob="1990-01-01")
+        .assert_blocked("name", "dob"))
+
+def test_real_values_commit():
+    (GroundingCase(register_patient)
+        .user("It's Maria Gomez, born January first nineteen ninety")
+        .call(name="Maria Gomez", dob="1990-01-01")
+        .assert_grounded())
+```
+
+## Production behaviour
+
+- **Fail-closed.** If a grounding check ever raises, the argument is treated as
+  ungrounded (blocked) and the error is logged — a crash never opens the gate.
+- **Validated at import time.** A policy naming a non-existent parameter raises
+  immediately, so a typo can't silently leave a real argument unguarded.
+- **No silent over-matching.** Numbers must match as whole values (`"2"` is not
+  grounded by `"20"`); short names require exact word matches; `date`, `int`,
+  `float`, `bool` arguments are coerced deterministically.
+- **Observability.** Blocks and errors log under the `saidso` logger.
+
+Tune thresholds or switch to raising via `GroundingConfig`:
+
+```python
+from saidso import GroundingConfig, Policy
+cfg = GroundingConfig(thresholds={Policy.SPOKEN: 0.9}, raise_on_block=True)
+
+@grounded(cfg, name=Policy.SPOKEN)
+def book(name): ...
+```
+
+## Run the demo
+
+```bash
+python examples/john_doe_demo.py
+```
+
+## Roadmap
+
+The MVP is deterministic-first and intentionally small. Planned next:
+verifier-model escalation for ambiguous cases, the **anti-priming prompt
+compiler**, the **hallucination regression harness** (pytest-style CI gate),
+and first-class framework adapters. See [`Docs/ROADMAP.md`](Docs/ROADMAP.md).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

saidso-0.1.0/examples/john_doe_demo.py

@@ -0,0 +1,80 @@
+"""The John Doe demo: a naked agent invents a patient; saidso blocks it.
+
+Run::
+
+    python examples/john_doe_demo.py
+
+No API keys, no network. This is the 30-second story the project exists for.
+"""
+
+from __future__ import annotations
+
+from saidso import AttestationLog, Policy, SteerBack, Transcript, call_context, grounded
+
+# A real action that would touch a database / EHR in production.
+DB = []
+
+
+@grounded(name=Policy.SPOKEN, dob=Policy.SPOKEN)
+def register_patient(name, dob):
+    DB.append({"name": name, "dob": dob})
+    return {"committed": True, "name": name, "dob": dob}
+
+
+def banner(title):
+    print("\n" + "=" * 64)
+    print(title)
+    print("=" * 64)
+
+
+def scenario_naked_agent():
+    banner("LEFT — naked agent (no firewall)")
+    tr = Transcript()
+    tr.add_user("Hi, I'd like to book an appointment for next week.")
+    print("caller: \"Hi, I'd like to book an appointment for next week.\"")
+    # The model hallucinates a name + DOB the caller never gave.
+    name, dob = "John Doe", "1990-01-01"
+    DB.append({"name": name, "dob": dob})  # straight to the DB
+    print(f"agent  -> register_patient(name={name!r}, dob={dob!r})")
+    print(f"RESULT : committed fabricated record. DB now: {DB[-1]}")
+
+
+def scenario_firewalled():
+    DB.clear()
+    banner("RIGHT — same agent, behind saidso")
+    tr = Transcript()
+    tr.add_user("Hi, I'd like to book an appointment for next week.")
+    print("caller: \"Hi, I'd like to book an appointment for next week.\"")
+
+    with call_context(tr):
+        out = register_patient(name="John Doe", dob="1990-01-01")
+    assert isinstance(out, SteerBack)
+    print("agent  -> register_patient(name='John Doe', dob='1990-01-01')")
+    print("BLOCKED: body never ran. DB is still", DB)
+    print(f"steer-back to agent: \"{out.message}\"")
+
+    # The agent re-asks; the caller answers; now it's grounded.
+    print("\n-- agent re-asks, caller answers --")
+    tr.add_agent("I didn't catch your name and date of birth — could you tell me?")
+    tr.add_user("Sure, it's Maria Gomez, born January first, nineteen ninety.")
+    print("caller: \"Sure, it's Maria Gomez, born January first, nineteen ninety.\"")
+
+    log = AttestationLog()
+    with call_context(tr, ledger=log, call_id="call-42"):
+        out = register_patient(name="Maria Gomez", dob="1990-01-01")
+    print(f"agent  -> register_patient(name='Maria Gomez', dob='1990-01-01')")
+    print(f"COMMITTED: {out}")
+    print("\nprovenance receipt:")
+    for arg in log.records[0].to_dict()["args"]:
+        span = arg["span"]
+        print(
+            f"  - {arg['arg']}={arg['value']!r} via {arg['policy']} "
+            f"(conf {arg['confidence']}) grounded by turn #{span['turn_id']}: "
+            f"\"{span['text']}\""
+        )
+
+
+if __name__ == "__main__":
+    scenario_naked_agent()
+    scenario_firewalled()
+    print()