@databricks-solutions/lakebase-scm-utils 0.3.2 → 0.3.4

package/templates/project/client/tests/setup.ts

@@ -1,10 +1,85 @@
-// Vitest global setup: extends expect() with jest-dom matchers and clears the
-// DOM + mocks between tests so each test starts from a known state.
+// Vitest setup: extends expect() with jest-dom matchers and clears the DOM between tests.
+//
+// Kit principle — never mock when a real counterpart exists: component tests hit the REAL backend
+// over the REAL `/api` boundary. jsdom has no origin, so a relative `fetch("/api/stock")` throws
+// "Failed to parse URL"; this shim prefixes relative `/api` + `/health` with the backend the global
+// setup (`vitest.globalSetup.ts`) booted and published to `.consort/.vitest-backend`. The component
+// still only speaks HTTP — it never touches the DB. When no backend was booted (no base file) the
+// shim is inert, so a pure-presentation component test is unaffected.
 import "@testing-library/jest-dom/vitest";
-import { afterEach, vi } from "vitest";
+import { afterEach, beforeEach, vi } from "vitest";
 import { cleanup } from "@testing-library/react";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { captureTablesFromRoute } from "../../consort-capture";
 
-afterEach(() => {
+const TEST_ID = /@(T\d+(?:-[a-z0-9-]+)?)/;
+
+// The @T<id> of the test currently running, so the fetch shim can tag each /api request with it (the
+// backend attributes the rows the request RETRIEVES/STORED to this test — app/consort_capture.py).
+let currentTestId: string | null = null;
+beforeEach((ctx: { task?: { name?: string } }) => {
+  currentTestId = TEST_ID.exec(ctx?.task?.name ?? "")?.[1] ?? null;
+});
+
+function backendBase(): string {
+  let d = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    try {
+      return readFileSync(join(d, ".consort", ".vitest-backend"), "utf8").trim();
+    } catch {
+      /* walk up to the project root */
+    }
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return "";
+}
+
+const BACKEND_BASE = backendBase();
+if (BACKEND_BASE) {
+  const realFetch = globalThis.fetch.bind(globalThis);
+  const isApi = (u: string): boolean => u.startsWith("/api") || u.startsWith("/health");
+  const reroute = (url: string): string => (isApi(url) ? BACKEND_BASE + url : url);
+  // Add the X-Consort-Test-Id header to each /api request so the backend's per-test capture can key
+  // the rows this request reads/writes to the running test.
+  const tag = (url: string, init?: RequestInit): RequestInit | undefined => {
+    if (!currentTestId || !isApi(url)) return init;
+    const headers = new Headers(init?.headers);
+    headers.set("X-Consort-Test-Id", currentTestId);
+    return { ...init, headers };
+  };
+  globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+    if (typeof input === "string") return realFetch(reroute(input), tag(input, init));
+    if (input instanceof URL) {
+      const u = input.toString();
+      return realFetch(reroute(u), tag(u, init));
+    }
+    if (input instanceof Request && input.url.startsWith("/")) {
+      const r = new Request(reroute(input.url), input);
+      if (currentTestId && isApi(input.url)) r.headers.set("X-Consort-Test-Id", currentTestId);
+      return realFetch(r, init);
+    }
+    return realFetch(input, init);
+  }) as typeof fetch;
+}
+
+// Per-test table-state capture lives HERE (the worker), not in the reporter: `BACKEND_BASE` is
+// resolved in the worker after globalSetup booted the backend (same read the shim above proved
+// works), whereas the reporter runs in the MAIN process where that base did not resolve — so the
+// reporter's capture silently no-op'd. Running it in afterEach is also version-independent (always
+// fires) and has the current test in context. Captures the DB state THIS component test left, keyed
+// by its @T<id>, via the app's snapshot route (shared writer with the pytest/Playwright reporters).
+afterEach(async (ctx: { task?: { name?: string; file?: { filepath?: string } } }) => {
   cleanup();
   vi.restoreAllMocks();
+  if (!BACKEND_BASE) return;
+  const id = TEST_ID.exec(ctx?.task?.name ?? "")?.[1];
+  if (!id) return;
+  try {
+    await captureTablesFromRoute(BACKEND_BASE, id, ctx?.task?.file?.filepath ?? "");
+  } catch {
+    /* best-effort: a snapshot write must never fail the test */
+  }
 });

package/templates/project/client/tsconfig.json

@@ -15,7 +15,7 @@
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true,
-    "types": ["vitest/globals", "@testing-library/jest-dom"]
+    "types": ["vitest/globals", "@testing-library/jest-dom", "node"]
   },
   "include": ["src", "tests/setup.ts"]
 }

package/templates/project/client/vite.config.ts

@@ -33,6 +33,14 @@ export default defineConfig({
     environment: "jsdom",
     globals: true,
     setupFiles: "./tests/setup.ts",
+    // Boot a REAL backend (migrated, against the paired branch) for the whole component run, so
+    // component tests hit the real `/api` service — never a mock (kit principle). The fetch shim in
+    // tests/setup.ts routes relative `/api` to it. Torn down after. See vitest.globalSetup.ts.
+    globalSetup: "./vitest.globalSetup.ts",
+    // Keep Vitest's own `default` reporter for humans, and add the Consort per-test reporter:
+    // it appends each `@T<id>`-named test to `.consort/test-run.jsonl` as it finishes, so the
+    // dashboard lights client tests live alongside the backend (pytest) and E2E (Playwright) ones.
+    reporters: ["default", "./consort-vitest-reporter.ts"],
     include: ["src/**/*.test.{ts,tsx}", "tests/**/*.test.{ts,tsx}"],
     exclude: [...configDefaults.exclude, "tests/e2e/**"],
     css: false,

package/templates/project/client/vitest.globalSetup.ts

@@ -0,0 +1,121 @@
+// Vitest global setup — boot a REAL backend for the component suite.
+//
+// Kit principle: never mock when a real counterpart exists. Client component tests must hit the
+// REAL backend over the REAL `/api` boundary (which hits the real paired-branch DB), exactly like
+// production — the client never gets direct DB access. This mirrors `playwright.config.ts`'s backend
+// webServer: migrate the branch, serve the app on a free 127.0.0.1 port, wait for health, and
+// publish the base URL to `.consort/.vitest-backend` for the fetch shim in `tests/setup.ts`. Torn
+// down after the run. Language-aware (python / node / java), same detection as the Playwright config.
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { join } from "node:path";
+
+const ROOT = join(process.cwd(), ".."); // vitest runs from client/
+const CLIENT = join(ROOT, "client");
+const BASE_FILE = join(ROOT, ".consort", ".vitest-backend");
+
+// True iff the project has at least one component test (`*.test.tsx|ts` under client/src or
+// client/tests, excluding the Playwright `tests/e2e/` dir). When there are none, booting a backend
+// is pure waste and an avoidable failure surface — so the setup is a no-op (returns early). This is
+// what keeps a component-less project (e.g. one whose UI is all Playwright E2E) from paying for, or
+// failing on, a backend boot it never uses.
+function hasComponentTests(): boolean {
+  const stack: string[] = [join(CLIENT, "src"), join(CLIENT, "tests")];
+  while (stack.length) {
+    const dir = stack.pop()!;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const abs = join(dir, e);
+      if (abs.replace(/\\/g, "/").includes("/tests/e2e")) continue; // Playwright's, not Vitest's
+      let st;
+      try {
+        st = statSync(abs);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) stack.push(abs);
+      else if (/\.test\.(ts|tsx|js|jsx)$/.test(e)) return true;
+    }
+  }
+  return false;
+}
+
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.on("error", reject);
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+// migrate-before-serve command + health URL for the detected stack (mirrors the Playwright config).
+function backend(port: number): { shell: string; health: string } {
+  if (existsSync(join(ROOT, "pom.xml"))) {
+    return {
+      shell: `./mvnw -q flyway:migrate && ./mvnw -q spring-boot:run -Dspring-boot.run.arguments=--server.port=${port}`,
+      health: `http://127.0.0.1:${port}/actuator/health`,
+    };
+  }
+  if (
+    existsSync(join(ROOT, "package.json")) &&
+    !existsSync(join(ROOT, "pyproject.toml")) &&
+    !existsSync(join(ROOT, "requirements.txt"))
+  ) {
+    return { shell: `npm run migrate && PORT=${port} npm run start`, health: `http://127.0.0.1:${port}/health` };
+  }
+  return {
+    shell: `uv run alembic upgrade head && uv run uvicorn app.main:app --host 127.0.0.1 --port ${port}`,
+    health: `http://127.0.0.1:${port}/health`,
+  };
+}
+
+let proc: ChildProcess | undefined;
+
+export default async function setup(ctx?: { provide?: (k: string, v: unknown) => void }): Promise<() => Promise<void>> {
+  if (!hasComponentTests()) {
+    // No component tests → nothing to serve a backend for. No-op teardown.
+    return async () => {};
+  }
+  const port = await freePort();
+  const base = `http://127.0.0.1:${port}`;
+  const { shell, health } = backend(port);
+  proc = spawn("bash", ["-c", shell], { cwd: ROOT, stdio: "ignore", env: { ...process.env } });
+
+  const deadline = Date.now() + 120_000;
+  for (;;) {
+    try {
+      const r = await fetch(health);
+      if (r.ok) break;
+    } catch {
+      /* backend not up yet */
+    }
+    if (Date.now() > deadline) {
+      if (proc && !proc.killed) proc.kill("SIGTERM");
+      throw new Error(`vitest: backend did not become healthy at ${health} within 120s`);
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+
+  mkdirSync(join(ROOT, ".consort"), { recursive: true });
+  writeFileSync(BASE_FILE, base); // the fetch shim reads this (pool-agnostic)
+  ctx?.provide?.("consortApiBase", base);
+
+  return async () => {
+    try {
+      rmSync(BASE_FILE);
+    } catch {
+      /* already gone */
+    }
+    if (proc && !proc.killed) proc.kill("SIGTERM");
+  };
+}

package/templates/project/common/consort-capture.ts

@@ -0,0 +1,87 @@
+// Consort per-test capture writers — FRAMEWORK-AGNOSTIC (no Playwright, no Vitest import).
+//
+// These are the shared, pure Node helpers the three test reporters use to stream per-test signals to
+// `.consort/`: the status trail (`test-run.jsonl`) the dashboard tails to light bubbles, and the
+// per-test table snapshots (`table-snapshots.jsonl`) the dashboard reads for its table view. They
+// live in their OWN module (not in `consort-test-reporter.ts`) precisely because that file imports
+// `@playwright/test/reporter` for the Playwright Reporter class — and the Vitest client compile
+// (`tests/setup.ts` captures table state in an afterEach) must NOT drag Playwright's types through
+// the client's bundler-resolution tsconfig. Importing these from here keeps the client Playwright-free.
+//
+// Pure observability: everything is wrapped so a write can NEVER fail a test/suite.
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Walk up from `start` to the project's `.consort` dir (tests run from root OR client/, so cwd
+ *  varies); fall back to `<cwd>/.consort` (created on write) if none is found. */
+export function findConsortDir(start: string): string {
+  let d = start;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(d, ".consort"))) return join(d, ".consort");
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return join(start, ".consort");
+}
+
+export type TestRunStatus = "running" | "green" | "red" | "skipped";
+
+export function emitTestRun(id: string, status: TestRunStatus, absFile: string, kind: string): void {
+  try {
+    const dir = findConsortDir(process.cwd());
+    mkdirSync(dir, { recursive: true });
+    const root = dirname(dir);
+    const file = (absFile || "").replace(`${root}/`, "");
+    appendFileSync(
+      join(dir, "test-run.jsonl"),
+      JSON.stringify({ ts: new Date().toISOString(), test_id: id, status, file, kind }) + "\n",
+    );
+  } catch {
+    /* best-effort: a per-test reporter write must never fail the suite */
+  }
+}
+
+/** Append a per-test TABLE snapshot (one line per table) to `.consort/table-snapshots.jsonl`, keyed
+ *  by test id — parallel to `emitTestRun`. Best-effort. */
+export function emitTableSnapshot(id: string, absFile: string, table: string, rows: unknown[], rowCount: number | null): void {
+  try {
+    const dir = findConsortDir(process.cwd());
+    mkdirSync(dir, { recursive: true });
+    const root = dirname(dir);
+    const file = (absFile || "").replace(`${root}/`, "");
+    appendFileSync(
+      join(dir, "table-snapshots.jsonl"),
+      JSON.stringify({ ts: new Date().toISOString(), test_id: id, file, table, rows, row_count: rowCount }) + "\n",
+    );
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Capture the DB state a test left — for the dashboard's per-test table view — by asking the app's
+ *  read-only `/api/_consort/table-snapshot` route (the client never touches the DB; the app, which the
+ *  test hit over `/api`, reports its rows). Writes one `emitTableSnapshot` per table, keyed by test id.
+ *  Shared by the Playwright (e2e) AND Vitest (component) paths — both drive the DB THROUGH the app.
+ *  Best-effort + time-boxed: a missing route (prod app) or a slow/unreachable endpoint just skips it. */
+export async function captureTablesFromRoute(baseURL: string, id: string, absFile: string): Promise<void> {
+  if (!baseURL) return;
+  try {
+    // Time-box with Promise.race, NOT an AbortController signal: this runs in BOTH Node (Playwright /
+    // pytest reporters) and jsdom (Vitest component afterEach), and a jsdom-realm AbortSignal is not an
+    // instance of the AbortSignal Node's undici fetch expects ("Expected signal to be an instance of
+    // AbortSignal") — it throws there and the capture silently no-ops. A dangling GET on timeout is a
+    // harmless read-only best-effort call.
+    const res = await Promise.race([
+      fetch(`${baseURL.replace(/\/$/, "")}/api/_consort/table-snapshot`),
+      new Promise<Response>((_, reject) => setTimeout(() => reject(new Error("snapshot timeout")), 4000)),
+    ]);
+    if (!res.ok) return;
+    const tables = (await res.json()) as Record<string, { rows?: unknown[]; row_count?: number | null }>;
+    for (const [table, data] of Object.entries(tables)) {
+      emitTableSnapshot(id, absFile, table, data.rows ?? [], data.row_count ?? null);
+    }
+  } catch {
+    /* route absent (prod) / unreachable / timed out — skip the snapshot */
+  }
+}

package/templates/project/common/consort-test-reporter.ts

@@ -0,0 +1,45 @@
+// Consort per-test "green as it runs" reporter for Playwright.
+//
+// Appends one line to `.consort/test-run.jsonl` as each test tagged `@T<id>` in its title finishes,
+// so the dashboard tails it and lights that test live — even under story cadence (one whole-suite
+// run), where otherwise every test would appear to flip at once. The `file` disambiguates a reused
+// test id across features (F1 and F2 may both carry a T37); the dashboard keys by (scenario_file + id).
+//
+// The shared, framework-agnostic capture writers (emitTestRun / emitTableSnapshot /
+// captureTablesFromRoute / findConsortDir) live in `./consort-capture` — this file is the ONLY one
+// that imports `@playwright/test/reporter`, so the Vitest/client compile never pulls in Playwright.
+// Re-exported here for back-compat with importers that still reach through this module.
+//
+// Pure observability: everything is wrapped so a reporter write can NEVER fail the suite. Tag a test
+// by putting its test-list id in the title, e.g. `test("home table lists stock @T37", …)`.
+import type { FullConfig, Reporter, TestCase, TestResult } from "@playwright/test/reporter";
+import { emitTestRun, captureTablesFromRoute } from "./consort-capture";
+
+export { findConsortDir, emitTestRun, emitTableSnapshot, captureTablesFromRoute, type TestRunStatus } from "./consort-capture";
+
+const TEST_ID = /@(T\d+(?:-[a-z0-9-]+)?)/;
+
+export default class ConsortTestReporter implements Reporter {
+  private baseURL = "";
+
+  // The app's read-only snapshot route lives at the app origin; E2E specs hit the DB THROUGH the
+  // app, so after each spec we ask the app what rows it left (the client never touches the DB).
+  onBegin(config: FullConfig): void {
+    this.baseURL = config.projects?.[0]?.use?.baseURL ?? "";
+  }
+
+  // Emit `running` the moment a tagged spec starts, so the dashboard shows it in-flight (amber)
+  // before it resolves — the dashboard's last-write-wins reduce makes running -> green compose.
+  onTestBegin(test: TestCase): void {
+    const id = TEST_ID.exec(test.title)?.[1];
+    if (id) emitTestRun(id, "running", test.location?.file ?? "", "client");
+  }
+
+  async onTestEnd(test: TestCase, result: TestResult): Promise<void> {
+    const id = TEST_ID.exec(test.title)?.[1];
+    if (!id) return;
+    const status = result.status === "passed" ? "green" : result.status === "skipped" ? "skipped" : "red";
+    emitTestRun(id, status, test.location?.file ?? "", "client");
+    await captureTablesFromRoute(this.baseURL, id, test.location?.file ?? "");
+  }
+}

package/templates/project/common/playwright.config.ts

@@ -37,7 +37,12 @@ export default defineConfig({
   // network jitter against a freshly-provisioned paired branch endpoint.
   retries: process.env.CI ? 1 : 0,
   workers: process.env.CI ? 2 : undefined,
-  reporter: process.env.CI ? [["html", { open: "never" }], ["list"]] : "list",
+  // `./consort-test-reporter.ts` appends each `@T<id>`-tagged test to `.consort/test-run.jsonl` as
+  // it finishes, so the Consort dashboard lights per-test progress live (see that file). It rides
+  // alongside the human reporters and never replaces them.
+  reporter: process.env.CI
+    ? [["html", { open: "never" }], ["list"], ["./consort-test-reporter.ts"]]
+    : [["list"], ["./consort-test-reporter.ts"]],
   use: {
     baseURL,
     trace: "on-first-retry",

package/templates/project/python/app/consort_capture.py

@@ -0,0 +1,130 @@
+"""Per-test RETRIEVED/STORED row capture (dev/test/CI only) for the Consort dashboard.
+
+The dashboard's per-test table view wants the rows each TEST actually touched — not the whole table.
+Every test (pytest / Playwright / Vitest component) exercises the DB THROUGH this app over `/api`, so
+this app is the one place that sees every query. Each test tags its requests with an
+`X-Consort-Test-Id: T<id>` header; a middleware stashes that id in a contextvar for the request, and
+two SQLAlchemy events record the rows that request touched, keyed by the test id:
+
+  * RETRIEVED  — the ORM `load` event fires as each row is materialized into a mapped instance
+                 (covers every `select(Model)` read path).
+  * STORED     — the `after_cursor_execute` event fires for INSERT/UPDATE/DELETE; the written values
+                 live in the statement's bound parameters (the app writes via `insert(...).returning()`
+                 executed as a statement, which `after_flush`/unit-of-work would NOT see).
+
+Each touched row is appended to `.consort/test-interactions.jsonl` as
+`{ts, test_id, table, op: "read"|"write", row}`. Guarded by the PRESENCE of a `.consort/` dir (dev/
+test/CI checkout, not a packaged prod app) exactly like the snapshot route — so this is simply absent
+in a real deploy. Everything is wrapped so a capture write can NEVER fail a request.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import json
+import os
+import re
+import threading
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlalchemy import event
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import DeclarativeBase
+
+# The current request's test id (from the X-Consort-Test-Id header), and the per-request buffer of
+# touched rows. ContextVars propagate into Starlette's sync-endpoint threadpool, so the SQLAlchemy
+# events (which fire on the DB call within the handler) see the id the middleware set.
+_TEST_ID: contextvars.ContextVar[str | None] = contextvars.ContextVar("consort_test_id", default=None)
+_BUFFER: contextvars.ContextVar[list[dict[str, Any]] | None] = contextvars.ContextVar("consort_buffer", default=None)
+
+_WRITE_LOCK = threading.Lock()
+_ROWS_CAP = 200  # per (test, table, op) within one request — keep the log bounded
+_DML = re.compile(r"^\s*(INSERT|UPDATE|DELETE)\b", re.IGNORECASE)
+_TABLE = re.compile(r'(?:INTO|UPDATE|FROM)\s+"?([A-Za-z_][A-Za-z0-9_]*)"?', re.IGNORECASE)
+
+
+def _jsonable(v: Any) -> Any:
+    if isinstance(v, datetime):
+        return v.isoformat()
+    try:
+        json.dumps(v)
+        return v
+    except (TypeError, ValueError):
+        return str(v)
+
+
+def _record(table: str, op: str, row: dict[str, Any]) -> None:
+    """Append a touched row to the current request's buffer (no-op outside a tagged request)."""
+    buf = _BUFFER.get()
+    if buf is None:
+        return
+    # Bound the buffer per (table, op) so a big list read can't explode the log.
+    n = sum(1 for e in buf if e["table"] == table and e["op"] == op)
+    if n >= _ROWS_CAP:
+        return
+    buf.append({"table": table, "op": op, "row": {k: _jsonable(v) for k, v in row.items()}})
+
+
+def _flush(path: str, test_id: str, buf: list[dict[str, Any]]) -> None:
+    if not buf:
+        return
+    ts = datetime.now(timezone.utc).isoformat()
+    lines = "".join(
+        json.dumps({"ts": ts, "test_id": test_id, "table": e["table"], "op": e["op"], "row": e["row"]}) + "\n"
+        for e in buf
+    )
+    try:
+        with _WRITE_LOCK:
+            with open(path, "a", encoding="utf-8") as fh:
+                fh.write(lines)
+    except OSError:
+        pass  # best-effort: a capture write must never fail a request
+
+
+def install(app: Any, engine: Engine, base: type[DeclarativeBase]) -> None:
+    """Wire the middleware + SQLAlchemy events. No-op unless a `.consort/` dir is present."""
+    project_root = os.path.join(os.path.dirname(__file__), os.pardir)
+    consort_dir = os.path.join(project_root, ".consort")
+    if not os.path.isdir(consort_dir):
+        return
+    interactions_path = os.path.join(consort_dir, "test-interactions.jsonl")
+
+    @app.middleware("http")
+    async def _consort_tag_request(request: Any, call_next: Any) -> Any:
+        test_id = request.headers.get("x-consort-test-id")
+        id_token = _TEST_ID.set(test_id)
+        buf_token = _BUFFER.set([] if test_id else None)
+        try:
+            return await call_next(request)
+        finally:
+            buf = _BUFFER.get()
+            if test_id and buf:
+                _flush(interactions_path, test_id, buf)
+            _BUFFER.reset(buf_token)
+            _TEST_ID.reset(id_token)
+
+    @event.listens_for(base, "load", propagate=True)
+    def _consort_on_load(target: Any, _context: Any) -> None:  # RETRIEVED
+        if _TEST_ID.get() is None:
+            return
+        try:
+            table = target.__tablename__
+            row = {c.key: getattr(target, c.key) for c in target.__table__.columns}
+            _record(table, "read", row)
+        except Exception:  # noqa: BLE001 — capture must never break a load
+            pass
+
+    @event.listens_for(engine, "after_cursor_execute")
+    def _consort_on_execute(_conn, _cursor, statement, parameters, _context, _executemany) -> None:  # STORED
+        if _TEST_ID.get() is None or not statement or not _DML.match(statement):
+            return
+        try:
+            m = _TABLE.search(statement)
+            table = m.group(1) if m else "?"
+            params_list = parameters if isinstance(parameters, (list, tuple)) else [parameters]
+            for p in params_list:
+                if isinstance(p, dict) and p:
+                    _record(table, "write", dict(p))
+        except Exception:  # noqa: BLE001
+            pass

package/templates/project/python/app/database.py

@@ -118,9 +118,9 @@ class Base(DeclarativeBase):
     pass
 
 
-def get_db():
-    db = SessionLocal()
-    try:
-        yield db
-    finally:
-        db.close()
+# The request-scoped session DEPENDENCY (`get_session`) lives in the repository layer,
+# at `app/repositories/session.py` — NOT here. This module is pure infrastructure (engine,
+# SessionLocal, Base); keeping the per-request session door out of it is what lets a
+# service-backed feature's boundary stay off infrastructure (the layering contract). A route
+# that needs a session depends on the session a SERVICE exposes (sourced from the repository
+# layer), never `from app.database import ...` a session dependency.

package/templates/project/python/app/main.py

@@ -14,6 +14,58 @@ def health():
     return {"status": "ok"}
 
 
+# ── Consort dashboard table-snapshot (dev/test/CI only) ─────────────────────
+# A READ-ONLY peek at the current rows of each public table, for the Consort
+# dashboard's per-test table view. E2E (Playwright) specs mutate the DB THROUGH
+# the app, so the app is the one process already connected to the branch — the
+# E2E reporter calls this after each spec to record the DB state that spec left.
+# Guarded by the PRESENCE of a `.consort/` dir at the project root: present in a
+# dev/test/CI checkout but NOT in a packaged production app, so the route is
+# simply absent in a real deploy — no env flag, no per-server wiring. Read-only,
+# row-capped, identifier-validated.
+_PROJECT_ROOT = os.path.join(os.path.dirname(__file__), os.pardir)
+if os.path.isdir(os.path.join(_PROJECT_ROOT, ".consort")):
+    import re as _re
+
+    from sqlalchemy import text as _sql_text
+
+    from app.database import engine as _snap_engine
+
+    _SNAP_IDENT = _re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+    _SNAP_CAP = 50
+
+    @app.get("/api/_consort/table-snapshot")
+    def _consort_table_snapshot():
+        """Current rows of every public app table (except alembic_version), capped. Read-only."""
+        out: dict[str, dict] = {}
+        with _snap_engine.connect() as conn:
+            names = [
+                r[0]
+                for r in conn.execute(
+                    _sql_text(
+                        "select tablename from pg_tables where schemaname='public' "
+                        "and tablename <> 'alembic_version' order by 1"
+                    )
+                )
+            ]
+            for name in names:
+                if not _SNAP_IDENT.fullmatch(name):
+                    continue
+                rows = conn.execute(_sql_text(f'SELECT * FROM "{name}" ORDER BY 1 DESC LIMIT {_SNAP_CAP}')).mappings().all()
+                total = conn.execute(_sql_text(f'SELECT count(*) FROM "{name}"')).scalar()
+                out[name] = {"rows": [dict(r) for r in rows], "row_count": total}
+        return out
+
+    # Per-test RETRIEVED/STORED row capture: records the rows each test's `/api` requests read/wrote
+    # (keyed by the X-Consort-Test-Id header) to `.consort/test-interactions.jsonl`, for the
+    # dashboard's per-test table view. Middleware + SQLAlchemy ORM `load`/DML events; same dev/test/CI
+    # guard as the snapshot route above. See app/consort_capture.py.
+    from app import consort_capture as _consort_capture
+    from app.database import Base as _consort_base
+
+    _consort_capture.install(app, _snap_engine, _consort_base)
+
+
 # ── Register API routes ABOVE this line ─────────────────────────────────────
 # Everything below serves the built React SPA (client/dist) in production, so a
 # single-process deploy (e.g. a Databricks App) serves both the API and the UI.

package/templates/project/python/app/repositories/__init__.py

@@ -0,0 +1,8 @@
+"""Repository layer: the ONLY layer that touches the ORM / database session.
+
+Each feature's repositories (data access for one aggregate) live here, alongside
+the shared request-session door `session.get_session`. Business logic lives in the
+service layer above; persistence lives only here. A service-backed feature's
+boundary (routes) therefore never imports the DB session from infrastructure
+(`app.database`) — it depends on a session the service exposes, sourced here.
+"""

package/templates/project/python/app/repositories/session.py

@@ -0,0 +1,28 @@
+"""Request-scoped database session — the repository layer's session door.
+
+The ONE place a request obtains a SQLAlchemy `Session`. It lives in the REPOSITORY
+layer (not infrastructure) on purpose: the layering contract is boundary -> service
+-> repository, and ONLY the repository (and the engine in `app.database`) touches the
+session. So a service-backed feature's route NEVER imports the session from
+`app.database`; instead a service exposes `get_session` (re-exporting it) and the route
+depends on that. A simple, non-layered feature may depend on `get_session` directly —
+it is still outside infrastructure, so the boundary stays clean either way.
+
+The engine + `SessionLocal` are built once in `app.database` (runtime-minted Lakebase
+token per connection); this module only hands out and closes a session.
+"""
+
+from collections.abc import Iterator
+
+from sqlalchemy.orm import Session
+
+from app.database import SessionLocal
+
+
+def get_session() -> Iterator[Session]:
+    """Yield a database session and always close it (FastAPI `Depends` / `with` use)."""
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

package/templates/project/python/pyproject.toml

@@ -33,4 +33,5 @@ dev = [
 # downgrade/upgrade cannot corrupt the shared verify DB for sibling tests.
 markers = [
     "migration: schema-mutating migration-reversibility test; runs on an isolated ephemeral branch",
+    "testid: the test-list id (e.g. @pytest.mark.testid(\"T37\")) this test realizes, for the dashboard's per-test live signal",
 ]