feat(database-design): add soft-delete query filters and helpers

Implements the soft-delete pattern that pipeline.config.json enables by
default (database.softDeleteDefault: true) but was previously unimplemented.

- Add nullable deletedAt column to the shared users schema template
- Add shared db/soft-delete.ts with notDeleted, withSoftDeleteFilter,
  softDelete, and restore helpers (generic over postgres-js and neon-http)
- Add a node users route demonstrating DELETE -> softDelete and the
  ?include_deleted=true admin query param
- Add tests asserting generated SQL for each helper
- Document soft-delete column/helper/route generation in the
  database-design skill, gated on softDeleteDefault

Closes #53

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: PAMulligan

.claude/skills/database-design/SKILL.md

@@ -173,6 +173,7 @@ import {
   text,
   timestamp,
   uniqueIndex,
+  index,
 } from 'drizzle-orm/pg-core';
 import { relations } from 'drizzle-orm';
 import { userRoleEnum } from './enums';
@@ -193,9 +194,14 @@ export const users = pgTable(
       .defaultNow()
       .notNull()
       .$onUpdate(() => new Date()),
+    // Soft-delete marker — only emitted when `database.softDeleteDefault` is
+    // true in pipeline.config.json. Null = active; a timestamp = soft-deleted.
+    deletedAt: timestamp('deleted_at', { withTimezone: true }),
   },
   (table) => [
     uniqueIndex('users_email_idx').on(table.email),
+    // Partial index keeps the common "active rows" lookups fast.
+    index('users_deleted_at_idx').on(table.deletedAt),
   ],
 );
 
@@ -349,6 +355,136 @@ export const orderItemsRelations = relations(orderItems, ({ one }) => ({
 }));
 ```
 
+### Step 6.5 -- Soft Delete Columns & Helpers (when enabled)
+
+Gate this step on `pipeline.config.json` -> `database.softDeleteDefault`. When it
+is `true` (the default), every table that represents a deletable resource gets a
+nullable `deletedAt` column and the build emits a shared soft-delete helper
+module. Skip this step entirely when `softDeleteDefault` is `false`.
+
+```typescript
+// Read the flag from pipeline.config.json before generating schemas
+import { readFile } from 'fs/promises';
+import path from 'path';
+
+const pipelineConfig = JSON.parse(
+  await readFile(
+    path.join(process.cwd(), '.claude', 'pipeline.config.json'),
+    'utf-8',
+  ),
+);
+const softDeleteEnabled: boolean = pipelineConfig.database?.softDeleteDefault ?? false;
+```
+
+**1. Add the column to each soft-deletable table.** Use a nullable timestamp
+(no default) plus a supporting index — see the `deletedAt` column and
+`users_deleted_at_idx` in the Users example above. Pure join/pivot tables
+(e.g. `order_items`) are usually hard-deleted with their parent and can be left
+out.
+
+**2. Generate the shared helper module** at `api/src/db/soft-delete.ts`. This is
+the single source of truth for the soft-delete query filter and write helpers:
+
+```typescript
+// api/src/db/soft-delete.ts
+import {
+  and,
+  eq,
+  isNull,
+  type Column,
+  type SQL,
+  type TablesRelationalConfig,
+} from 'drizzle-orm';
+import type {
+  PgColumn,
+  PgDatabase,
+  PgQueryResultHKT,
+  PgTable,
+  PgUpdateSetSource,
+} from 'drizzle-orm/pg-core';
+
+export interface SoftDeletable {
+  deletedAt: Column;
+}
+
+export type SoftDeletableTable = PgTable & SoftDeletable & { id: PgColumn };
+
+/** WHERE filter that hides soft-deleted rows (`deleted_at IS NULL`). */
+export function notDeleted(table: SoftDeletable): SQL {
+  return isNull(table.deletedAt);
+}
+
+/**
+ * Hide soft-deleted rows unless an admin explicitly asks for them via
+ * `?include_deleted=true`. An optional `extra` clause is AND-ed in.
+ */
+export function withSoftDeleteFilter(
+  table: SoftDeletable,
+  includeDeleted: boolean,
+  extra?: SQL,
+): SQL | undefined {
+  if (includeDeleted) {
+    return extra;
+  }
+  const active = notDeleted(table);
+  return extra ? and(active, extra) : active;
+}
+
+/** Soft-delete one row by id: stamps `deletedAt` instead of removing it. */
+export function softDelete<
+  TQueryResult extends PgQueryResultHKT,
+  TFullSchema extends Record<string, unknown>,
+  TSchema extends TablesRelationalConfig,
+>(db: PgDatabase<TQueryResult, TFullSchema, TSchema>, table: SoftDeletableTable, id: string) {
+  return db
+    .update(table)
+    .set({ deletedAt: new Date() } as PgUpdateSetSource<SoftDeletableTable>)
+    .where(eq(table.id, id));
+}
+
+/** Restore a soft-deleted row by clearing `deletedAt`. */
+export function restore<
+  TQueryResult extends PgQueryResultHKT,
+  TFullSchema extends Record<string, unknown>,
+  TSchema extends TablesRelationalConfig,
+>(db: PgDatabase<TQueryResult, TFullSchema, TSchema>, table: SoftDeletableTable, id: string) {
+  return db
+    .update(table)
+    .set({ deletedAt: null } as PgUpdateSetSource<SoftDeletableTable>)
+    .where(eq(table.id, id));
+}
+```
+
+**3. Use the helpers in read and delete routes.** `route-generation` (Phase 3)
+consumes these helpers so generated handlers filter deleted rows by default and
+expose `?include_deleted=true` on admin/list endpoints:
+
+```typescript
+import { eq } from 'drizzle-orm';
+import { db } from '../db';
+import { users } from '../db/schema';
+import { restore, softDelete, withSoftDeleteFilter } from '../db/soft-delete';
+
+// GET /users — active rows only; ?include_deleted=true reveals soft-deleted rows
+const includeDeleted = c.req.query('include_deleted') === 'true';
+const rows = await db
+  .select()
+  .from(users)
+  .where(withSoftDeleteFilter(users, includeDeleted));
+
+// DELETE /users/:id — soft delete instead of a hard DELETE
+const [deleted] = await softDelete(db, users, c.req.param('id')).returning();
+if (!deleted) return c.json({ error: 'User not found' }, 404);
+return c.json({ message: 'User deleted' });
+
+// POST /users/:id/restore — admin un-delete
+const [restored] = await restore(db, users, c.req.param('id')).returning();
+```
+
+**4. Keep `deletedAt` out of write validators.** When generating Zod schemas in
+Step 8, `deletedAt` is server-managed: omit it from insert/update schemas exactly
+like `id`, `createdAt`, and `updatedAt`.
+
 ### Step 7 -- Generate Barrel Export
 
 ```typescript
@@ -379,6 +515,7 @@ export const insertUserSchema = createInsertSchema(users, {
   id: true,
   createdAt: true,
   updatedAt: true,
+  deletedAt: true, // server-managed soft-delete marker (when softDeleteDefault)
   passwordHash: true,
 });
 
@@ -560,6 +697,7 @@ cd api && pnpm add -D drizzle-kit drizzle-zod
 | Schema files | `api/src/db/schema/*.ts` | One Drizzle pgTable per model |
 | Enum definitions | `api/src/db/schema/enums.ts` | PostgreSQL enum types |
 | Schema barrel | `api/src/db/schema/index.ts` | Re-exports all schemas |
+| Soft-delete helpers | `api/src/db/soft-delete.ts` | `notDeleted`, `withSoftDeleteFilter`, `softDelete`, `restore` (when `softDeleteDefault`) |
 | DB connection | `api/src/db/index.ts` | Drizzle client setup |
 | Zod validators | `api/src/validators/*.ts` | Insert/select/update schemas |
 | Drizzle config | `api/drizzle.config.ts` | Migration configuration |
@@ -583,4 +721,5 @@ cd api && pnpm add -D drizzle-kit drizzle-zod
 - **Zod inference from Drizzle**: Single source of truth -- change the Drizzle schema, the Zod validators follow automatically.
 - **UUID primary keys**: Default for all tables. Avoids sequential ID enumeration attacks and works well in distributed systems.
 - **Soft timestamps**: `createdAt` and `updatedAt` on every table. `$onUpdate` handles automatic timestamp refresh.
+- **Soft deletes by default**: when `database.softDeleteDefault` is true, deletable tables get a nullable `deletedAt` column and a shared `soft-delete.ts` helper module instead of issuing hard `DELETE`s. Reads filter with `notDeleted`/`withSoftDeleteFilter`, deletes stamp `deletedAt` via `softDelete`, and `?include_deleted=true` exposes deleted rows to admin endpoints. Set the flag to `false` to opt back into hard deletes.
 - **snake_case columns**: PostgreSQL convention. Drizzle maps to camelCase in TypeScript automatically.

templates/snippets/node/src/routes/users.ts

@@ -0,0 +1,66 @@
+import { Hono } from 'hono';
+import { eq } from 'drizzle-orm';
+import { db } from '../db/client.js';
+import { users } from '../db/schema.js';
+import { restore, softDelete, withSoftDeleteFilter } from '../db/soft-delete.js';
+
+/**
+ * Example resource routes demonstrating the soft-delete pattern.
+ *
+ * Wire these into the app where a database is available:
+ *
+ *   import { usersRoutes } from './routes/users';
+ *   app.route('/users', usersRoutes);
+ *
+ * Soft-delete rules of thumb:
+ *   - Reads filter out deleted rows with `withSoftDeleteFilter` / `notDeleted`.
+ *   - `?include_deleted=true` lets admin callers see soft-deleted rows.
+ *   - DELETE stamps `deleted_at` via `softDelete` instead of removing the row.
+ *   - A restore endpoint clears `deleted_at` via `restore`.
+ */
+export const usersRoutes = new Hono()
+  // GET /users — list active users. Admins pass ?include_deleted=true for all.
+  .get('/', async (c) => {
+    const includeDeleted = c.req.query('include_deleted') === 'true';
+    const rows = await db
+      .select()
+      .from(users)
+      .where(withSoftDeleteFilter(users, includeDeleted));
+    return c.json({ users: rows, total: rows.length });
+  })
+
+  // GET /users/:id — fetch one user. Soft-deleted rows return 404 unless
+  // ?include_deleted=true is supplied.
+  .get('/:id', async (c) => {
+    const id = c.req.param('id');
+    const includeDeleted = c.req.query('include_deleted') === 'true';
+    const rows = await db
+      .select()
+      .from(users)
+      .where(withSoftDeleteFilter(users, includeDeleted, eq(users.id, id)));
+    const user = rows[0];
+    if (!user) {
+      return c.json({ error: 'User not found' }, 404);
+    }
+    return c.json(user);
+  })
+
+  // DELETE /users/:id — soft delete: stamps deleted_at instead of removing.
+  .delete('/:id', async (c) => {
+    const id = c.req.param('id');
+    const [deleted] = await softDelete(db, users, id).returning();
+    if (!deleted) {
+      return c.json({ error: 'User not found' }, 404);
+    }
+    return c.json({ message: 'User deleted' });
+  })
+
+  // POST /users/:id/restore — admin action to undo a soft delete.
+  .post('/:id/restore', async (c) => {
+    const id = c.req.param('id');
+    const [restored] = await restore(db, users, id).returning();
+    if (!restored) {
+      return c.json({ error: 'User not found' }, 404);
+    }
+    return c.json(restored);
+  });

templates/snippets/shared/src/db/schema.ts

@@ -6,4 +6,8 @@ export const users = pgTable('users', {
   name: text('name').notNull(),
   createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
   updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
+  // Soft-delete marker. Null means the row is active; a timestamp marks when it
+  // was soft-deleted. Filter active rows with `notDeleted(users)` from
+  // ./soft-delete and remove rows with `softDelete(db, users, id)`.
+  deletedAt: timestamp('deleted_at', { withTimezone: true }),
 });

templates/snippets/shared/src/db/soft-delete.ts

@@ -0,0 +1,124 @@
+import {
+  and,
+  eq,
+  isNull,
+  type Column,
+  type SQL,
+  type TablesRelationalConfig,
+} from 'drizzle-orm';
+import type {
+  PgColumn,
+  PgDatabase,
+  PgQueryResultHKT,
+  PgTable,
+  PgUpdateSetSource,
+} from 'drizzle-orm/pg-core';
+
+/**
+ * Soft-delete helpers.
+ *
+ * Soft deletes are enabled by default in `pipeline.config.json`
+ * (`database.softDeleteDefault: true`). Tables opt in by adding a nullable
+ * `deletedAt` timestamp column (see `users` in ./schema). A null `deletedAt`
+ * means the row is active; a timestamp marks when it was soft-deleted.
+ *
+ * Instead of issuing `DELETE`, callers stamp `deletedAt` so rows can be
+ * filtered out of normal reads and optionally restored later. Use `notDeleted`
+ * (or `withSoftDeleteFilter` for admin `?include_deleted=true` access) in every
+ * read query, and `softDelete` / `restore` for writes.
+ */
+
+/**
+ * Minimal shape of a table that supports soft deletes: it must expose a
+ * `deletedAt` column. This is all `notDeleted` / `withSoftDeleteFilter` need.
+ */
+export interface SoftDeletable {
+  deletedAt: Column;
+}
+
+/**
+ * A soft-deletable table that also exposes an `id` primary key. Required by the
+ * `softDelete` / `restore` helpers, which target a single row by id.
+ */
+export type SoftDeletableTable = PgTable & SoftDeletable & { id: PgColumn };
+
+/**
+ * Drizzle `where` filter that excludes soft-deleted rows (`deleted_at IS NULL`).
+ *
+ * @example
+ *   const active = await db.select().from(users).where(notDeleted(users));
+ */
+export function notDeleted(table: SoftDeletable): SQL {
+  return isNull(table.deletedAt);
+}
+
+/**
+ * Build a `where` clause that hides soft-deleted rows unless they are explicitly
+ * requested — e.g. an admin endpoint passing `?include_deleted=true`. An
+ * optional `extra` filter (such as `eq(users.id, id)`) is combined with the
+ * soft-delete filter via `AND`.
+ *
+ * Returns `undefined` only when `includeDeleted` is true and no `extra` filter
+ * is supplied, which Drizzle treats as "no filter".
+ *
+ * @example
+ *   db.select().from(users)
+ *     .where(withSoftDeleteFilter(users, includeDeleted, eq(users.id, id)));
+ */
+export function withSoftDeleteFilter(
+  table: SoftDeletable,
+  includeDeleted: boolean,
+  extra?: SQL,
+): SQL | undefined {
+  if (includeDeleted) {
+    return extra;
+  }
+  const active = notDeleted(table);
+  return extra ? and(active, extra) : active;
+}
+
+/**
+ * Soft-delete a single row by id: sets `deletedAt` to the current time instead
+ * of removing the row. Returns the Drizzle update query so callers can chain
+ * `.returning()` and inspect whether a row was affected (404 vs success).
+ *
+ * @example
+ *   const [deleted] = await softDelete(db, users, id).returning();
+ *   if (!deleted) return c.json({ error: 'Not found' }, 404);
+ */
+export function softDelete<
+  TQueryResult extends PgQueryResultHKT,
+  TFullSchema extends Record<string, unknown>,
+  TSchema extends TablesRelationalConfig,
+>(
+  db: PgDatabase<TQueryResult, TFullSchema, TSchema>,
+  table: SoftDeletableTable,
+  id: string,
+) {
+  return db
+    .update(table)
+    .set({ deletedAt: new Date() } as PgUpdateSetSource<SoftDeletableTable>)
+    .where(eq(table.id, id));
+}
+
+/**
+ * Restore a previously soft-deleted row by clearing its `deletedAt`. Returns the
+ * Drizzle update query so callers can chain `.returning()`.
+ *
+ * @example
+ *   const [restored] = await restore(db, users, id).returning();
+ */
+export function restore<
+  TQueryResult extends PgQueryResultHKT,
+  TFullSchema extends Record<string, unknown>,
+  TSchema extends TablesRelationalConfig,
+>(
+  db: PgDatabase<TQueryResult, TFullSchema, TSchema>,
+  table: SoftDeletableTable,
+  id: string,
+) {
+  return db
+    .update(table)
+    .set({ deletedAt: null } as PgUpdateSetSource<SoftDeletableTable>)
+    .where(eq(table.id, id));
+}