pipework 0.252.0 → 0.252.1

package/src/infra/webhook/outbound.ts

@@ -0,0 +1,315 @@
+import { sql } from '../../data/db/sql.js'
+import type { DB } from '../../data/db/index.js'
+import { signPayload, type WebhookSignatureOptions } from './sign.js'
+import { untrustedPost } from '../fetch/handle.js'
+import type { FetchTarget } from '../fetch/handle.js'
+import type { Socket } from 'node:net'
+import { unscopedExecutor, scopedExecutor, requireUnscopedExecutor } from '../../auth/tenant/scoped-db.js'
+
+export interface OutboundWebhookConfig {
+  table?: string
+  deliveryTable?: string
+  signing?: WebhookSignatureOptions
+  retry?: {
+    maxAttempts?: number
+    initialDelayMs?: number
+    maxDelayMs?: number
+  }
+  timeoutMs?: number
+  /**
+   * Where deliveries may go. `'public'` (default): only public addresses; a private, loopback or link-local address, a name
+   * resolving to one, or a redirect is refused and recorded on the delivery row's `error` column. `'any'`: for an app that
+   * sends webhooks to its own internal services; redirects are still not followed and the kept response is still capped.
+   * `'any'` throws at creation when `environment` is `production`.
+   */
+  addresses?: 'public' | 'any'
+  /** The app's environment (`config.environment`); `addresses: 'any'` is refused when it is `production`. */
+  environment?: string
+  /** For tests: replaces DNS and the socket of the `'public'` path, as `untrustedFetch.get` takes them. The address check still runs. */
+  network?: {
+    resolve: (hostname: string) => Promise<string[]>
+    connect: (target: FetchTarget) => Socket
+  }
+}
+
+export interface WebhookEndpoint {
+  id: string
+  tenantId: string
+  url: string
+  secret: string
+  events: string[]
+  active: boolean
+}
+
+export interface DeliveryAttempt {
+  id: string
+  endpointId: string
+  tenantId: string
+  eventType: string
+  payload: unknown
+  statusCode: number | null
+  responseBody: string | null
+  attempt: number
+  maxAttempts: number
+  nextRetryAt: Date | null
+  createdAt: Date
+}
+
+export interface OutboundWebhook {
+  ensureTables(db: DB): Promise<void>
+  send(db: DB, tenantId: string, eventType: string, payload: unknown): Promise<string[]>
+  deliver(db: DB, deliveryId: string): Promise<{ success: boolean; statusCode: number | null }>
+  processPending(db: DB): Promise<number>
+  registerEndpoint(db: DB, endpoint: Omit<WebhookEndpoint, 'id' | 'events'> & { events: readonly string[] }): Promise<string>
+  listEndpoints(db: DB, tenantId: string): Promise<WebhookEndpoint[]>
+  removeEndpoint(db: DB, tenantId: string, endpointId: string): Promise<boolean>
+}
+
+/** The delivery table `createOutboundWebhook` uses unless `deliveryTable` is set. */
+export const DEFAULT_WEBHOOK_DELIVERY_TABLE = '__pipework_webhook_deliveries'
+
+const DEFAULTS = {
+  table: '__pipework_webhook_endpoints',
+  deliveryTable: DEFAULT_WEBHOOK_DELIVERY_TABLE,
+  maxAttempts: 5,
+  initialDelayMs: 1000,
+  maxDelayMs: 3_600_000,
+  timeoutMs: 30_000,
+} as const
+
+/** The most of an endpoint's response kept on the delivery row. */
+const RESPONSE_BODY_CAP = 64 * 1024
+
+/** What a refused or failed attempt is recorded as on the delivery row's `error` column. */
+type AttemptError = 'address' | 'scheme' | 'redirects' | 'network' | 'timeout' | 'too_large' | 'status' | 'rejected'
+
+interface Attempt { statusCode: number | null; responseBody: string | null; success: boolean; error: AttemptError | null }
+
+/** Plain fetch, for `addresses: 'any'`: no redirect followed, the kept body capped, one time limit. */
+async function sendAnywhere(url: string, headers: Record<string, string>, body: string, timeoutMs: number): Promise<Attempt> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetch(url, { method: 'POST', headers, body, signal: controller.signal, redirect: 'manual' })
+    const statusCode = response.status
+    if (statusCode >= 300 && statusCode < 400) {
+      await response.body?.cancel().catch(() => undefined)
+      return { statusCode, responseBody: null, success: false, error: 'redirects' }
+    }
+    const success = statusCode >= 200 && statusCode < 300
+    const chunks: Buffer[] = []
+    let total = 0
+    let over = false
+    const reader = response.body?.getReader()
+    try {
+      while (reader !== undefined) {
+        const { done, value } = await reader.read()
+        if (done) break
+        total += value.length
+        if (total > RESPONSE_BODY_CAP) { over = true; break }
+        chunks.push(Buffer.from(value))
+      }
+    } catch { /* a body that breaks is not kept; the status decides */ }
+    await reader?.cancel().catch(() => undefined)
+    return { statusCode, responseBody: over ? null : Buffer.concat(chunks).toString('utf8'), success, error: null }
+  } catch {
+    return { statusCode: null, responseBody: null, success: false, error: controller.signal.aborted ? 'timeout' : 'network' }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export function createOutboundWebhook(config: OutboundWebhookConfig = {}): OutboundWebhook {
+  const endpointTable = config.table ?? DEFAULTS.table
+  const deliveryTable = config.deliveryTable ?? DEFAULTS.deliveryTable
+  const maxAttempts = config.retry?.maxAttempts ?? DEFAULTS.maxAttempts
+  const initialDelayMs = config.retry?.initialDelayMs ?? DEFAULTS.initialDelayMs
+  const maxDelayMs = config.retry?.maxDelayMs ?? DEFAULTS.maxDelayMs
+  const timeoutMs = config.timeoutMs ?? DEFAULTS.timeoutMs
+  const signingOptions = config.signing ?? {}
+  const addresses = config.addresses ?? 'public'
+  if (addresses === 'any' && config.environment === 'production') {
+    throw new Error(
+      '[pipework] webhook.createOutbound: `addresses: \'any\'` is refused when the environment is production, because a tenant-registered URL could then reach the app\'s private network (cloud metadata, internal services). '
+      + 'Fix: remove `addresses` so deliveries go to public addresses only, or set it only outside production.\n',
+    )
+  }
+
+  return {
+    async ensureTables(handle) {
+      const db = unscopedExecutor(handle).db
+      await db.execute(sql.raw(`
+        CREATE TABLE IF NOT EXISTS ${endpointTable} (
+          id TEXT NOT NULL PRIMARY KEY DEFAULT gen_random_uuid()::text,
+          tenant_id TEXT NOT NULL,
+          url TEXT NOT NULL,
+          secret TEXT NOT NULL,
+          events TEXT[] NOT NULL DEFAULT '{}',
+          active BOOLEAN NOT NULL DEFAULT true,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        )
+      `))
+
+      await db.execute(sql.raw(`
+        CREATE TABLE IF NOT EXISTS ${deliveryTable} (
+          id TEXT NOT NULL PRIMARY KEY DEFAULT gen_random_uuid()::text,
+          endpoint_id TEXT NOT NULL,
+          tenant_id TEXT NOT NULL,
+          event_type TEXT NOT NULL,
+          payload JSONB NOT NULL,
+          status_code INTEGER,
+          response_body TEXT,
+          error TEXT,
+          attempt INTEGER NOT NULL DEFAULT 0,
+          max_attempts INTEGER NOT NULL,
+          next_retry_at TIMESTAMPTZ,
+          completed_at TIMESTAMPTZ,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        )
+      `))
+      await db.execute(sql.raw(`ALTER TABLE ${deliveryTable} ADD COLUMN IF NOT EXISTS error TEXT`))
+    },
+
+    async send(handle, tenantId, eventType, payload) {
+      const db = scopedExecutor(handle, tenantId, 'webhook.send()').db
+      const endpoints: unknown[] = await db.execute(
+        sql`SELECT id, url, secret FROM ${sql.raw(endpointTable)}
+            WHERE tenant_id = ${tenantId}
+              AND active = true
+              AND (events = '{}' OR ${eventType} = ANY(events))`,
+      )
+
+      const deliveryIds: string[] = []
+      for (const row of endpoints as { id: string }[]) {
+        const result: unknown[] = await db.execute(
+          sql`INSERT INTO ${sql.raw(deliveryTable)} (endpoint_id, tenant_id, event_type, payload, max_attempts, next_retry_at)
+              VALUES (${row.id}, ${tenantId}, ${eventType}, ${JSON.stringify(payload)}, ${maxAttempts}, now())
+              RETURNING id`,
+        )
+        const inserted = (result as { id: string }[])[0]
+        if (inserted !== undefined) deliveryIds.push(inserted.id)
+      }
+
+      return deliveryIds
+    },
+
+    async deliver(handle, deliveryId) {
+      const db = requireUnscopedExecutor(handle, 'webhook.deliver()', 'a delivery is looked up by id across tenants')
+      const rows: unknown[] = await db.execute(
+        sql`SELECT d.id, d.endpoint_id, d.event_type, d.payload, d.attempt, d.max_attempts,
+                   e.url, e.secret
+            FROM ${sql.raw(deliveryTable)} d
+            JOIN ${sql.raw(endpointTable)} e ON e.id = d.endpoint_id
+            WHERE d.id = ${deliveryId} AND d.completed_at IS NULL`,
+      )
+
+      const delivery = (rows as Record<string, unknown>[])[0]
+      if (delivery === undefined) return { success: false, statusCode: null }
+
+      const attempt = (delivery['attempt'] as number) + 1
+      const signed = signPayload(delivery['payload'], delivery['secret'] as string, signingOptions)
+
+      const headers = {
+        'Content-Type': 'application/json',
+        'X-Webhook-Id': signed.messageId,
+        'X-Webhook-Timestamp': signed.timestamp.toString(),
+        'X-Webhook-Signature': signed.signature,
+      }
+      const url = delivery['url'] as string
+      let outcome: Attempt
+      if (addresses === 'any') {
+        outcome = await sendAnywhere(url, headers, signed.body, timeoutMs)
+      } else {
+        const sent = await untrustedPost(url, {
+          body: signed.body, headers, maxBytes: RESPONSE_BODY_CAP, timeoutMs, maxRedirects: 0,
+          ...(config.network ?? {}),
+        })
+        if (sent.ok) {
+          outcome = { statusCode: sent.status, responseBody: Buffer.from(sent.body).toString('utf8'), success: true, error: null }
+        } else if (sent.status !== undefined) {
+          // The answer arrived; the body is not kept (non-2xx, or a 2xx body over the cap).
+          outcome = { statusCode: sent.status, responseBody: null, success: sent.status >= 200 && sent.status < 300, error: null }
+        } else {
+          outcome = { statusCode: null, responseBody: null, success: false, error: sent.reason }
+        }
+      }
+      const { statusCode, responseBody, success, error } = outcome
+
+      if (success || attempt >= (delivery['max_attempts'] as number)) {
+        await db.execute(
+          sql`UPDATE ${sql.raw(deliveryTable)}
+              SET attempt = ${attempt}, status_code = ${statusCode},
+                  response_body = ${responseBody}, error = ${error}, completed_at = now(), next_retry_at = NULL
+              WHERE id = ${deliveryId}`,
+        )
+      } else {
+        const delayMs = Math.min(initialDelayMs * Math.pow(2, attempt - 1), maxDelayMs)
+        const nextRetry = new Date(Date.now() + delayMs)
+        await db.execute(
+          sql`UPDATE ${sql.raw(deliveryTable)}
+              SET attempt = ${attempt}, status_code = ${statusCode},
+                  response_body = ${responseBody}, error = ${error}, next_retry_at = ${nextRetry.toISOString()}
+              WHERE id = ${deliveryId}`,
+        )
+      }
+
+      return { success, statusCode }
+    },
+
+    async processPending(handle) {
+      const db = requireUnscopedExecutor(handle, 'webhook.processPending()', 'it delivers every tenant\'s pending webhooks')
+      const rows: unknown[] = await db.execute(
+        sql`SELECT id FROM ${sql.raw(deliveryTable)}
+            WHERE completed_at IS NULL AND next_retry_at <= now()
+            ORDER BY next_retry_at ASC
+            LIMIT 100`,
+      )
+
+      let processed = 0
+      for (const row of rows as { id: string }[]) {
+        await this.deliver(db, row.id)
+        processed++
+      }
+      return processed
+    },
+
+    async registerEndpoint(handle, endpoint) {
+      const db = scopedExecutor(handle, endpoint.tenantId, 'webhook.registerEndpoint()').db
+      const rows: unknown[] = await db.execute(
+        sql`INSERT INTO ${sql.raw(endpointTable)} (tenant_id, url, secret, events, active)
+            VALUES (${endpoint.tenantId}, ${endpoint.url}, ${endpoint.secret},
+                    ${`{${endpoint.events.join(',')}}`}, ${endpoint.active})
+            RETURNING id`,
+      )
+      return ((rows as { id: string }[])[0])!.id
+    },
+
+    async listEndpoints(handle, tenantId) {
+      const db = scopedExecutor(handle, tenantId, 'webhook.listEndpoints()').db
+      const rows: unknown[] = await db.execute(
+        sql`SELECT id, tenant_id, url, secret, events, active
+            FROM ${sql.raw(endpointTable)}
+            WHERE tenant_id = ${tenantId}
+            ORDER BY created_at ASC`,
+      )
+      return (rows as Record<string, unknown>[]).map(row => ({
+        id: row['id'] as string,
+        tenantId: row['tenant_id'] as string,
+        url: row['url'] as string,
+        secret: row['secret'] as string,
+        events: row['events'] as string[],
+        active: row['active'] as boolean,
+      }))
+    },
+
+    async removeEndpoint(handle, tenantId, endpointId) {
+      const db = scopedExecutor(handle, tenantId, 'webhook.removeEndpoint()').db
+      const rows: unknown[] = await db.execute(
+        sql`DELETE FROM ${sql.raw(endpointTable)}
+            WHERE id = ${endpointId} AND tenant_id = ${tenantId}
+            RETURNING id`,
+      )
+      return (rows as unknown[]).length > 0
+    },
+  }
+}

package/src/infra/webhook/sign.ts

@@ -0,0 +1,32 @@
+import { createHmac, randomUUID } from 'node:crypto'
+
+export interface WebhookSignatureOptions {
+  algorithm?: string
+  encoding?: 'hex' | 'base64'
+  /** Message id to sign and return; default a fresh UUID. Pass a stable id so a retry is recognisable as the same message. */
+  messageId?: string
+}
+
+export interface SignedPayload {
+  body: string
+  signature: string
+  timestamp: number
+  messageId: string
+}
+
+export function signPayload(
+  payload: unknown,
+  secret: string,
+  options: WebhookSignatureOptions = {},
+): SignedPayload {
+  const algorithm = options.algorithm ?? 'sha256'
+  const encoding = options.encoding ?? 'hex'
+
+  const messageId = options.messageId ?? randomUUID()
+  const timestamp = Math.floor(Date.now() / 1000)
+  const body = typeof payload === 'string' ? payload : JSON.stringify(payload)
+  const toSign = `${messageId}.${timestamp}.${body}`
+  const signature = createHmac(algorithm, secret).update(toSign).digest(encoding)
+
+  return { body, signature, timestamp, messageId }
+}

package/src/infra/webhook/verify.ts

@@ -0,0 +1,82 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+export interface SignatureVerifier {
+  verify(rawBody: Buffer, headers: Readonly<Record<string, string | undefined>>): boolean
+}
+
+type LazySecret = string | (() => string)
+
+function resolveSecret(secret: LazySecret): string {
+  return typeof secret === 'function' ? secret() : secret
+}
+
+export function hmacVerifier(options: {
+  secret: LazySecret
+  algorithm?: string
+  header: string
+  prefix?: string
+  encoding?: 'hex' | 'base64'
+  computePayload?: (rawBody: Buffer, headers: Readonly<Record<string, string | undefined>>) => Buffer
+}): SignatureVerifier {
+  const algorithm = options.algorithm ?? 'sha256'
+  const encoding = options.encoding ?? 'hex'
+  const prefix = options.prefix ?? ''
+
+  return {
+    verify(rawBody, headers) {
+      const headerValue = headers[options.header.toLowerCase()]
+      if (headerValue === undefined || headerValue === '') return false
+
+      const payload = options.computePayload !== undefined
+        ? options.computePayload(rawBody, headers)
+        : rawBody
+
+      const expected = prefix + createHmac(algorithm, resolveSecret(options.secret)).update(payload).digest(encoding)
+
+      try {
+        return timingSafeEqual(Buffer.from(headerValue), Buffer.from(expected))
+      } catch {
+        return false
+      }
+    },
+  }
+}
+
+export function stripeVerifier(secret: LazySecret): SignatureVerifier {
+  return {
+    verify(rawBody, headers) {
+      const sigHeader = headers['stripe-signature']
+      if (sigHeader === undefined) return false
+
+      const parts = new Map<string, string>()
+      for (const pair of sigHeader.split(',')) {
+        const eqIdx = pair.indexOf('=')
+        if (eqIdx === -1) continue
+        parts.set(pair.slice(0, eqIdx).trim(), pair.slice(eqIdx + 1).trim())
+      }
+
+      const timestamp = parts.get('t')
+      const v1Sig = parts.get('v1')
+      if (timestamp === undefined || v1Sig === undefined) return false
+
+      const signedPayload = Buffer.from(`${timestamp}.${rawBody.toString('utf-8')}`)
+      const expected = createHmac('sha256', resolveSecret(secret)).update(signedPayload).digest('hex')
+
+      try {
+        return timingSafeEqual(Buffer.from(v1Sig), Buffer.from(expected))
+      } catch {
+        return false
+      }
+    },
+  }
+}
+
+export function githubVerifier(secret: LazySecret): SignatureVerifier {
+  return hmacVerifier({
+    secret,
+    algorithm: 'sha256',
+    header: 'x-hub-signature-256',
+    prefix: 'sha256=',
+    encoding: 'hex',
+  })
+}

package/src/invariants/assert.ts

@@ -0,0 +1,26 @@
+export class InvariantViolation extends Error {
+  constructor(
+    public readonly invariant: string,
+    public readonly context: Record<string, unknown>,
+  ) {
+    const details = Object.entries(context)
+      .map(([k, v]) => `    ${k}: ${JSON.stringify(v)}`)
+      .join('\n')
+    super(
+      `[pipework] Invariant violation: ${invariant}\n\n` +
+      `  Context:\n${details}\n\n` +
+      `  This is a framework bug. Please report it.\n`
+    )
+    this.name = 'TrunkInvariantViolation'
+  }
+}
+
+export function invariant(
+  condition: boolean,
+  name: string,
+  context: Record<string, unknown> = {},
+): asserts condition {
+  if (!condition) {
+    throw new InvariantViolation(name, context)
+  }
+}

package/src/invariants/index.ts

@@ -0,0 +1 @@
+export { invariant, InvariantViolation } from './assert.js'

package/src/lint/config.ts

@@ -0,0 +1,56 @@
+import tseslint from '@typescript-eslint/eslint-plugin'
+import tsparser from '@typescript-eslint/parser'
+import { noReexports } from './rules/no-reexports.js'
+
+export const rules = {
+  '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+  '@typescript-eslint/no-explicit-any': 'error',
+  '@typescript-eslint/no-floating-promises': 'error',
+  '@typescript-eslint/no-misused-promises': 'error',
+  '@typescript-eslint/require-await': 'error',
+  '@typescript-eslint/no-unnecessary-condition': 'error',
+  '@typescript-eslint/strict-boolean-expressions': 'error',
+  'pipework/no-reexports': 'error',
+} as const
+
+export interface LintOptions {
+  readonly tsconfigRootDir?: string
+  readonly include?: readonly string[]
+  readonly ignores?: readonly string[]
+  readonly extraRules?: Readonly<Record<string, unknown>>
+  readonly extraPlugins?: Readonly<Record<string, unknown>>
+  readonly extraConfigs?: readonly unknown[]
+}
+
+export function createLintConfig(config?: LintOptions): unknown[] {
+  const files = config?.include ?? ['src/**/*.ts', 'src/**/*.tsx']
+  const parserOptions: Record<string, unknown> = { projectService: true }
+  if (config?.tsconfigRootDir !== undefined) {
+    parserOptions['tsconfigRootDir'] = config.tsconfigRootDir
+  }
+
+  const appliedRules = { ...rules, ...config?.extraRules }
+  const appliedPlugins: Record<string, unknown> = {
+    '@typescript-eslint': tseslint,
+    'pipework': { rules: { 'no-reexports': noReexports } },
+    ...config?.extraPlugins,
+  }
+
+  const blocks: unknown[] = [
+    {
+      files: [...files],
+      languageOptions: {
+        parser: tsparser,
+        parserOptions,
+      },
+      plugins: appliedPlugins,
+      rules: appliedRules,
+    },
+    ...(config?.extraConfigs ?? []),
+    {
+      ignores: ['dist/', 'node_modules/', ...(config?.ignores ?? [])],
+    },
+  ]
+
+  return blocks
+}

package/src/lint/doctrine.ts

@@ -0,0 +1,163 @@
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+export interface DoctrineViolation {
+  readonly rule: string
+  readonly file: string
+  readonly line: number
+  readonly message: string
+}
+
+export interface DoctrineResult {
+  readonly violations: readonly DoctrineViolation[]
+  readonly scanned: number
+}
+
+export function validateDoctrine(cwd: string, sourceFiles: readonly string[]): DoctrineResult {
+  const violations: DoctrineViolation[] = []
+  let scanned = 0
+
+  for (const file of sourceFiles) {
+    const abs = join(cwd, file)
+    if (!existsSync(abs)) continue
+
+    const content = readFileSync(abs, 'utf-8')
+    const lines = content.split('\n')
+    scanned++
+
+    checkSchemaTableUsage(file, lines, violations)
+    checkRawPgTableImport(file, lines, violations)
+    checkUnbrandedPrimaryKeys(file, lines, violations)
+    checkHandWrittenTraitFields(file, lines, violations)
+  }
+
+  return { violations, scanned }
+}
+
+const SCHEMA_TABLE_PATTERN = /\bschema\.table\s*\(/
+const PIPE_DEFINE_FILE_PATTERN = /\bpipe\.define\s*\(/
+
+function checkSchemaTableUsage(
+  file: string,
+  lines: readonly string[],
+  violations: DoctrineViolation[],
+): void {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    if (SCHEMA_TABLE_PATTERN.test(line)) {
+      violations.push({
+        rule: 'define/prefer-pipe-define',
+        file,
+        line: i + 1,
+        message: 'Use pipe.define() instead of schema.table(). pipe.define() provides branded types, shape validators, test factories, and tenant isolation.',
+      })
+    }
+  }
+}
+
+const RAW_PG_TABLE_IMPORT_LINE = /import\s+.*\bpgTable\b.*from\s+/
+
+function checkRawPgTableImport(
+  file: string,
+  lines: readonly string[],
+  violations: DoctrineViolation[],
+): void {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    if (RAW_PG_TABLE_IMPORT_LINE.test(line)) {
+      violations.push({
+        rule: 'define/no-raw-pgTable',
+        file,
+        line: i + 1,
+        message: 'Raw pgTable() import — use pipe.define() instead. pipe.define() returns a DefinedTable that IS a PgTable, with branded types that flow through select().from() and eq().',
+      })
+    }
+  }
+}
+
+const PRIMARY_KEY_PATTERN = /\.primaryKey\(\)/
+const BRAND_PATTERN = /\.brand\(/
+const PIPE_FIELD_UUID_PATTERN = /pipe\.field\.(uuid|serial)\(\)/
+
+function checkUnbrandedPrimaryKeys(
+  file: string,
+  lines: readonly string[],
+  violations: DoctrineViolation[],
+): void {
+  if (!lines.some(l => PIPE_DEFINE_FILE_PATTERN.test(l))) return
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    if (PIPE_FIELD_UUID_PATTERN.test(line) && PRIMARY_KEY_PATTERN.test(line) && !BRAND_PATTERN.test(line)) {
+      violations.push({
+        rule: 'define/brand-primary-key',
+        file,
+        line: i + 1,
+        message: 'Primary key field missing .brand(). Add .brand(\'EntityNameId\') for nominal type safety.',
+      })
+    }
+  }
+}
+
+const TRAIT_FIELD_PATTERNS: ReadonlyArray<{ pattern: RegExp; trait: string; field: string }> = [
+  { pattern: /\bcreatedAt\s*:\s*pipe\.field\.timestamp\(\)/, trait: '.audited()', field: 'createdAt' },
+  { pattern: /\bupdatedAt\s*:\s*pipe\.field\.timestamp\(\)/, trait: '.audited()', field: 'updatedAt' },
+  { pattern: /\beffectiveFrom\s*:\s*pipe\.field\.timestamp\(\)/, trait: '.effectiveDated()', field: 'effectiveFrom' },
+  { pattern: /\beffectiveTo\s*:\s*pipe\.field\.timestamp\(\)/, trait: '.effectiveDated()', field: 'effectiveTo' },
+  { pattern: /\bdeletedAt\s*:\s*pipe\.field\.timestamp\(\)/, trait: '.softDeleted()', field: 'deletedAt' },
+]
+
+function checkHandWrittenTraitFields(
+  file: string,
+  lines: readonly string[],
+  violations: DoctrineViolation[],
+): void {
+  if (!lines.some(l => PIPE_DEFINE_FILE_PATTERN.test(l))) return
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    for (const { pattern, trait, field } of TRAIT_FIELD_PATTERNS) {
+      if (pattern.test(line)) {
+        violations.push({
+          rule: 'define/use-traits',
+          file,
+          line: i + 1,
+          message: `Hand-written '${field}' field — use ${trait} trait instead. Traits are auto-managed and excluded from insert/update shapes.`,
+        })
+      }
+    }
+  }
+}
+
+export function findSourceFiles(cwd: string, modulePaths: readonly string[]): string[] {
+  const files: string[] = []
+
+  for (const modPath of modulePaths) {
+    const srcDir = join(cwd, modPath, 'src')
+    if (!existsSync(srcDir)) continue
+    collectTsFiles(srcDir, cwd, files)
+  }
+
+  return files.sort()
+}
+
+/** A `.ts` or `.tsx` source: not a test file, not a declaration file. */
+export function isSourceFileName(name: string): boolean {
+  if (name.endsWith('.d.ts')) return false
+  if (name.endsWith('.test.ts') || name.endsWith('.test.tsx')) return false
+  return name.endsWith('.ts') || name.endsWith('.tsx')
+}
+
+function collectTsFiles(dir: string, cwd: string, out: string[]): void {
+  const entries = readdirSync(dir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '__tests__') continue
+      collectTsFiles(full, cwd, out)
+    } else if (isSourceFileName(entry.name)) {
+      out.push(relative(cwd, full))
+    }
+  }
+}