@archrad/deterministic 0.1.0

package/scripts/GIF_RECORDING_STEP_BY_STEP.md

@@ -0,0 +1,125 @@
+# Step-by-step: record `demo-validate.gif` (and use a branch, not `main`)
+
+Use this when regenerating the **npm README** hero GIF (**failure-first** validate: `demo-direct-db-violation` → `demo-direct-db-layered`). For install troubleshooting, see **[README_DEMO_RECORDING.md](./README_DEMO_RECORDING.md)**.
+
+---
+
+## Part A — Git: work on a branch
+
+Do **not** commit the new GIF (or tape tweaks) straight to `main` until reviewed.
+
+1. **Update local `main`** (from repo root `InkByte`):
+
+   ```bash
+   git fetch origin
+   git checkout main
+   git pull origin main
+   ```
+
+2. **Create a branch** (pick a name that matches your convention):
+
+   ```bash
+   git checkout -b chore/record-demo-validate-gif
+   ```
+
+3. **Do all recording, edits, and commits on this branch** (see Part C–D).
+
+4. **Open a PR** into `main` when the GIF looks right and file size is acceptable (~3–5 MB for npm).
+
+---
+
+## Part B — One-time prerequisites
+
+- **Node.js ≥ 20** (`node -v`).
+- **This monorepo** cloned; you will run commands from **`packages/deterministic`**.
+- **VHS** + **ffmpeg** + **ttyd** on your `PATH` (VHS drives a headless terminal). On Windows, **Git Bash** (or WSL) is easiest because the tape uses **`Set Shell "bash"`**.
+
+Install hints (Windows):
+
+- `winget install charmbracelet.vhs`
+- `winget install Gyan.FFmpeg`
+- `winget install -e --id tsl0922.ttyd` (or Scoop: `scoop install ttyd`)
+
+Verify:
+
+```bash
+vhs --version
+ffmpeg -version
+ttyd --version
+```
+
+---
+
+## Part C — Build CLI, then record
+
+All steps from **`packages/deterministic`**:
+
+1. **Install deps** (if you have not already):
+
+   ```bash
+   cd packages/deterministic
+   npm ci
+   ```
+
+2. **Compile TypeScript** (the tape runs **`node dist/cli.js`**):
+
+   ```bash
+   npm run build
+   ```
+
+3. **Record the GIF** (must be **bash** — run Git Bash here if you are on Windows):
+
+   ```bash
+   vhs scripts/record-demo-validate.tape
+   ```
+
+   This writes **`demo-validate.gif`** next to **`package.json`** (`packages/deterministic/demo-validate.gif`).
+
+4. **If output is too fast or slow**, edit **`scripts/record-demo-validate.tape`** **`Sleep`** durations (e.g. after each `Enter`), then run **`vhs`** again.
+
+---
+
+## Part D — Check, commit on your branch, PR
+
+1. **Open the GIF** locally and confirm:
+   - First run shows **`IR-LINT-DIRECT-DB-ACCESS-002`** (and **`NO-HEALTHCHECK`**) on stderr.
+   - Second run ends with the **clean** success lines (no lint block).
+   - File size is reasonable for npm (~**< 3–5 MB** if possible).
+
+2. **Stage and commit** (still on your feature branch):
+
+   ```bash
+   git add packages/deterministic/demo-validate.gif
+   # include any tape/README changes you made
+   git status
+   git commit -m "chore(deterministic): regenerate demo-validate.gif (failure-first IR gate)"
+   ```
+
+3. **Push the branch** and open a **PR to `main`**:
+
+   ```bash
+   git push -u origin chore/record-demo-validate-gif
+   ```
+
+4. After merge, **`package.json` → `files`** already includes **`demo-validate.gif`** so it ships in the **npm** tarball.
+
+---
+
+## Optional GIFs (same package, same branch if you like)
+
+| Tape | Output |
+|------|--------|
+| **`scripts/record-demo.tape`** | **`demo.gif`** (minimal export + file list) |
+| **`scripts/record-demo-payment-retry.tape`** | **`demo-payment-retry.gif`** |
+| **`scripts/record-demo-drift.tape`** | **`demo-drift.gif`** (**`validate-drift`** trust tape) |
+| **`scripts/record-demo-validate.tape`** | **`demo-validate.gif`** (README hero) |
+
+---
+
+## Quick reference — what the tape runs
+
+1. `node dist/cli.js validate -i fixtures/demo-direct-db-violation.json`
+2. Comment + `node dist/cli.js validate -i fixtures/demo-direct-db-layered.json`
+3. Short comment about **`--fail-on-warning`** / **`--json`**
+
+Fixtures live under **`packages/deterministic/fixtures/`**.

package/scripts/README_DEMO_RECORDING.md

@@ -0,0 +1,314 @@
+# Recording the **npm README** demo GIF
+
+**Scope:** the README for **`@archrad/deterministic`** on **npmjs.com** (package root **`README.md`**).  
+**Storyboard:** [DEMO_GIF_STORYBOARD.md](./DEMO_GIF_STORYBOARD.md) — one recommended hero GIF.  
+**Step-by-step (Git branch + VHS + commit):** [GIF_RECORDING_STEP_BY_STEP.md](./GIF_RECORDING_STEP_BY_STEP.md).
+
+## Recommended: `demo-validate.gif`
+
+**Story:** **failure first** — **`fixtures/demo-direct-db-violation.json`** → **`IR-LINT-DIRECT-DB-ACCESS-002`** (and **NO-HEALTHCHECK**) → layered **`fixtures/demo-direct-db-layered.json`** → **clean** validate. **No `export`** in the tape. **IR-LINT** lines use **ANSI red** when **stderr is a TTY** (unset **`NO_COLOR`**); VHS/ttyd counts as a TTY.
+
+From **`packages/deterministic`**. The **`.tape`** files expect **bash** (Git Bash, WSL, or macOS/Linux). On **PowerShell alone**, `vhs` is not installed until you add it to `PATH` (see below).
+
+### When VHS fails
+
+VHS shells out to **`ttyd`** + **`ffmpeg`**; installs differ, and some environments block or hang headless terminals.
+
+| Symptom | Things to try |
+|--------|----------------|
+| **`echo`: executable file not found** | VHS **`Require echo`** checks a real `echo` binary. Our **`record-demo-drift.tape`** omits it; for other tapes, delete the **`Require echo`** line or run VHS from **Git Bash** where **`echo`** exists. |
+| **`ttyd` / `ffmpeg` not found** | Install both, **restart the terminal**, confirm **`ttyd --version`** and **`ffmpeg -version`**. |
+| **Black screen, hang, or instant failure** | Update VHS; run from **Git Bash**; try WSL2; temporarily reduce **`Set Width` / `Set Height`** in the `.tape`. |
+| **You want to skip VHS entirely** | Use the **same command sequence** as the tape while screen-recording (see below). |
+
+**Drift GIF without VHS:** from **`packages/deterministic`**, start **ShareX** (GIF) / **OBS** / **ScreenToGif**, then run one of:
+
+```bash
+# Git Bash / WSL / macOS / Linux
+bash scripts/run-demo-drift-sequence.sh
+# Optional slower pacing: DEMO_DRIFT_PAUSE=4 bash scripts/run-demo-drift-sequence.sh
+```
+
+```powershell
+# Windows PowerShell (from packages/deterministic)
+powershell -ExecutionPolicy Bypass -File scripts/run-demo-drift-sequence.ps1
+```
+
+Trim the recording and export to GIF (ShareX can save directly to GIF; otherwise **`ffmpeg`** as in [Manual recording (no VHS)](#manual-recording-no-vhs) below). The **`.tape`** file remains the spec; the scripts are the **portable replay** for capture tools.
+
+**asciinema** (terminal cast, then GIF with **[agg](https://github.com/asciinema/agg)**): `asciinema rec demo.cast`, run the same commands (or `bash scripts/run-demo-drift-sequence.sh` inside the session), then `agg demo.cast demo-drift.gif`.
+
+### Install VHS on Windows
+
+[VHS](https://github.com/charmbracelet/vhs) needs **`ffmpeg`** and **`ttyd`** on your `PATH`.
+
+- **`ffmpeg is not installed`** → install ffmpeg (e.g. `winget install Gyan.FFmpeg`), restart terminal, `ffmpeg -version`.
+- **`ttyd is not installed`** → `winget install -e --id tsl0922.ttyd` or `scoop install ttyd`, restart terminal, `ttyd --version`.
+
+Typical paths:
+
+1. **winget** (run in **elevated** PowerShell if prompted):
+   ```powershell
+   winget install charmbracelet.vhs
+   winget install Gyan.FFmpeg
+   winget install -e --id tsl0922.ttyd
+   ```
+   If **winget** has no **ttyd** package on your machine, use [ttyd releases](https://github.com/tsl0922/ttyd/releases) or **Scoop**: `scoop install ttyd`.
+
+2. **Scoop** (user install):
+   ```powershell
+   scoop install vhs ffmpeg ttyd
+   ```
+
+3. **Go** (puts `vhs.exe` in `%USERPROFILE%\go\bin` — add that folder to PATH):
+   ```powershell
+   go install github.com/charmbracelet/vhs@latest
+   ```
+
+Close and reopen the terminal, then:
+
+```bash
+npm run build
+vhs scripts/record-demo-validate.tape
+```
+
+If `vhs` still says “not recognized”, run `where.exe vhs` or use the full path to `vhs.exe`. Easiest path on Windows is often **Git Bash** after install, since the tape uses `Set Shell "bash"`.
+
+Writes **`demo-validate.gif`** next to **`package.json`**. Add to **`README.md`** (below the title block):
+
+```markdown
+![archrad validate — IR-LINT-DIRECT-DB-ACCESS-002 first, fix on the graph, clean gate](demo-validate.gif)
+```
+
+**`package.json` → `files`** already lists **`demo-validate.gif`** so it ships in the **npm tarball** once the file exists (commit the GIF or generate before publish).
+
+Tweak **`Sleep`** in **`record-demo-validate.tape`** if the output scrolls too fast or slow. Target **< ~3–5 MB** for npm/GitHub.
+
+## Optional second GIF (`demo.gif`)
+
+Export + listing generated files (no Docker in tape):
+
+```bash
+vhs scripts/record-demo.tape
+```
+
+Use only if you need a second motion graphic; prefer **one** GIF on npm.
+
+## Phase A — payment + retry → FastAPI (`demo-payment-retry.gif`)
+
+Golden fixture **`fixtures/payment-retry-demo.json`**, validate + export + **`grep`** on **`app/main.py`** for **`maxAttempts`**. Storyboard: **`DEMO_GIF_STORYBOARD.md`** (Phase A). From **`packages/deterministic`** (bash):
+
+```bash
+npm run build
+vhs scripts/record-demo-payment-retry.tape
+```
+
+Writes **`demo-payment-retry.gif`** next to **`package.json`**. Not included in the default npm README hero slot unless you choose to ship it (watch tarball size).
+
+## Deterministic drift (`demo-drift.gif`)
+
+**`validate-drift`** after a deliberate edit to **`./out/app/main.py`** — see **`DEMO_GIF_STORYBOARD.md`**.
+
+**Automated (VHS):** from **`packages/deterministic`**:
+
+```bash
+npm run record:demo:drift
+```
+
+**Manual capture (no VHS):** **`scripts/run-demo-drift-sequence.sh`** or **`scripts/run-demo-drift-sequence.ps1`** — see [When VHS fails](#when-vhs-fails) above.
+
+Writes **`demo-drift.gif`** next to **`package.json`** when you export from your recorder. **`package.json` → `files`** includes **`demo-drift.gif`** when you publish.
+
+---
+
+## Trust loop drift (IDE + terminal)
+
+For **skeptic-grade** drift marketing, show **edit → save → drift**, *and* bookend with **green** **`validate-drift`** before and after so it is not “only a failure.” Storyboard: **[DEMO_GIF_STORYBOARD.md](./DEMO_GIF_STORYBOARD.md)** (**Trust loop**). Tools: **ShareX**, **ScreenStudio**, **OBS**.
+
+### Complete GIF — step by step (baseline OK → break → fail → fix → OK again)
+
+Use **`packages/deterministic`**. Replace **`C:\scm\InkByte`** with your path.
+
+**Drift check — pick one (avoids “Invoke-DriftCheck not recognized”):**
+
+1. **Script (works in every new terminal)** — from **`packages/deterministic`**:
+
+   ```powershell
+   .\scripts\invoke-drift-check.ps1
+   ```
+
+2. **One-liner (paste anytime, same folder):**
+
+   ```powershell
+   node dist/cli.js validate-drift -i fixtures/payment-retry-demo.json -t python -o ./out --skip-host-port-check --skip-ir-lint
+   ```
+
+3. **Function (only in the same PowerShell session where you defined it):** if you use **`Invoke-DriftCheck`**, you must paste the **`function Invoke-DriftCheck { ... }`** block **in that same window** before calling it; **new tabs** do not keep the function.
+
+**Before you record — rehearsal (optional):** run steps 1–4 once without ShareX so timings feel natural.
+
+---
+
+**Step 1 — Install / configure capture**  
+- **ShareX:** **Task settings → Capture → Screen recording → GIF**; assign **record region** hotkey.  
+- Or **OBS** / **Game Bar** → MP4 → **`ffmpeg`** (see [Manual recording](#manual-recording-no-vhs)).
+
+**Step 2 — Layout**  
+IDE (**VS Code** / **Cursor**) + **Windows Terminal** (PowerShell) visible together (**split screen** = one ShareX region covers both).
+
+**Pasting commands (read this)**  
+If you copy several lines and they end up **on one line** (e.g. `...deterministicnpm run build...` or `SilentlyContinuenode dist...`), PowerShell breaks and you may see **`Set-Location : Parameter name 'i' is ambiguous`** — the shell is no longer running **`node dist/cli.js export -i ...`** as intended. **Fix:** press **Enter after each line**, or paste the **single-line** version below (semicolons separate statements).
+
+**Step 3 — Prep export (off-camera or start of clip)**  
+
+Run **one line at a time**, or use this **paste-safe one-liner** (change the path if needed):
+
+```powershell
+Set-Location C:\scm\InkByte\packages\deterministic; npm run build; if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }; Remove-Item -Recurse -Force .\out -ErrorAction SilentlyContinue; node dist/cli.js export -i fixtures/payment-retry-demo.json -t python -o ./out --skip-host-port-check --skip-ir-lint
+```
+
+Multi-line (only if each line executes separately):
+
+```powershell
+Set-Location C:\scm\InkByte\packages\deterministic
+npm run build
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+Remove-Item -Recurse -Force .\out -ErrorAction SilentlyContinue
+node dist/cli.js export -i fixtures/payment-retry-demo.json -t python -o ./out --skip-host-port-check --skip-ir-lint
+```
+
+**Step 4 — Find the line you will edit (rehearsal)**  
+
+```powershell
+Select-String -Path .\out\app\main.py -Pattern "maxAttempts|max_attempts|retry" | Select-Object -First 10 LineNumber, Line
+```
+
+Pick one line (e.g. **`max_attempts`** / retry **`3`** → you will temporarily change to **`1`**).
+
+**Step 5 — Start recording**  
+ShareX **region** around IDE + terminal (or full screen for quick-cut editing later).
+
+**Step 6 — Act A: export success (terminal)**  
+If you did not show export in step 3 on camera, run the **`export`** block from step 3 now. Pause ~2s on **`archrad: wrote … files`** / success text.
+
+**Step 7 — Act B: baseline drift check = success**  
+
+```powershell
+.\scripts\invoke-drift-check.ps1
+```
+
+(or the **one-liner** under *Drift check — pick one* above.)
+
+**Expect:** exit code **0** and a line like **`no deterministic drift`**. This proves the tool **passes** when disk matches IR. Hold ~2–3s on screen.
+
+**Step 8 — Act C: open editor**  
+
+```powershell
+code .\out\app\main.py
+```
+
+(or open the file manually). Scroll so the target line is visible.
+
+**Step 9 — Act D: the edit + save**  
+Change the value (e.g. **`3` → `1`**) or another obvious edit on that line → **Ctrl+S**. Pause ~1s.
+
+**Step 10 — Act E: drift check = failure**  
+
+```powershell
+.\scripts\invoke-drift-check.ps1
+```
+
+**Expect:** **`DRIFT-MODIFIED`** / **`app/main.py`**, non-zero exit. Hold ~3s so viewers read it.
+
+**Step 11 — Act F: fix (pick one)**
+
+- **F1 — Undo in editor (best for “same tree” story):** **Ctrl+Z** until the line matches the export again → **Ctrl+S**.  
+- **F2 — Re-export (regenerate story):** in terminal (one line, paste-safe):
+
+```powershell
+Remove-Item -Recurse -Force .\out -ErrorAction SilentlyContinue; node dist/cli.js export -i fixtures/payment-retry-demo.json -t python -o ./out --skip-host-port-check --skip-ir-lint
+```
+
+If you used **F2**, optionally show **IDE** refreshing **`main.py`** (reload from disk) so the number is **3** again.
+
+**Step 12 — Act G: drift check = success again**  
+
+```powershell
+.\scripts\invoke-drift-check.ps1
+```
+
+**Expect:** exit **0**, **`no deterministic drift`** again. Hold ~2–3s — this is the **success case** that closes the loop.
+
+**Step 13 — Stop recording**  
+Trim dead air at start/end; if the GIF is huge, lower fps or shorten pauses in ShareX/ffmpeg. Save as **`demo-drift-trust-loop-full.gif`** (or your name).
+
+**Step 14 — Sanity check**  
+Watch once: **green → edit → red → fix → green**. If **red** never appears, the edit did not change bytes the export cares about; pick another line or use **`echo '# x' >> .\out\app\main.py`** only for the break (less “architectural” but still valid **DRIFT-MODIFIED**).
+
+---
+
+**Notes:** Substitute **`archrad`** for **`node dist/cli.js`** if the CLI is on **`PATH`**. Do not set **`NO_COLOR`** if you want red stderr. Terminal-only variant (no IDE): run **step 3**, then **7**, append a line with **`Add-Content`**, **10**, delete **`out`** and **export** again, **12** — still a full arc, weaker causality; see **`scripts/run-demo-drift-sequence.ps1`** for a partial terminal-only path (extend locally with a final **`validate-drift`** after you revert).
+
+## Manual recording (no VHS)
+
+Works in **PowerShell** — no `vhs` required. Run the command, then capture the terminal:
+
+| Tool | Notes |
+|------|--------|
+| **ShareX** (free) | [getsharex.com](https://getsharex.com/) — can record **directly to GIF**. |
+| **Xbox Game Bar** | `Win+G` → record → **MP4**; convert with **ffmpeg** (see below). |
+| **Snipping Tool** (Win11) | **Record** if available → video → ffmpeg → GIF. |
+| **ScreenToGif** | Optional; not required. |
+
+**MP4 → GIF** (after Game Bar / OBS; requires **ffmpeg** on PATH):
+
+```powershell
+ffmpeg -i recording.mp4 -vf "fps=10,scale=800:-1:flags=lanczos" -loop 0 demo-validate.gif
+```
+
+**PowerShell:**
+
+```powershell
+cd C:\path\to\packages\deterministic
+npm run build
+node dist/cli.js validate -i fixtures/demo-direct-db-violation.json
+node dist/cli.js validate -i fixtures/demo-direct-db-layered.json
+```
+
+**Bash / Git Bash:**
+
+```bash
+npm run build
+node dist/cli.js validate -i fixtures/demo-direct-db-violation.json
+node dist/cli.js validate -i fixtures/demo-direct-db-layered.json
+```
+
+---
+
+## Full golden path (not for npm README hero)
+
+**`archrad export`** → **`make run`** → **`curl`** → **422** on **`/signup`** — good for docs or video; Docker makes README GIFs long. Commands:
+
+```bash
+npm run build
+node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out ./out
+cd ./out && make run
+```
+
+```bash
+curl -sS -w "\nHTTP %{http_code}\n" -X POST http://localhost:8080/signup \
+  -H "Content-Type: application/json" -d '{}'
+```
+
+Or **`bash scripts/golden-path-demo.sh`** / **`pwsh -File scripts/golden-path-demo.ps1`** for export + reminders.
+
+## Other tools
+
+| Tool | Notes |
+|------|-------|
+| **[VHS](https://github.com/charmbracelet/vhs)** | `.tape` → GIF; **`record-demo-validate.tape`**, **`record-demo.tape`**. |
+| **[asciinema](https://asciinema.org/)** + **[agg](https://github.com/asciinema/agg)** | Terminal → GIF. |
+
+## CI / repo size
+
+Avoid multi‑MB GIFs without **Git LFS** if your policy requires it; npm and GitHub READMEs are usually fine under a few MB.

package/scripts/SOCIAL_POST_DRIFT_AND_INGESTION.md

@@ -0,0 +1,17 @@
+# Draft reply: drift + “where does the IR come from?”
+
+Use as a Reddit (or similar) follow-up after the drift thread. Trim voice to match your account.
+
+---
+
+**On drift:** The enforcement story is not “hope people read the docs.” It’s **gate the blueprint artifact**. You run **`archrad validate`** on the **IR** in CI (or pre-commit): the linter fires on the graph — e.g. **`IR-LINT-DIRECT-DB-ACCESS-002`** when an HTTP node talks straight to a datastore — **before** you generate or ship code. The fix is **an edit to the IR** (introduce a service layer, health route, etc.), then the gate passes. Same loop you’d want for any contract-first workflow: **blueprint in → violation found → fix on the graph → gate passes**. No generated-code diff required for that 30-second story.
+
+**On “where does the IR come from?”** Fair question for any real team. Today the honest answer is **multiple on-ramps**: hand-authored JSON/YAML graph, **`archrad yaml-to-ir`**, and **`archrad ingest openapi`** (OpenAPI 3.x → HTTP-shaped IR — structural surface, not full system semantics). **That ingestion path is the part we’re actively building out** (OpenAPI, and toward **IaC / other specs** as inputs), with **manual IR** as the **starting point**, not the end state. Stating that clearly tends to turn “but where does IR come from?” into **someone following the journey** instead of **blocking on a strawman permanent end state**.
+
+---
+
+Optional one-liner for the post body: *IR from OpenAPI ingest + YAML graph today; more ingestion sources in progress — validate runs on whatever lands in the repo as the blueprint.*
+
+---
+
+**Internal / roadmap:** OSS **`archrad validate-drift`** and Cloud **`POST /api/v1/deterministic/drift-check`** are the **thin** deterministic drift checks; dashboard KPI + **SYNC** remain roadmap — **`docs/PHASE_B_C_DRIFT_AND_OSS_REGEN.md`**.

package/scripts/golden-path-demo.ps1

@@ -0,0 +1,25 @@
+# Golden-path demo commands (README / GIF). Run from packages/deterministic.
+param([string] $OutDir = "golden-path-out")
+
+$ErrorActionPreference = "Stop"
+$Root = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path
+Set-Location $Root
+
+Write-Host ">>> npm run build"
+npm run build
+
+$out = Join-Path $Root $OutDir
+if (Test-Path $out) { Remove-Item -Recurse -Force $out }
+
+Write-Host ">>> archrad export -> $OutDir"
+node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out $out
+
+Write-Host ""
+Write-Host "=== Next (terminal 1) ==="
+Write-Host "  cd $out"
+Write-Host "  make run"
+Write-Host ""
+Write-Host "=== Next (terminal 2) ==="
+Write-Host "  curl -sS -X POST http://localhost:8080/signup -H `"Content-Type: application/json`" -d '{}'"
+Write-Host ""
+Write-Host "Expect HTTP 422 or 400 with a structured error body."

package/scripts/golden-path-demo.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Commands for a ~60s golden-path demo (and README / HN GIF recording).
+# Run from packages/deterministic after: npm run build
+
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+OUT="${1:-./golden-path-out}"
+echo ">>> npm run build"
+npm run build
+echo ">>> rm -rf $OUT && archrad export"
+rm -rf "$OUT"
+node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out "$OUT"
+
+echo ""
+echo "=== Next (terminal 1) — start the stack ==="
+echo "  cd $(pwd)/$OUT && make run"
+echo ""
+echo "=== Next (terminal 2) — validation smoke ==="
+echo "  curl -sS -X POST http://localhost:8080/signup -H 'Content-Type: application/json' -d '{}'"
+echo ""
+echo "Expect HTTP 422 or 400 with a structured error body (not 500)."

package/scripts/invoke-drift-check.ps1

@@ -0,0 +1,16 @@
+# Payment-retry fixture drift check (same flags as trust-loop docs).
+# From packages/deterministic:
+#   .\scripts\invoke-drift-check.ps1
+# Or from anywhere:
+#   powershell -ExecutionPolicy Bypass -File path\to\packages\deterministic\scripts\invoke-drift-check.ps1
+
+$ErrorActionPreference = "Stop"
+$pkgRoot = Resolve-Path (Join-Path $PSScriptRoot "..")
+Set-Location $pkgRoot
+
+& node dist/cli.js validate-drift `
+  -i fixtures/payment-retry-demo.json `
+  -t python -o ./out `
+  --skip-host-port-check --skip-ir-lint
+
+exit $LASTEXITCODE

package/scripts/record-demo-drift.tape

@@ -0,0 +1,50 @@
+# OSS trust tape: export → tamper generated file → validate-drift catches DRIFT-MODIFIED.
+# Same CLI as global `archrad` when linked; tape uses `node dist/cli.js` for clone-local reproducibility.
+# Prereq: bash (Git Bash / WSL). From packages/deterministic:
+#   npm run record:demo:drift
+# or: npm run build && vhs scripts/record-demo-drift.tape
+# If VHS/ttyd fails on your machine: run scripts/run-demo-drift-sequence.sh (Git Bash) or
+#   scripts/run-demo-drift-sequence.ps1 while capturing the terminal (ShareX, OBS, etc.) — see README_DEMO_RECORDING.md
+
+Output demo-drift.gif
+
+Set Shell "bash"
+Set FontSize 16
+Set Width 1200
+Set Height 720
+Set Padding 20
+Set Theme "Catppuccin Mocha"
+
+Hide
+Type "clear" Enter
+Type "rm -rf ./out" Enter
+Show
+
+Sleep 400ms
+Type "# Deterministic drift: on-disk export vs fresh export from the same IR" Sleep 120ms Enter
+Sleep 350ms
+Type "npm run build && node dist/cli.js export -i fixtures/payment-retry-demo.json -t python -o ./out --skip-host-port-check --skip-ir-lint" Sleep 100ms Enter
+Sleep 500ms
+Sleep 4s
+
+Type "# out/app/main.py — tail before tamper (generated, matches IR)" Sleep 120ms Enter
+Sleep 300ms
+Type "tail -n 10 ./out/app/main.py" Sleep 100ms Enter
+Sleep 3s
+
+Type "# Tamper: append one line (IR file on disk is unchanged)" Sleep 120ms Enter
+Sleep 400ms
+Type "echo '# Drift introduced' >> ./out/app/main.py" Sleep 100ms Enter
+Sleep 2s
+
+Type "# Same file — tail after (extra line is the only change)" Sleep 120ms Enter
+Sleep 300ms
+Type "tail -n 12 ./out/app/main.py" Sleep 100ms Enter
+Sleep 3s
+
+Type "node dist/cli.js validate-drift -i fixtures/payment-retry-demo.json -t python -o ./out --skip-host-port-check --skip-ir-lint" Sleep 100ms Enter
+Sleep 500ms
+Sleep 4s
+
+Type "# Fix: re-export from IR (or revert the file) — then validate-drift is clean again" Sleep 100ms Enter
+Sleep 2s

package/scripts/record-demo-payment-retry.tape

@@ -0,0 +1,36 @@
+# Phase A demo: golden payment + retry IR → FastAPI export → show emitted retry in main.py
+# Requires bash (Git Bash / WSL). From packages/deterministic:
+#   npm run build && vhs scripts/record-demo-payment-retry.tape
+# Voiceover (not in tape): IR is source of truth; editing generated code diverges —
+#   see record-demo-drift.tape → demo-drift.gif for validate-drift catching tampering.
+
+Output demo-payment-retry.gif
+
+Require echo
+
+Set Shell "bash"
+Set FontSize 16
+Set Width 1200
+Set Height 640
+Set Padding 20
+Set Theme "Catppuccin Mocha"
+
+Hide
+Type "clear" Enter
+Show
+
+Sleep 500ms
+Type "# Golden IR: fixtures/payment-retry-demo.json (edge retry + node retryPolicy)" Sleep 200ms Enter
+Sleep 400ms
+Type "npm run build && node dist/cli.js validate -i fixtures/payment-retry-demo.json" Sleep 100ms Enter
+Sleep 3s
+
+Type "node dist/cli.js export -i fixtures/payment-retry-demo.json -t python -o ./demo-payment-retry-out --skip-host-port-check" Sleep 100ms Enter
+Sleep 200ms
+Sleep 4s
+
+Type "grep -n 'maxAttempts' demo-payment-retry-out/app/main.py | head -6" Sleep 100ms Enter
+Sleep 3s
+
+Type "# Voiceover: delete retry in generated code → IR still encodes 3; re-run export to restore" Sleep 100ms Enter
+Sleep 2s

package/scripts/record-demo-validate.tape

@@ -0,0 +1,34 @@
+# Hero README GIF: failure-first validate loop (IR gate before codegen).
+# IR-LINT-DIRECT-DB-ACCESS-002 on violation → same intent, layered graph → clean validate.
+# Prereq: npm run build. From packages/deterministic (bash):
+#   vhs scripts/record-demo-validate.tape
+# → demo-validate.gif (stderr uses red IR-LINT lines when TTY — VHS/ttyd is TTY)
+
+Output demo-validate.gif
+Require echo
+
+Set Shell "bash"
+Set FontSize 16
+Set Width 1200
+Set Height 720
+Set Padding 20
+Set Theme "Catppuccin Mocha"
+
+Hide
+Type "clear" Enter
+Show
+
+Sleep 350ms
+Type "# Validate the blueprint IR — enforcement on the artifact (not on prose)" Sleep 120ms Enter
+Sleep 350ms
+Type "node dist/cli.js validate -i fixtures/demo-direct-db-violation.json" Sleep 100ms Enter
+Sleep 5s
+
+Type "# Fix the graph: service between API and DB + /health (see demo-direct-db-layered.json)" Sleep 100ms Enter
+Sleep 2s
+
+Type "node dist/cli.js validate -i fixtures/demo-direct-db-layered.json" Sleep 100ms Enter
+Sleep 4s
+
+Type "# CI: archrad validate --fail-on-warning  |  JSON: --json" Sleep 100ms Enter
+Sleep 2s

package/scripts/record-demo.tape

@@ -0,0 +1,33 @@
+# Record a README GIF with VHS: https://github.com/charmbracelet/vhs
+# Run from packages/deterministic (bash available): vhs scripts/record-demo.tape
+# → writes demo.gif next to package.json (packages/deterministic)
+# From monorepo root: cd packages/deterministic && vhs scripts/record-demo.tape
+
+Output demo.gif
+Require echo
+
+Set Shell "bash"
+Set FontSize 16
+Set Width 1200
+Set Height 600
+Set Padding 20
+Set Theme "Catppuccin Mocha"
+
+Hide
+Type "clear" Enter
+Show
+
+Sleep 500ms
+Type "# Build + export (golden path demo)" Sleep 200ms Enter
+Sleep 300ms
+Type "npm run build && node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out ./demo-gif-out --skip-host-port-check" Sleep 100ms Enter
+Sleep 4s
+
+Type "ls demo-gif-out | head -8" Sleep 100ms Enter
+Sleep 2s
+
+Type "# Next: cd demo-gif-out && make run  (Docker)" Sleep 100ms Enter
+Sleep 1s
+
+Type "# Then: curl -X POST http://localhost:8080/signup -H 'Content-Type: application/json' -d '{}'" Sleep 100ms Enter
+Sleep 2s