@rawsql-ts/ztd-cli 0.15.0 → 0.17.0

package/templates/dist/ztd-cli/templates/tests/user-profiles.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-profiles.test.js","sourceRoot":"","sources":["../../../../tests/user-profiles.test.ts"],"names":[],"mappings":";;AAAA,mCAAgD;AAEhD,6EAI2C;AAC3C,6DAA+D;AAC/D,qEAAqE;AAErE,SAAS,iBAAiB;IACxB,OAAO;QACL;YACE,eAAe,EAAE,CAAC;YAClB,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,mBAAmB;YAC1B,YAAY,EAAE,cAAc;YAC5B,UAAU,EAAE,sBAAsB;YAClC,UAAU,EAAE,sBAAsB;SACnC;QACD;YACE,eAAe,EAAE,CAAC;YAClB,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,mBAAmB;YAC1B,YAAY,EAAE,eAAe;YAC7B,UAAU,EAAE,sBAAsB;YAClC,UAAU,EAAE,sBAAsB;SACnC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB;IACxB,OAAO;QACL;YACE,UAAU,EAAE,GAAG;YACf,eAAe,EAAE,CAAC;YAClB,GAAG,EAAE,oCAAoC;YACzC,OAAO,EAAE,qBAAqB;YAC9B,QAAQ,EAAE,IAAI;SACf;KACF,CAAC;AACJ,CAAC;AAED,SAAS,aAAa;IACpB,OAAO;QACL,IAAA,oCAAY,EACV,qBAAqB,EACrB,iBAAiB,EAAE,EACnB,oCAAY,CAAC,qBAAqB,CAAC,CACpC;QACD,IAAA,oCAAY,EACV,qBAAqB,EACrB,iBAAiB,EAAE,EACnB,oCAAY,CAAC,qBAAqB,CAAC,CACpC;KACF,CAAC;AACJ,CAAC;AAED,IAAA,iBAAQ,EAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,IAAA,aAAI,EAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;QAC5D,MAAM,QAAQ,GAAG,aAAa,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,MAAM,IAAA,oCAAmB,EAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAA,gCAAgB,EAAC,MAAM,CAAC,CAAC;YAC9C,IAAA,eAAM,EAAC,MAAM,CAAC,CAAC,OAAO,CAAC;gBACrB;oBACE,aAAa,EAAE,CAAC;oBAChB,QAAQ,EAAE,OAAO;oBACjB,KAAK,EAAE,mBAAmB;oBAC1B,WAAW,EAAE,cAAc;oBAC3B,SAAS,EAAE,IAAI,IAAI,CAAC,sBAAsB,CAAC;oBAC3C,SAAS,EAAE,IAAI,IAAI,CAAC,sBAAsB,CAAC;oBAC3C,OAAO,EAAE;wBACP,SAAS,EAAE,GAAG;wBACd,aAAa,EAAE,CAAC;wBAChB,GAAG,EAAE,oCAAoC;wBACzC,OAAO,EAAE,qBAAqB;wBAC9B,QAAQ,EAAE,IAAI;qBACf;iBACF;gBACD;oBACE,aAAa,EAAE,CAAC;oBAChB,QAAQ,EAAE,OAAO;oBACjB,KAAK,EAAE,mBAAmB;oBAC1B,WAAW,EAAE,eAAe;oBAC5B,SAAS,EAAE,IAAI,IAAI,CAAC,sBAAsB,CAAC;oBAC3C,SAAS,EAAE,IAAI,IAAI,CAAC,sBAAsB,CAAC;oBAC3C,OAAO,EAAE,SAAS;iBACnB;aACF,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/templates/dist/ztd-cli/templates/tests/writer-constraints.test.d.ts

@@ -0,0 +1 @@
+export {};

package/templates/dist/ztd-cli/templates/tests/writer-constraints.test.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const ztd_row_map_generated_1 = require("./generated/ztd-row-map.generated");
+const user_accounts_1 = require("../src/repositories/user-accounts");
+const userColumns = new Set(Object.keys(ztd_row_map_generated_1.tableSchemas['public.user_account'].columns));
+(0, vitest_1.describe)('user_account writer columns', () => {
+    (0, vitest_1.test)('insert columns must exist on the canonical table', () => {
+        const { insertColumns } = user_accounts_1.userAccountWriterColumnSets;
+        const missing = insertColumns.filter((column) => !userColumns.has(column));
+        (0, vitest_1.expect)(missing).toEqual([]);
+        (0, vitest_1.expect)(insertColumns).toEqual(vitest_1.expect.arrayContaining(['username', 'email', 'display_name']));
+    });
+    (0, vitest_1.test)('update columns stay within allowed set and avoid immutable columns', () => {
+        const { updateColumns, immutableColumns } = user_accounts_1.userAccountWriterColumnSets;
+        const missing = updateColumns.filter((column) => !userColumns.has(column));
+        (0, vitest_1.expect)(missing).toEqual([]);
+        (0, vitest_1.expect)(updateColumns).not.toEqual(vitest_1.expect.arrayContaining([...immutableColumns]));
+    });
+    (0, vitest_1.test)('immutable columns reflect the DDL and are not targetted by updates', () => {
+        const { immutableColumns, updateColumns } = user_accounts_1.userAccountWriterColumnSets;
+        const missing = immutableColumns.filter((column) => !userColumns.has(column));
+        (0, vitest_1.expect)(missing).toEqual([]);
+        immutableColumns.forEach((column) => {
+            (0, vitest_1.expect)(updateColumns).not.toContain(column);
+        });
+    });
+});
+//# sourceMappingURL=writer-constraints.test.js.map

package/templates/dist/ztd-cli/templates/tests/writer-constraints.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-constraints.test.js","sourceRoot":"","sources":["../../../../tests/writer-constraints.test.ts"],"names":[],"mappings":";;AAAA,mCAAgD;AAChD,6EAAiE;AACjE,qEAAgF;AAEhF,MAAM,WAAW,GAAG,IAAI,GAAG,CACzB,MAAM,CAAC,IAAI,CAAC,oCAAY,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,CACzD,CAAC;AAEF,IAAA,iBAAQ,EAAC,6BAA6B,EAAE,GAAG,EAAE;IAC3C,IAAA,aAAI,EAAC,kDAAkD,EAAE,GAAG,EAAE;QAC5D,MAAM,EAAE,aAAa,EAAE,GAAG,2CAA2B,CAAC;QACtD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3E,IAAA,eAAM,EAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,IAAA,eAAM,EAAC,aAAa,CAAC,CAAC,OAAO,CAC3B,eAAM,CAAC,eAAe,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAC9D,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAA,aAAI,EAAC,oEAAoE,EAAE,GAAG,EAAE;QAC9E,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG,2CAA2B,CAAC;QACxE,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3E,IAAA,eAAM,EAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,IAAA,eAAM,EAAC,aAAa,CAAC,CAAC,GAAG,CAAC,OAAO,CAC/B,eAAM,CAAC,eAAe,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAC9C,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAA,aAAI,EAAC,oEAAoE,EAAE,GAAG,EAAE;QAC9E,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,GAAG,2CAA2B,CAAC;QACxE,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9E,IAAA,eAAM,EAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,gBAAgB,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE;YAClC,IAAA,eAAM,EAAC,aAAa,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC9C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/templates/dist/ztd-cli/templates/tests/ztd-layout.generated.d.ts

@@ -0,0 +1,7 @@
+declare const _default: {
+    ztdRootDir: string;
+    ddlDir: string;
+    enumsDir: string;
+    domainSpecsDir: string;
+};
+export default _default;

package/templates/dist/ztd-cli/templates/tests/ztd-layout.generated.js

@@ -0,0 +1,10 @@
+"use strict";
+// GENERATED FILE. DO NOT EDIT.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = {
+    ztdRootDir: 'ztd',
+    ddlDir: 'ztd/ddl',
+    enumsDir: 'ztd/enums',
+    domainSpecsDir: 'ztd/domain-specs',
+};
+//# sourceMappingURL=ztd-layout.generated.js.map

package/templates/dist/ztd-cli/templates/tests/ztd-layout.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ztd-layout.generated.js","sourceRoot":"","sources":["../../../../tests/ztd-layout.generated.ts"],"names":[],"mappings":";AAAA,+BAA+B;;AAE/B,kBAAe;IACb,UAAU,EAAE,KAAK;IACjB,MAAM,EAAE,SAAS;IACjB,QAAQ,EAAE,WAAW;IACrB,cAAc,EAAE,kBAAkB;CACnC,CAAC"}

package/templates/src/AGENTS.md

@@ -0,0 +1,26 @@
+# src AGENTS
+
+This directory is runtime application code.
+
+## Boundaries
+
+- Code under "src/" MUST NOT import from:
+  - "tests/"
+  - "tests/generated/"
+  - any test-only helpers
+- Runtime code MUST NOT depend on ZTD internals.
+- Generated artifacts are test-only signals, not runtime dependencies.
+
+## Implementation principles
+
+- Keep modules small and explicit.
+- Prefer explicit contracts over inference.
+- Favor deterministic behavior and clear error surfaces.
+
+## Verification (required)
+
+After changes:
+- Run the project typecheck command (example: "pnpm typecheck").
+- Run relevant tests (example: "pnpm test" or a filtered command).
+
+If you touched SQL contracts or catalog specs, run tests that exercise them.

package/templates/src/catalog/AGENTS.md

@@ -0,0 +1,37 @@
+# src/catalog AGENTS
+
+This directory is runtime code.
+
+## Purpose
+
+Catalog defines named query entry points by binding:
+- SQL assets ("src/sql/*.sql")
+- input parameter contracts
+- output DTO contracts
+- validation and mapping behavior
+- observability hooks (if supported)
+
+## Directory roles (important)
+
+- "src/catalog/specs": human-owned contracts (params + DTO + semantics)
+- "src/catalog/runtime": AI-assisted runtime wiring (executors, helpers, sinks)
+
+## Non-negotiable ownership
+
+- Specs are contracts. Do not infer, guess, widen, or narrow them.
+- Do not change params / DTO shapes in "specs" without explicit instruction.
+
+## Boundaries
+
+- Code under "src/catalog/" MUST NOT import from:
+  - "tests/"
+  - "tests/generated/"
+  - "ztd/"
+- Do not depend on ZTD internals at runtime.
+
+## Testing rule (required)
+
+Every spec MUST have tests that verify:
+- SQL executes under ZTD rewriting
+- mapping/validation behavior is correct (success and failure)
+- output DTO shape matches expectations

package/templates/src/catalog/runtime/AGENTS.md

@@ -0,0 +1,75 @@
+# src/catalog/runtime AGENTS
+
+This directory contains runtime wiring for catalog specs:
+- parameter validation entrypoints
+- row-to-DTO mapping
+- output validation
+
+## Runtime classification
+
+- This is a runtime directory.
+- Code here is executed/loaded by the application.
+
+## Responsibilities (critical)
+
+- Runtime MUST be the only place that:
+  - validates unknown inputs into typed params
+  - maps SQL rows (snake_case) into DTO objects
+  - validates DTO outputs before returning to repositories
+- Runtime output validation MUST follow the output contract type (DTO or scalar).
+- Command outputs MAY be scalar identifiers or `void`; DTO mapping is required only when the output contract is DTO.
+
+Repositories MUST call runtime helpers (ensure*/map*) and MUST NOT bypass them.
+
+## Validator requirement (required)
+
+- A validator library (zod or arktype) is always available.
+- Runtime MUST apply validators for:
+  - input params (unknown -> typed)
+  - outputs (mapped DTO -> validated DTO)
+
+Do not rely on TypeScript types alone.
+
+## SQL row normalization (important)
+
+SQL drivers may return different runtime representations for the same column types.
+Runtime MUST normalize driver-dependent values before validating DTOs.
+
+Required normalization rules:
+- Timestamp columns (e.g. timestamptz) may arrive as Date or string.
+  - Runtime MUST use `timestampFromDriver` from `@rawsql-ts/sql-contract`.
+  - Do NOT re-implement `normalizeTimestamp` locally.
+  - Do NOT call `new Date(...)` directly for driver-dependent timestamp normalization.
+- Numeric columns may arrive as number, string, or bigint depending on driver.
+  - Normalization rules MUST be explicit per contract and MUST NOT be silent.
+
+Never force SQL assets to encode driver-specific behavior.
+
+## Mapping rules (required)
+
+- Keep SQL assets snake_case and DTO-independent.
+- Mapping occurs in runtime:
+  - snake_case row -> DTO-shaped object
+  - apply normalization
+  - validate via spec-owned validator
+- DTO camelCase aliases in SQL are forbidden.
+
+## Entry points (recommended)
+
+Prefer these patterns:
+- `ensureXxxParams(value: unknown): XxxParams` (validate inputs)
+- `mapXxxRowToDto(row: XxxSqlRow): XxxDto` (normalize + validate outputs)
+
+The `map*` functions MUST always validate before returning.
+
+## Error behavior (required)
+
+- Validation errors must fail fast with clear messages.
+- Do not swallow validator errors.
+- Do not silently coerce invalid values unless explicitly defined by the contract.
+
+## Boundaries
+
+- Do not perform database I/O here.
+- Do not import from "tests/" or "tests/generated/".
+- Do not define human-owned contracts here; they live in "src/catalog/specs".

package/templates/src/catalog/runtime/_coercions.ts

@@ -0,0 +1 @@
+export { timestampFromDriver as normalizeTimestamp } from '@rawsql-ts/sql-contract';

package/templates/src/catalog/runtime/_smoke.runtime.ts

@@ -0,0 +1,21 @@
+import { parseSmokeOutput, type SmokeOutput } from '../specs/_smoke.spec';
+import { normalizeTimestamp } from './_coercions';
+
+/**
+ * Validate runtime output against the catalog smoke invariant.
+ */
+export function ensureSmokeOutput(value: unknown): SmokeOutput {
+  // Normalize driver-dependent timestamp representations before contract validation.
+  if (isRecord(value) && 'createdAt' in value) {
+    return parseSmokeOutput({
+      ...value,
+      createdAt: normalizeTimestamp(value.createdAt, 'createdAt')
+    });
+  }
+
+  return parseSmokeOutput(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/templates/src/catalog/specs/AGENTS.md

@@ -0,0 +1,48 @@
+# src/catalog/specs AGENTS
+
+This directory defines query and command specifications (contracts).
+
+## Runtime classification
+
+- This is a runtime directory.
+- Contents are human-owned contracts, not implementation details.
+
+## Ownership (critical)
+
+- Specs are human-owned.
+- Input parameters are part of the domain contract.
+- Output DTO shapes are part of the domain contract.
+- Cardinality and semantics are part of the domain contract.
+
+AI MUST NOT:
+- infer missing parameters
+- widen or narrow DTO shapes
+- change nullability or optionality
+- change CUD return shape implicitly
+
+Changes require explicit human instruction.
+
+## Validator requirement (required)
+
+- A validator library (zod or arktype) is always available.
+- Every spec MUST define validators for its public inputs/outputs.
+- Validators are part of the contract and are human-owned.
+
+## Driver variability policy (important)
+
+Specs MUST NOT require SQL assets to encode driver-specific workarounds.
+
+- Specs may acknowledge that SQL rows can vary in representation by driver
+  (e.g. timestamps as Date or string).
+- Normalization for driver-dependent values is implemented in catalog runtime,
+  then validated against the spec.
+
+Contracts define the final DTO shape.
+Runtime defines normalization steps to reach that shape.
+
+## What does NOT belong here
+
+- No executors
+- No database connections
+- No ZTD internals
+- No SQL camelCase aliasing rules (SQL rules live under src/sql)

package/templates/src/catalog/specs/_smoke.spec.arktype.ts

@@ -0,0 +1,21 @@
+import { type } from 'arktype';
+
+/**
+ * Validator invariant contract used to prove runtime validation wiring.
+ *
+ * This file is intentionally minimal and domain-agnostic.
+ */
+export const smokeOutputSchema = type({
+  id: 'number.integer',
+  createdAt: 'Date'
+});
+
+export type SmokeOutput = ReturnType<typeof smokeOutputSchema>;
+
+/**
+ * Parse and validate an unknown runtime payload.
+ */
+export function parseSmokeOutput(value: unknown): SmokeOutput {
+  smokeOutputSchema.assert(value);
+  return value as SmokeOutput;
+}

package/templates/src/catalog/specs/_smoke.spec.zod.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+
+/**
+ * Validator invariant contract used to prove runtime validation wiring.
+ *
+ * This file is intentionally minimal and domain-agnostic.
+ */
+export const smokeOutputSchema = z.object({
+  id: z.number().int(),
+  createdAt: z.date()
+});
+
+export type SmokeOutput = z.infer<typeof smokeOutputSchema>;
+
+/**
+ * Parse and validate an unknown runtime payload.
+ */
+export function parseSmokeOutput(value: unknown): SmokeOutput {
+  return smokeOutputSchema.parse(value);
+}

package/templates/src/db/sql-client.ts

@@ -9,16 +9,16 @@ export type SqlQueryRows<T> = Promise<T[]>;
 /**
  * Minimal SQL client interface required by the repository layer.
  *
- * - Production: adapt `pg` (or other drivers) to normalize results into `T[]`
- * - Tests: compatible with `pg-testkit` clients returned by `createTestkitClient()`
+ * - Production: adapt this interface to your preferred driver (pg, mysql2, etc.) and normalize the results to `T[]`.
+ * - Tests: replace the implementation with a mock, a fixture helper, or an adapter that follows this contract.
  *
  * Connection strategy note:
- * - Prefer a shared client per worker process for performance.
- * - Do not share a live client across parallel workers.
+ * - Prefer a shared client per worker process for better performance.
+ * - Do not share a live client across parallel workers without proper synchronization.
  */
 export type SqlClient = {
   query<T extends Record<string, unknown> = Record<string, unknown>>(
     text: string,
-    values?: readonly unknown[]
+    values?: readonly unknown[] | Record<string, unknown>
   ): SqlQueryRows<T>;
 };

package/templates/src/jobs/AGENTS.md

@@ -0,0 +1,26 @@
+# src/jobs AGENTS
+
+This folder contains script-like operations (procedural SQL execution).
+
+## Scope
+
+- Maintenance jobs
+- Data backfills
+- Batch operations
+- Temporary-table driven workflows
+
+## Safety rules
+
+- Be explicit about transaction boundaries.
+- Prefer idempotent design (safe to rerun).
+- Emit clear logs/events at start and end of the job.
+
+## SQL usage
+
+- It is acceptable to run multiple statements in a job (including temp tables).
+- Avoid coupling job logic to tests-only helpers.
+
+## Testing
+
+- Prefer integration-style tests that verify observable outcomes.
+- If the job is heavy, test smaller units or use fixtures to limit scope.

package/templates/src/jobs/README.md

@@ -0,0 +1,3 @@
+# Jobs
+
+Job runners that orchestrate repository or SQL workflows.

package/templates/src/repositories/AGENTS.md

@@ -0,0 +1,118 @@
+# src/repositories AGENTS
+
+This directory contains repository implementations.
+
+## Runtime classification
+
+- This is a runtime directory.
+- Code here is executed by the application.
+
+## Responsibilities
+
+Repositories orchestrate execution only.
+
+They are responsible for:
+- loading SQL assets from `src/sql`
+- validating external inputs via catalog runtime
+- binding parameters
+- calling `SqlClient`
+- mapping SQL rows to DTOs via catalog runtime
+- returning application-facing results
+
+Repositories MUST remain thin adapters over SQL.
+
+Repositories MUST NOT:
+- embed business rules
+- infer schema or DTO structure
+- compensate for driver limitations with extra queries
+
+## Contract boundaries (important)
+
+- Human-owned contracts live under "src/catalog/specs".
+- Runtime normalization and validation live under "src/catalog/runtime".
+- Repositories MUST NOT invent, infer, or modify contracts.
+
+If a contract is insufficient, update the spec/runtime first.
+
+## Mandatory runtime usage (required)
+
+Repositories MUST use catalog runtime helpers:
+- `ensure*Params` for all external inputs (`unknown -> typed`)
+- `map*RowToDto` for row-to-DTO mapping and output validation
+
+Repositories MUST NOT:
+- call spec validators directly
+- bypass runtime normalization
+- return DTOs without runtime validation
+- assume driver-specific runtime types (e.g. timestamps always `Date`)
+
+## SQL rules
+
+- SQL assets MUST remain DTO-independent.
+- SQL files MUST use snake_case column names.
+- Repositories MUST NOT push DTO aliasing into SQL.
+- Inline SQL strings are forbidden.
+- Repository SQL loading MUST be centralized in shared runtime/repository infrastructure.
+- Repositories MUST reference SQL assets by stable logical key (example: `user/insert_user.sql`).
+- Repository modules MUST NOT pass caller-relative paths (`./`, `../`) or absolute filesystem paths to SQL loaders.
+- The shared loader MUST resolve logical keys against the `src/sql` root (or catalog SQL registry), never relative to the caller file location.
+- Repository modules MUST NOT implement ad-hoc SQL file loading with `readFileSync`, `__dirname`, `import.meta.url`, or direct path resolution.
+
+## CUD default policy (important)
+
+Default policy for table-oriented CUD is:
+- CREATE SQL MAY use `RETURNING` for identifier columns only.
+- CREATE repository methods MUST return the generated identifier by default.
+- CREATE repository methods MUST NOT perform a follow-up SELECT whose purpose is DTO return shaping.
+- UPDATE/DELETE SQL MUST NOT use `RETURNING`.
+- repositories do NOT perform follow-up SELECTs after UPDATE/DELETE.
+- UPDATE/DELETE methods return `Promise<void>` by default.
+
+If a CREATE method must return a DTO, that requirement MUST be explicitly declared in catalog specs by human instruction.
+
+## CUD row count rules (non-negotiable)
+
+- UPDATE and DELETE MUST rely on driver-reported affected row counts (`rowCount` or equivalent).
+- Repositories MUST NOT use SQL `RETURNING` result presence/count as a substitute for affected row counts.
+- Repositories MUST NOT emulate affected rows using:
+  - pre-check SELECT
+  - post-check SELECT
+  - retry loops
+  - shadow queries / CTE hacks
+
+If `rowCount === 0`, repositories MUST throw an explicit error.
+
+If the driver cannot report affected row counts:
+- CUD verification is unsupported
+- tests MUST fail fast
+- do NOT add workaround logic in repositories
+
+## Read (SELECT) rules
+
+- SELECT methods may return:
+  - `T | null` for single-row queries
+  - `T[]` for multi-row queries
+- Absence of rows is NOT an error unless specified by the contract.
+
+## Error behavior
+
+- Propagate validation errors as failures.
+- Do not silently coerce invalid data.
+- Error messages SHOULD include operation name and identifying parameters.
+
+## Testing expectations
+
+- Every public repository method MUST be covered by tests.
+- Update/Delete tests MUST verify rowCount handling explicitly.
+- Repository changes without tests are incomplete.
+
+## Guiding principle
+
+Repositories execute contracts.
+They do not interpret intent.
+
+If correctness depends on extra queries to "confirm" changes:
+- the contract is wrong
+- or the driver is unsupported
+
+Fix the contract, not the repository.

package/templates/src/repositories/tables/AGENTS.md

@@ -0,0 +1,94 @@
+# src/repositories/tables AGENTS
+
+This directory contains simple CRUD-style repositories.
+
+## Runtime classification
+
+- This is a runtime directory.
+- Code here executes SQL and returns application-facing results.
+
+## Responsibilities
+
+- Execute SQL assets using defined contracts.
+- Perform explicit mapping from SQL rows to DTOs.
+- Enforce CUD semantics at the application boundary (including "0 rows" handling).
+
+## Contract ownership (important)
+
+- Input parameter types and DTO shapes are defined in specs ("src/catalog/specs").
+- Repositories MUST NOT invent or modify contracts.
+- Repositories may adapt SQL results into DTOs, but must not redefine the contract.
+
+## SQL usage rules (tables CRUD quality bar)
+
+- Repositories in this folder MUST treat SQL assets as human-maintained, idiomatic SQL.
+- Do not require SQL assets to implement driver-specific behaviors.
+- If a driver does not provide affected-row counts for UPDATE/DELETE, fail fast as unsupported.
+
+Examples:
+- Prefer a plain UPDATE statement in SQL.
+- Do not force SQL to return `affected_count` via CTE tricks.
+
+## CUD behavior rules
+
+### CREATE (INSERT)
+
+Default:
+- SQL MUST use `insert ... returning <primary_key>` when a generated key is needed.
+- Repository CREATE MUST return identifier only (scalar) per contract.
+- Repository CREATE MUST NOT perform a follow-up SELECT for DTO return shaping.
+- SQL MUST NOT return full rows or DTO-shaped payloads.
+
+Exception:
+- If a CREATE endpoint must return DTO, the spec MUST explicitly require it by human instruction.
+- Without that explicit contract, identifier-only return is mandatory.
+
+### UPDATE
+
+Default:
+- SQL: plain UPDATE without RETURNING.
+- Repository: determine success by affected row count when available.
+
+Driver variability handling:
+- If affected row count is unavailable:
+  - Treat UPDATE verification as unsupported for that driver/runtime.
+  - Throw an explicit error.
+- Do not add fallback checks or workaround logic in repositories.
+- Do not push this variability down into SQL assets.
+
+0-row rule (important):
+- Treat "0 rows updated" as a meaningful condition.
+- Default behavior is to surface it clearly (often an error), per spec.
+
+### DELETE
+
+Default:
+- SQL: plain DELETE without RETURNING.
+- Repository: determine success by affected row count when available.
+
+Driver variability handling:
+- If affected row count is unavailable:
+  - Treat DELETE verification as unsupported for that driver/runtime.
+  - Throw an explicit error.
+- Do not add fallback checks or workaround logic in repositories.
+
+0-row rule (important):
+- Treat "0 rows deleted" as a meaningful condition, per spec.
+
+## Patch updates (important)
+
+- Avoid ambiguous patterns such as `coalesce(param, column)` by default.
+- Contracts should distinguish:
+  - "not provided"
+  - "explicitly set to null"
+- If patch semantics are needed, implement them explicitly via:
+  - separate SQL variants, or
+  - explicit contract types that preserve intent.
+
+## Testing rule (required)
+
+- Every public repository method MUST be covered by tests.
+- Tests should verify:
+  - correct mapping behavior
+  - correct "0 rows" behavior for UPDATE/DELETE
+  - correct error surfaces (do not silently succeed)

package/templates/src/repositories/tables/README.md

@@ -0,0 +1,3 @@
+# Table Repositories
+
+Write-focused repositories that execute CRUD SQL from `src/sql`.

package/templates/src/repositories/views/AGENTS.md

@@ -0,0 +1,25 @@
+# src/repositories/views AGENTS
+
+This folder is for complex read-only queries.
+
+## Scope
+
+- Complex SELECT queries (joins, aggregations, window functions).
+- Read models that are not 1:1 with a single table.
+
+## Allowed
+
+- Multi-table joins and aggregations.
+- Purpose-built DTOs for read models.
+- Validation at the boundary (catalog validator or repository-level validator).
+
+## Forbidden
+
+- INSERT/UPDATE/DELETE in this folder by default.
+- Hidden write side-effects.
+
+## Guidance
+
+- Keep query intent clear in naming.
+- Document cardinality assumptions (one, many, optional).
+- Prefer stable ordering if tests rely on order.

package/templates/src/repositories/views/README.md

@@ -0,0 +1,3 @@
+# View Repositories
+
+Read-only repositories backed by SELECT SQL in `src/sql`.