@rawsql-ts/ztd-cli 0.16.0 → 0.19.0

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "@rawsql-ts/ztd-cli",
-  "version": "0.16.0",
+  "version": "0.19.0",
   "description": "DB-agnostic scaffolding and DDL helpers for Zero Table Dependency projects",
   "main": "dist/index.js",
   "bin": {
     "ztd": "dist/index.js"
   },
+  "scripts": {
+    "prepack": "node -e \"const fs=require('fs');const cp=require('child_process');const npm=process.platform==='win32'?'npm.cmd':'npm';if(!fs.existsSync('dist/index.js')){process.exit(cp.spawnSync(npm,['run','build'],{stdio:'inherit'}).status??1)}\"",
+    "build": "pnpm --filter rawsql-ts run build && pnpm --filter @rawsql-ts/sql-grep-core run build && pnpm --filter @rawsql-ts/test-evidence-core run build && pnpm --filter @rawsql-ts/test-evidence-renderer-md run build && pnpm --filter @rawsql-ts/testkit-core run build && tsc -p tsconfig.json",
+    "test": "pnpm --filter @rawsql-ts/adapter-node-pg run build && vitest run --config vitest.config.ts",
+    "lint": "eslint src --ext .ts",
+    "release": "npm run lint && npm run test && npm run build && node -e \"require('fs').mkdirSync('../../tmp', { recursive: true })\" && pnpm pack --out ../../tmp/rawsql-ts-ztd-cli.tgz && pnpm publish --access public",
+    "test:consumer-validation": "vitest run --config vitest.config.ts tests/testEvidence.unit.test.ts tests/testEvidence.cli.test.ts tests/sqlCatalog.evidence.test.ts tests/testCaseCatalog.evidence.test.ts"
+  },
   "keywords": [
     "rawsql-ts",
     "ztd",
@@ -15,6 +23,11 @@
   ],
   "author": "msugiura",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mk3008/rawsql-ts.git",
+    "directory": "packages/ztd-cli"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -22,21 +35,33 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@testcontainers/postgresql": "^10.28.0",
+    "@rawsql-ts/test-evidence-core": "workspace:*",
+    "@rawsql-ts/test-evidence-renderer-md": "workspace:*",
     "chokidar": "^5.0.0",
     "commander": "^12.0.0",
     "diff": "^8.0.3",
     "fast-glob": "^3.3.3",
-    "pg": "^8.11.1",
-    "testcontainers": "^10.28.0",
-    "@rawsql-ts/adapter-node-pg": "^0.15.1",
-    "@rawsql-ts/testkit-postgres": "^0.15.1",
-    "@rawsql-ts/testkit-core": "^0.15.1",
-    "rawsql-ts": "^0.16.0"
+    "rawsql-ts": "workspace:^",
+    "yaml": "^2.8.2",
+    "@rawsql-ts/sql-grep-core": "workspace:*"
+  },
+  "peerDependencies": {
+    "@rawsql-ts/adapter-node-pg": "workspace:^"
+  },
+  "peerDependenciesMeta": {
+    "@rawsql-ts/adapter-node-pg": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@rawsql-ts/adapter-node-pg": "workspace:^",
+    "@rawsql-ts/testkit-core": "workspace:^",
+    "@rawsql-ts/testkit-postgres": "workspace:^",
+    "@testcontainers/postgresql": "^10.28.0",
     "@types/diff": "^5.0.1",
     "@types/node": "^22.13.10",
+    "pg": "^8.11.1",
+    "testcontainers": "^10.28.0",
     "typescript": "^5.8.2",
     "vitest": "^4.0.7"
   },
@@ -45,12 +70,5 @@
     "templates",
     "AGENTS.md",
     "README.md"
-  ],
-  "scripts": {
-    "prebuild": "pnpm --filter @rawsql-ts/testkit-core build && pnpm --filter @rawsql-ts/testkit-postgres build && pnpm --filter @rawsql-ts/adapter-node-pg build",
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "lint": "eslint src --ext .ts",
-    "release": "npm run lint && npm run test && npm run build && npm pack --dry-run && npm publish --access public"
-  }
-}
+  ]
+}

package/templates/.editorconfig

@@ -1,16 +1,16 @@
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-indent_style = space
-indent_size = 2
-tab_width = 2
-insert_final_newline = true
-trim_trailing_whitespace = true
-
-[*.md]
-trim_trailing_whitespace = false
-
-[*.sql]
-indent_size = 2
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+tab_width = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.sql]
+indent_size = 2

package/templates/.prettierignore

@@ -1,2 +1,2 @@
-tests/generated/**
-
+tests/generated/**
+

package/templates/.prettierrc

@@ -1,24 +1,24 @@
-{
-  "semi": true,
-  "singleQuote": true,
-  "trailingComma": "all",
-  "tabWidth": 2,
-  "printWidth": 100,
-  "bracketSpacing": true,
-  "arrowParens": "always",
-  "plugins": ["prettier-plugin-sql"],
-  "overrides": [
-    {
-      "files": "*.sql",
-      "options": {
-        "parser": "sql"
-      }
-    },
-    {
-      "files": "*.md",
-      "options": {
-        "parser": "markdown"
-      }
-    }
-  ]
-}
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "printWidth": 100,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "plugins": ["prettier-plugin-sql"],
+  "overrides": [
+    {
+      "files": "*.sql",
+      "options": {
+        "parser": "sql"
+      }
+    },
+    {
+      "files": "*.md",
+      "options": {
+        "parser": "markdown"
+      }
+    }
+  ]
+}

package/templates/AGENTS.md

@@ -1,325 +1,30 @@
-# Appendix: Development Workflow Using Zero Table Dependency (ZTD)
-
-This application uses **Zero Table Dependency (ZTD)** as an internal development workflow for writing, testing, and maintaining SQL logic.
-ZTD is not part of the application's runtime behavior; rather, it provides a framework for:
-
-- Maintaining consistent SQL across the project
-- Keeping schema metadata and generated artifacts synchronized
-- Ensuring deterministic SQL unit tests
-- Enabling structured collaboration between humans and AI
-
-This section documents how ZTD is used inside this repository as a development methodology.
-
----
-
-## Defaults (important)
-
-- This project adopts **ZTD as the default development and testing methodology**.
-- ZTD is assumed unless explicitly stated otherwise.
-- Detailed rules about test execution modes are defined in `templates/tests/AGENTS.md`.
-
----
-
-## Generated files (important)
-
-- `tests/generated/` is auto-generated and must never be committed.
-- After cloning the repository (or in a clean environment), run `npx ztd ztd-config`.
-- If TypeScript reports missing modules or type errors because `tests/generated/` is missing, run `npx ztd ztd-config`.
-
----
-
-## TypeScript validation (required)
-
-After any code change, TypeScript type checking **must** be performed and must pass.
-
-- Run the project-appropriate typecheck command (e.g. `pnpm typecheck`).
-- If generated files are involved, run generators first, then re-run typecheck.
-- If typecheck fails, fix errors by root cause, not only the first reported error.
-- A change is not considered complete unless typecheck is green.
-CI pipelines SHOULD run `npx ztd ztd-config` before typecheck and tests (recommended).
-
-Rationale:  
-In ZTD-based development, many schema or SQL inconsistencies surface first as TypeScript errors via generated row maps and DTOs.
-Type checking is a primary correctness signal, not an optional step.
-
----
-
-## ZTD Implementation Guide (src/)
-
-The `src/` directory should contain pure TypeScript logic that operates on the row interfaces generated by `tests/generated/ztd-row-map.generated.ts`. Tests should import the row map, repositories should import DTOs, and fixtures must stay under `tests/`. Keep production code decoupled from the generated row map to preserve the distinction between implementation and test scaffolding.
-
-### Runtime dependency boundaries (important)
-
-- Code under `src/` MUST NOT import anything from `tests/` or `tests/generated/`.
-- Generated row-maps are test-only artifacts and MUST NEVER influence runtime behavior.
-- Mapper and writer runtime utilities MUST NOT depend on ZTD internals or generated helpers.
-- All schema compatibility checks (column existence, enum coverage, forbidden columns, etc.) MUST be enforced in tests, never in production code.
-
-### Repository Classes: What to Care About
-
-#### Scope and Responsibility
-- Repository classes are responsible for executing SQL and returning query results.
-- Avoid embedding business logic, thresholds, or data reshaping inside repositories.
-- Treat repositories as thin adapters over SQL.
-
-#### Mandatory testing rule (important)
-
-Whenever a repository class is created or modified, corresponding tests **must** be created or updated.
-
-Rules:
-- Every public repository method must be covered by tests.
-- Tests must call repository methods, not raw SQL files or SQL strings.
-- ZTD fixtures are the only allowed source of database state in tests.
-- A repository change without tests is considered incomplete.
-- Every repository or test modification must be followed by `pnpm --filter <package> test` (replace `<package>` with the template package name).
-  - `tests/support/global-setup.ts` already uses `@testcontainers/postgresql`, so the suite stands up a Postgres container automatically whenever `DATABASE_URL` is absent.
-  - If the suite fails, fix the root cause and rerun the command until it passes before considering the repository change complete.
-
-Rationale:  
-ZTD derives much of its value from deterministic, repository-level tests.
-Without tests, schema drift and SQL inconsistencies cannot be detected.
-
-#### SQL Management
-- Keep every SELECT statement in a dedicated `.sql` file under `src/sql/` (match the repository name, e.g. `src/sql/user-accounts.sql`).
-  - Load the SQL via `fs.readFileSync` or similar helpers so the repository never embeds long SQL strings inline.
-  - Inline SQL is forbidden unless a human explicitly requests an override; follow the `.sql` file convention by default.
-  - Repository classes should reference those SQL files; the file name should match the repository class or the query method to keep the code/spec alignment clear.
-
-#### Specifications and Documentation
-- If a markdown file with the same base name as the repository or SQL exists, read it before implementation.
-  - Such files may contain repository-local specifications (e.g. decision tables, thresholds, request/response notes).
-  - Naming should be aligned (e.g. `FooRepository.ts`, `foo.sql`, `foo.md`).
-
-#### Request and Response Contracts
-- Be explicit about request parameters (types, nullability, constraints).
-- Be explicit about response shape (columns, ordering, cardinality).
-- Prefer documenting contracts in the repository-local markdown file rather than code comments when they are non-trivial.
-
-### SqlClient lifecycle policy (important)
-
-- When using `src/db/sql-client.ts`, prefer a shared `SqlClient` per worker process (singleton).
-- Avoid creating a new database connection for every query or test case.
-- Do not share a live connection across parallel workers; each worker should own its own shared client or pool.
-- If you need strict isolation, create a dedicated client for that scope and close it explicitly.
-
-### Repository SQL and DTO policy (important)
-
-- Repository SQL must return application-facing DTO shapes.
-- SQL SELECT statements should alias columns to camelCase and match the repository return types.
-- Do not introduce intermediate `*Row` types when SQL already returns DTO-compatible shapes.
-- Define separate Row types only when SQL intentionally returns database-shaped (snake_case) rows, and always convert them explicitly.
-
----
-
-### Mapper + writer guardrails (template-specific)
-
-- In this project, `src/repositories/user-accounts.ts` is the authoritative mapper for the columns defined by the DDL; it MUST enumerate those columns explicitly so downstream logic never infers metadata at runtime.
-- Writer helpers in the same module MUST emit SQL for `public.user_account` only and MUST remain limited to the explicit insert/update/delete helpers shown there; DO NOT introduce ad-hoc schema discovery.
-- `tests/writer-constraints.test.ts` MUST consume `userAccountWriterColumnSets` together with `tests/generated/ztd-row-map.generated.ts` so CUD callers only reference columns that exist on `public.user_account`.
-- When the schema of `public.user_account` changes, update `src/repositories/user-accounts.ts` column metadata, keep `tests/writer-constraints.test.ts` expectations aligned, and re-run `npx ztd ztd-config` so the generated row map stays synchronized with the tests.
-
-#### Writer safety contract (important)
-
-- Allowed:
-  - Insert, update, and delete helpers tied to a single table with explicitly enumerated column sets.
-  - Explicit `RETURNING` clauses that list permitted columns.
-  - Patch-style updates that only touch writable columns listed in `userAccountWriterColumnSets`.
-- Forbidden:
-  - Generic writers that accept arbitrary table or column names.
-  - Runtime schema or enum discovery (e.g., querying `information_schema`) to drive writer column lists.
-  - Writers that embed joins or subqueries beyond simple `RETURNING` clauses.
-If these constraints are insufficient, write the SQL manually.
-
-#### Mapper strictness policy
-
-- Mapping is strict by default: SQL must return exactly the DTO-shaped results that `src/repositories/user-accounts.ts` exposes; missing or mismatched columns are bugs that tests MUST surface.
-- Non-strict behaviors (coercions, key transforms, etc.) MUST be enabled explicitly via named presets or configuration; relying on implicit or silent defaults is prohibited.
-
-### Sequence / identity column policy (important)
-
-- Sequence / identity columns (auto-generated IDs) are infrastructure concerns.
-- Do not explicitly assign values to sequence / identity columns in `INSERT` statements unless explicitly instructed.
-- Repository method inputs should omit sequence / identity columns by default.
-- Only treat an ID as input data when it represents a business rule (e.g. natural keys, externally assigned IDs).
-
-### No test-driven fallbacks in production code (important)
-
-- Do not add fallbacks in `src/` that exist only to accommodate ZTD/testkit/rewriter limitations.
-- If a query fails to be rewritten into ZTD form, do not change runtime behavior to compensate.
-- Report tooling issues with minimal reproduction and expected behavior.
-
-Rationale:  
-Production code must not diverge from intended SQL semantics due to tooling constraints.
-
----
-
-## ZTD Test Guide (tests/)
-
-Testing under ZTD follows dedicated, directory-scoped rules.
-
-- Test design, execution mode selection, and constraints are defined in:
-  - `templates/tests/AGENTS.md`
-- Tests validate repository behavior and returned DTOs.
-- Raw SQL files or SQL strings must not be tested directly.
-
----
-
-# ZTD Directory Layout
-
-```
-/ztd
-  /ddl
-    *.sql               <- physical schema definitions
-
-  README.md             <- documentation for the layout
-  AGENTS.md             <- combined guidance for DDL
-
-/src                    <- application & repository logic
-/tests                  <- ZTD tests, fixtures, row-maps
-```
-
-Only `ztd/ddl` is part of the template contract. Do not create or assume any other `ztd` subdirectories unless the project explicitly adds them.
-
-The file `tests/generated/ztd-layout.generated.ts` ensures ZTD CLI always points to the correct directories.
-
----
-
-# Protected directories and edit ownership (important)
-
-- DDL editing is human-led: `ztd/ddl/`
-- `ztd/ddl` is the sole human-owned directory inside `/ztd`; other directories must not be assumed or created without explicit instructions.
-- Application code is shared ownership: `src/`
-- Tests are shared ownership: `tests/`
-  - Detailed test constraints live in `templates/tests/AGENTS.md`.
-
-Additionally:
-- Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction.
-- When changes are required in human-led directories, prefer proposing a patch and explaining the impact before applying it.
-
----
-
-# Principles of ZTD in This Repository
-
-### 1. Humans own the definitions
-- Physical schema (DDL)
-- Repository interfaces
-
-### 2. AI assists with implementation
-- Generating repository SQL
-- Updating fixtures
-- Producing intermediate TypeScript structures
-- Ensuring SQL adheres to DDL
-
-### 3. ZTD enforces consistency
-ZTD tests verify that:
-- SQL logic matches DDL shapes
-
-If anything diverges, ZTD failures surface immediately and deterministically.
-
----
-
-# Development Workflows
-
-Different types of changes start from different entry points. Use the workflow appropriate for your situation.
-
----
-
-# Workflow A - Starting From DDL Changes
-Modifying tables, columns, constraints, indexes.
-
-1. Edit DDL files in `ztd/ddl/`.
-2. Run `npx ztd ztd-config`.
-3. Update repository SQL to match the new schema.
-4. Update fixtures if result shapes changed.
-5. Run tests.
-
-Flow: DDL to Repository SQL to Fixtures and Tests to Application
-
----
-
-# Workflow B - Starting From Repository Interface Changes
-Changing method signatures, adding new repository methods, etc.
-
-1. Modify the repository interface or implementation in `/src`.
-2. Use AI assistance to generate or update the SQL implementation.
-3. If the generated SQL conflicts with DDL or other human-maintained references, update the authoritative source first.
-4. Run ZTD tests.
-5. Regenerate config if SQL output shape changed.
-
-Flow: Interface to SQL to Tests
-
----
-
-# Workflow C - Starting From Repository SQL Logic Changes
-Bug fixes, refactoring, rewriting queries.
-
-1. Edit SQL inside the repository.
-2. Run ZTD tests.
-3. If intended behavior changes, coordinate any necessary DDL updates before adjusting dependent code.
-4. Update fixtures as needed.
-5. Regenerate config if result shape changed.
-
-Flow: SQL to Tests
-
----
-
-# Combined Real-World Examples
-
-- Adding a new contract state: DDL to SQL to config to tests
-- Adding a new table: DDL to SQL to fixtures/tests
-- Fixing business logic: SQL to tests
-
-ZTD ensures the development always converges into a consistent, validated workflow.
-
----
-
-# Human Responsibilities
-
-Humans maintain:
-
-- Schema definitions (`ztd/ddl`)
-- Repository interfaces and architectural decisions
-- Acceptance and review of AI-generated patches
-
-Humans decide what is correct.
-
----
-
-# AI Responsibilities
-
-AI must:
-
-- Use DDL as the physical structure constraint and never assume any additional `ztd` directories exist unless explicitly added.
-- Generate SQL consistent with DDL.
-- Update fixtures when needed.
-- Never modify `ztd/AGENTS.md` or `ztd/README.md` without explicit instruction.
-
-AI decides how to implement, but not what is correct.
-
----
-
-# ZTD CLI Responsibilities
-
-ZTD CLI:
-
-- Parses DDL to compute schema shapes
-- Rewrites SQL via CTE shadowing for testing
-- Generates `ztd-row-map.generated.ts`
-- Enables deterministic, parallel SQL unit tests
-
-ZTD is the verification engine that validates correctness beyond static typing.
-
----
-
-# Summary
-
-This appendix documents how ZTD is used strictly as an internal implementation and maintenance guide.
-It does not affect the runtime behavior of the application.
-Its purpose is ensuring:
-
-- Schema integrity
-- SQL correctness
-- Domain consistency
-- Reliable AI-assisted development
-
-With ZTD, humans define the meaning, AI writes the implementation, and tests guarantee correctness.
+# Package Scope
+- Applies to `packages/ztd-cli/templates`.
+- Defines repository-wide guardrails for generated project templates.
+- Provides parent rules for runtime (`src`), tests (`tests`), and metadata (`ztd`) without forcing one application style on every subtree.
+
+# Policy
+## REQUIRED
+- The nearest nested `AGENTS.md` MUST be treated as highest-priority policy for edited files.
+- Unknown facts during template work MUST be reported as `Not observed` with the next check.
+- Generated artifacts MUST remain unedited unless explicit instruction exists.
+- Preserve layer boundaries: transport, application, domain, and infrastructure concerns MUST remain explicit when those directories exist.
+- Human-owned contract directories (`ztd/ddl`, `src/catalog/specs`, `src/sql`) MUST NOT be semantically changed without explicit instruction.
+- Template output MUST include runnable test configuration at initialization.
+
+## ALLOWED
+- AI-assisted implementation MAY occur in infrastructure adapters, catalog runtime, and tests excluding `tests/generated`.
+
+## PROHIBITED
+- Manual edits under `tests/generated`.
+- Treating ZTD-specific workflow rules as repository-global rules.
+
+# Mandatory Workflow
+- Template changes MUST preserve an executable `pnpm test` path for initialized projects.
+
+# Hygiene
+- Keep directory-local deltas in child `AGENTS.md`; avoid restating parent rules in child files.
+
+# References
+- Rationale: [DESIGN.md](./DESIGN.md)
+- Operational notes: [DEV_NOTES.md](./DEV_NOTES.md)

package/templates/CONTEXT.md

@@ -0,0 +1,11 @@
+# Agent Context
+
+- Prefer `ztd --output json` in automation.
+- Treat this file as a high-level index only; rely on subtree `AGENTS.md` files for path-specific rules.
+- Prefer `ztd model-gen --probe-mode ztd` during the inner loop when local DDL is the source of truth.
+- Use `--dry-run` before file-writing commands when you need a safe validation pass.
+- Keep `ztd/ddl` as the human-owned schema source of truth.
+- Regenerate `tests/generated/*` with `ztd ztd-config`; do not edit generated files manually.
+- `ztd-cli` implicitly uses only `ZTD_TEST_DATABASE_URL`; it does not read `DATABASE_URL` automatically.
+- Treat `ddl pull` and `ddl diff` as explicit target inspection commands. Pass `--url` or a complete `--db-*` flag set when using them.
+- Keep transport, application, and domain work free from direct ZTD assumptions unless you are editing persistence infrastructure.

package/templates/CONTEXT.webapi.md

@@ -0,0 +1,11 @@
+# Agent Context
+
+- Treat this file as a top-level index for the layered WebAPI layout.
+- Keep `src/domain`, `src/application`, and `src/presentation/http` free from direct ZTD assumptions.
+- Apply ZTD-specific workflow rules only inside `src/infrastructure/persistence`, `src/sql`, `src/catalog`, and `ztd`.
+- Prefer `ztd model-gen --probe-mode ztd` during the inner loop when local DDL is the source of truth.
+- Use `--dry-run` before file-writing commands when you need a safe validation pass.
+- Keep `ztd/ddl` as the human-owned schema source of truth.
+- Regenerate `tests/generated/*` with `ztd ztd-config`; do not edit generated files manually.
+- `ztd-cli` implicitly uses only `ZTD_TEST_DATABASE_URL`; runtime settings such as `DATABASE_URL` remain outside its ownership.
+- Treat `ddl pull` and `ddl diff` as explicit target inspection commands. Pass `--url` or a complete `--db-*` flag set when using them.

package/templates/DESIGN.md

@@ -0,0 +1,17 @@
+# ZTD Template Design Notes
+
+## Role and Boundaries
+- Defines template-level design intent for ownership and runtime/test split.
+- Clarifies where human-owned contracts stop and implementation wiring begins.
+
+## Non-Goals
+- Replacing directory-local AGENTS contracts.
+- Embedding operational command playbooks.
+
+## Ownership Model
+- Human-owned directories preserve domain contracts and SQL intent.
+- AI-assisted directories implement runtime wiring and verification logic.
+
+## Runtime Split
+- `src/` contains runtime assets.
+- `tests/` and `ztd/` contain verification and generation inputs.

package/templates/DEV_NOTES.md

@@ -0,0 +1,14 @@
+# ZTD Template Dev Notes
+
+## Commands
+- `pnpm test` in initialized template projects.
+
+## Troubleshooting
+- Template initialization must include runnable test configuration and at least one executable test.
+
+## Navigation
+- `src/catalog/AGENTS.md`
+- `src/repositories/AGENTS.md`
+- `src/sql/AGENTS.md`
+- `tests/AGENTS.md`
+- `ztd/ddl/AGENTS.md`

package/templates/PROMPT_DOGFOOD.webapi.md

@@ -0,0 +1,49 @@
+# Prompt Dogfooding
+
+Use this checklist when you want to confirm that generic WebAPI requests stay focused on transport, application, and domain layers unless persistence work is explicitly requested.
+
+## Prompt 1
+
+Prompt:
+
+```text
+Convert to WebAPI
+```
+
+Expected focus:
+- `src/presentation/http`
+- `src/application`
+- `src/domain`
+
+Expected non-focus:
+- `src/sql`
+- `src/catalog`
+- `ztd/ddl`
+- `src/infrastructure/persistence`
+- `src/infrastructure/telemetry`
+
+## Prompt 2
+
+Prompt:
+
+```text
+Add SQL and implement repository
+```
+
+Expected focus:
+- `src/infrastructure/persistence/repositories`
+- `src/sql`
+- `src/catalog/specs`
+- `src/catalog/runtime`
+- `ztd/ddl`
+
+Expected non-focus:
+- unrelated HTTP transport rewrites
+- domain-wide refactors that are not required by the repository change
+
+## Record Template
+
+| Prompt | Primary files mentioned | Unwanted ZTD leakage? | Notes |
+| --- | --- | --- | --- |
+| `Convert to WebAPI` | | | |
+| `Add SQL and implement repository` | | | |