Merge feat/pull-erp: persist runs as an audit trail, bounded by a nightly reset

Bounded persistence replacing the stateless design: every run writes an
append-only agent_runs audit row, a "Recent runs" panel lists + replays them,
and a daily Vercel Cron resets Postgres so the demo stays pristine. Postgres
only — never touches the ERP/HRIS sandboxes. HITL resume stays replay-based.
Verified live; full gate green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: DylanMerigaud

.env.example

@@ -65,3 +65,12 @@ QBO_REALM_ID=
 # as-is and skip the refresh exchange — handy for a one-off capture from the
 # Playground without touching the refresh token.
 # QBO_ACCESS_TOKEN=
+
+# ─── Nightly reset cron (optional) ─────────────────────────────────────────
+# Every run is persisted as an append-only audit row (agent_runs); a daily Vercel
+# Cron (vercel.json) hits /api/reset to truncate + reseed Postgres so the demo
+# returns to a pristine queue each morning. The route is guarded by this shared
+# secret — Vercel injects it as `Authorization: Bearer $CRON_SECRET`; anything else
+# gets 401. Unset → the route refuses all callers (nothing resets). Postgres only;
+# the reset never touches the QuickBooks/BambooHR sandboxes.
+CRON_SECRET=

AGENT_BRIEF.md

@@ -53,8 +53,15 @@ The "complete loop" is built and on `main`. Key facts a fresh session must know:
   bounded loop (`lib/workflow-edit-agent.ts`) over the Claude SDK — NOT a Mastra
   Agent (see its header comment for why). Mastra owns the P2P pipeline
   (`src/mastra/workflows/p2p.ts`) and the exception-investigator agent.
-- **Stateless by design.** The run never writes to the DB. Keep it that way unless
-  told otherwise.
+- **Bounded persistence, not stateless.** The run writes ONE thing: an append-only
+  `agent_runs` audit row at the end (`db/runs.ts`), read back by the Recent runs
+  panel + replay. It NEVER writes the document tables or the ERP/HRIS, so a run
+  can't change a future run's verdict (the matcher always reads the pristine seed).
+  A nightly Vercel Cron (`/api/reset`, `vercel.json`) truncates+reseeds Postgres so
+  the demo stays pristine; the reset touches Postgres only, never the sandboxes.
+  HITL resume stays REPLAY-based (recompute the deterministic prefix from the
+  decisions), NOT Mastra snapshot/suspend — keep it that way (the snapshot path has
+  a known Postgres-bloat footgun). Don't reintroduce writes to the document tables.
 - **The recorded HRIS fixture is SEED-BUILT**, not a live capture
   (`scripts/build-recorded-fixture.ts` → `pnpm fixture:build`). recorded == live ==
   the 13-person "LedgerLoop Demo" org. Don't reintroduce a real-capture claim.

README.md

@@ -103,9 +103,13 @@ The manager gate fires on any exception **or** a clean bill over a floor ($1,000
 
 **Streaming, typed end to end.** The `run` procedure is an **oRPC event iterator** (a typed async generator of `TraceEvent | StreamDone`); the client consumes it with `for await`, no manual reader or cast. A small adapter ([`lib/trace.ts`](lib/trace.ts)) maps Mastra's raw `run.stream()` chunks to the stable `TraceEvent` vocabulary so the UI depends on ours, not Mastra's internals, and a junk chunk is dropped rather than crashing the stream.
 
-### Stateless by design
+### Bounded persistence + a nightly reset
 
-The seeded data is read-only. "Run pipeline" executes server-side, streams the trace, and **forgets** — so the 50th visitor sees the same pristine state as the 1st. (The `agent_runs` table is modelled as the canonical persisted shape of a run but intentionally left empty.)
+Every run is persisted as an append-only **audit row** ([`agent_runs`](db/schema.ts)) — its verdict, outcome, and the full trace — and the dashboard's **Recent runs** panel lists them, each one replayable (click → the stored trace re-renders with no model call, zero tokens). That's the audit trail an AP buyer asks for first.
+
+The persistence is **bounded**: a daily [Vercel Cron](vercel.json) hits [`/api/reset`](app/api/reset/route.ts) (guarded by `CRON_SECRET`), which truncates + reseeds Postgres — so the demo returns to a pristine queue each morning, the 1st visitor's view restored for the next. The reset touches **Postgres only**; it never calls the QuickBooks/BambooHR sandboxes (frozen fixtures the pipeline reads, never writes), so it can't fail on a rotated token or desync an external system.
+
+Crucially, a saved run **can't change a future run's verdict**: the app writes only `agent_runs`, never the document tables or the ERP/HRIS, so the matcher always reads the pristine seed. Persisting the audit trail and keeping every run deterministic are not in tension. The human-in-the-loop pause/resume stays **replay-based** (the run recomputes the deterministic prefix from the decisions) — persistence is for the audit log, not the resume, which keeps it off the costly Mastra-snapshot path.
 
 ### Project layout
 
@@ -177,6 +181,7 @@ pnpm dev                          # http://localhost:3000
 | `BAMBOO_HR_API_KEY` + `BAMBOO_HR_SUBDOMAIN` | optional | Live BambooHR. **Without them onboarding replays the committed real fixture** — the demo and CI work with no key. |
 | `QBO_CLIENT_ID` + `QBO_CLIENT_SECRET` + `QBO_REFRESH_TOKEN` + `QBO_REALM_ID` | optional | Live QuickBooks (ERP pull). **Without all four the pipeline replays the committed real fixture** — demo and CI work with no key. |
 | `UPSTASH_*` / `KV_REST_API_*` | optional | Per-IP rate limiting; fails open without it |
+| `CRON_SECRET` | optional | Guards the nightly `/api/reset` cron (Vercel injects it as a bearer token). Unset → the reset route refuses all callers. |
 
 > **Set a spend cap on the Anthropic key** — the deployed demo is public and the buttons call the model.
 
@@ -186,11 +191,11 @@ pnpm dev                          # http://localhost:3000
 
 ## What's next
 
-A stateless demo; the decision logic is pure, typed, and unit-tested, and the read-side integrations (HRIS, ERP pull) are already real-or-replayed. Production is additive, not a rewrite:
+The decision logic is pure, typed, and unit-tested; the read-side integrations (HRIS, ERP pull) are already real-or-replayed; and runs are persisted as an audit trail bounded by a nightly reset. Production is additive, not a rewrite:
 
 - the ERP **pull** is real (QuickBooks); swap the **post**-side stub (`fakeErp`) and the Slack/Jira integration stubs for real adapters of the same interfaces,
 - live BambooHR + QuickBooks (both adapters + captured fixtures already exist; keys unlock the live path) and a second HRIS / ERP behind the same `HrisAdapter` / `PoSourceAdapter`,
-- add persistence and an audit trail (the `agent_runs` table is shaped for it) so a workflow and a paused run survive a refresh,
+- the audit trail persists today (append-only `agent_runs`, replayable, reset nightly); drop the reset and add per-tenant scoping for a multi-client deployment, and persist the paused-run snapshot if you want resume to survive a server restart (today it's recomputed from the decisions),
 - wire real approver identity to the per-step gates,
 - accept real uploaded PDFs at intake.
 

app/api/reset/route.ts

@@ -0,0 +1,43 @@
+import { getDb } from "@/db/client";
+import { resetAndReseed } from "@/db/reset";
+import { env } from "@/lib/env";
+import { log } from "@/lib/logger";
+
+/**
+ * GET /api/reset — truncate + reseed Postgres back to the pristine demo dataset.
+ *
+ * Invoked once a day by a Vercel Cron (see vercel.json). This is what makes the
+ * persistence safe: every run writes an append-only `agent_runs` audit row, and
+ * this clears them nightly so the public demo returns to a clean queue — the
+ * "pristine for the next visitor" property, kept while still having an audit trail.
+ *
+ * Scope: Postgres ONLY. It never touches the QuickBooks / BambooHR sandboxes
+ * (those are frozen fixtures the pipeline reads, never writes), so the reset can't
+ * fail on a rotated QBO token and can't desync an external system.
+ *
+ * Guarded by CRON_SECRET: Vercel Cron sends `Authorization: Bearer $CRON_SECRET`.
+ * Anything without the matching secret gets 401 — so this isn't a public truncate
+ * button. If CRON_SECRET is unset, the route refuses all callers.
+ *
+ * Node runtime — it does real Postgres writes via the postgres-js driver.
+ */
+export const runtime = "nodejs";
+
+export const GET = async (request: Request): Promise<Response> => {
+  const secret = env.CRON_SECRET;
+  const auth = request.headers.get("authorization");
+  if (!secret || auth !== `Bearer ${secret}`) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  try {
+    const counts = await resetAndReseed(getDb());
+    log.info("nightly reset complete", counts);
+    return Response.json({ ok: true, ...counts });
+  } catch (err) {
+    log.error("nightly reset failed", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return new Response("Reset failed.", { status: 500 });
+  }
+};