@mettlecast/eslint-plugin-domain-module 0.2.59 → 0.2.60

package/README.md

@@ -1,6 +1,6 @@
 # @mettlecast/eslint-plugin-domain-module
 
-ESLint plugin enforcing TIB Domain Module framework usage patterns. Prevents accidental AWS SDK, HTTP server, and cross-domain violations.
+ESLint plugin enforcing TIB Domain Module framework usage patterns. Prevents accidental AWS SDK, HTTP server, Postgres client, raw DB lifecycle calls, and cross-domain violations in domain handler files.
 
 ## Install
 
@@ -25,22 +25,40 @@ export default [
 
 | Rule | Flags | Severity |
 |---|---|---|
-| `no-raw-aws-sdk` | Direct imports of `@aws-sdk/*` packages in domain handler files | error |
+| `no-raw-aws-sdk` | Direct imports of `@aws-sdk/*` packages in domain handler files (Lambda, DynamoDB, S3, EventBridge, SQS, SNS, Secrets Manager, STS, Cognito, etc. — each maps to the correct `ctx.*` method) | error |
+| `no-raw-pg-client` | Direct `pg`, `pg-pool`, `pg-cursor`, `postgres`, `pg-protocol`, `pg-query-stream` imports — use `ctx.db` | error |
+| `no-raw-db-client-release` | Low-level `client.release()` / `pool.end()` / `pgClient.release()` / `poolClient.release()` calls — runtime owns pool lifecycle | error |
 | `no-raw-http-server` | Framework imports (`express`, `koa`, `fastify`, `aws-lambda`) in domain handlers | error |
+| `no-raw-fetch` | Raw `fetch()` calls in domain handlers — use `ctx.fetch` | error |
 | `require-define-primitive` | Handler files without a top-level `define*()` call (missing domain primitive declaration) | warn |
 | `no-cross-domain-internal-import` | Importing internal modules (not exported types) from another domain directory | error |
+| `flow-domain-ownership` | Flow files in `domains/{x}/flows/` must declare `owningDomain: 'x'` | error |
+| `zod-defaults-required` | Top-level Zod input/output schemas must end in `.default(...)` | error |
+| `api-needs-fixture` | Every `defineApi` needs a sibling `__tests__/<id>.fixture.json` | error |
+| `prefer-result-over-throw` | Domain API handlers must `return err({...})` instead of throwing | error |
+| `use-tanstack-router` | Frontend must use TanStack Router | error |
+| `tanstack-query-options` | TanStack Query data must be wrapped in `queryOptions(...)` | warn |
 
 ## Recommended Config
 
-The `recommended` preset enables all four rules at their default severity levels:
+The `recommended` preset enables all rules at their default severity levels:
 
 ```javascript
 domainModulePlugin.configs.recommended
 // Results in:
 // - no-raw-aws-sdk: error
+// - no-raw-pg-client: error
+// - no-raw-db-client-release: error
 // - no-raw-http-server: error
+// - no-raw-fetch: error
 // - require-define-primitive: warn
 // - no-cross-domain-internal-import: error
+// - flow-domain-ownership: error
+// - zod-defaults-required: error
+// - api-needs-fixture: error
+// - prefer-result-over-throw: error
+// - use-tanstack-router: error
+// - tanstack-query-options: warn
 ```
 
 ## Examples
@@ -48,9 +66,22 @@ domainModulePlugin.configs.recommended
 **Violations caught:**
 
 ```typescript
-// ❌ no-raw-aws-sdk
+// ❌ no-raw-aws-sdk (Lambda) — use ctx.actions.call(...)
+import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';
+
+// ❌ no-raw-aws-sdk (DynamoDB) — use ctx.store.{get,put,query,...}
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 
+// ❌ no-raw-aws-sdk (S3) — use ctx.files.{get,put,...}
+import { S3Client } from '@aws-sdk/client-s3';
+
+// ❌ no-raw-pg-client — use ctx.db.query(...) / ctx.db.client.query(...)
+import { Pool } from 'pg';
+
+// ❌ no-raw-db-client-release — runtime owns pool lifecycle
+pool.end();
+client.release();
+
 // ❌ no-raw-http-server
 import express from 'express';
 
@@ -64,20 +95,23 @@ import { internalFn } from '../payments/internal.js'; // not in payments/index.t
 **Correct usage:**
 
 ```typescript
-// ✓ Use DomainContext.db instead
-const { db } = ctx;
+// ✓ Backend-to-backend calls go through the action envelope
+await ctx.actions.call('payments.charge-card', { amount });
+
+// ✓ Per-tenant DynamoDB
+await ctx.store.put('user#123', { email: 'a@example.com' });
+
+// ✓ Per-tenant S3
+await ctx.files.put('reports/q4.pdf', pdfBuffer);
 
-// ✓ Use defineApi() to declare handlers
-export const chargeHandler = defineApi({
-  path: '/charge',
-  // ...
-});
+// ✓ DB queries always carry Wave 5 session variables
+await ctx.db.query('SELECT * FROM orders WHERE tenant = $1', [ctx.tenant.id]);
 
-// ✓ Only import exported types from other domains
-import type { PaymentEvent } from '@myorg/payments-contracts';
+// ✓ Runtime releases the pool for you — do not call .release() / .end()
+await ctx.db.release(); // only if you really need to release early
 ```
 
 ## See Also
 
-- `@mettlecast/domain-runtime` — handler definitions
-- `@mettlecast/domain-cli` — validation and linting
+- `@mettlecast/domain-runtime` — handler definitions and `DomainContext`
+- `@mettlecast/domain-cli` — validation and linting

package/dist/__tests__/no-raw-aws-sdk.test.js

@@ -12,6 +12,8 @@ tester.run('no-raw-aws-sdk', noRawAwsSdk, {
         { code: "import { something } from '@my-org/utils';" },
         { code: "import { DomainContext } from '@mettlecast/domain-runtime';" },
         { code: "const x = require('fs');" },
+        // pg imports are handled by a separate rule — they are valid for no-raw-aws-sdk
+        { code: "import { Pool } from 'pg';" },
     ],
     invalid: [
         {
@@ -26,5 +28,36 @@ tester.run('no-raw-aws-sdk', noRawAwsSdk, {
             code: "import { EventBridgeClient } from '@aws-sdk/client-eventbridge';",
             errors: [{ messageId: 'noRawAwsSdk' }],
         },
+        // Wave 6 Task 6.2 — additional bypass patterns point at the right ctx method.
+        {
+            code: "import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';",
+            errors: [{ messageId: 'noRawAwsSdk' }],
+        },
+        {
+            code: "import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';",
+            errors: [{ messageId: 'noRawAwsSdk' }],
+        },
+        {
+            code: "import { SQSClient, SendMessageCommand } from '@aws-sdk/client-sqs';",
+            errors: [{ messageId: 'noRawAwsSdk' }],
+        },
+        {
+            code: "import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';",
+            errors: [{ messageId: 'noRawAwsSdk' }],
+        },
+        {
+            code: "import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';",
+            errors: [{ messageId: 'noRawAwsSdk' }],
+        },
+        // Subpath imports still match (substring matcher).
+        {
+            code: "import { Foo } from '@aws-sdk/client-dynamodb/dist-cjs/commands/GetItemCommand.js';",
+            errors: [{ messageId: 'noRawAwsSdk' }],
+        },
+        // Unknown @aws-sdk/* packages still fall through to the generic message.
+        {
+            code: "import { Foo } from '@aws-sdk/client-some-new-service';",
+            errors: [{ messageId: 'noRawAwsSdk' }],
+        },
     ],
 });

package/dist/__tests__/no-raw-db-client-release.test.d.ts

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

package/dist/__tests__/no-raw-db-client-release.test.js

@@ -0,0 +1,66 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { afterAll, describe, it } from 'vitest';
+import { noRawDbClientRelease } from '../rules/no-raw-db-client-release.js';
+RuleTester.afterAll = afterAll;
+RuleTester.describe = describe;
+RuleTester.it = it;
+const tester = new RuleTester({
+    languageOptions: { ecmaVersion: 2022, sourceType: 'module' },
+});
+tester.run('no-raw-db-client-release', noRawDbClientRelease, {
+    valid: [
+        // Runtime-managed release through ctx.db is the supported pattern.
+        "await ctx.db.release();",
+        "await ctx.db.release(true);",
+        // Unknown method names on otherwise innocuous objects.
+        "client.close();",
+        "client.destroy();",
+        "pool.disconnect();",
+        // release()/end() on unrelated objects (object names not in hints).
+        "thing.release();",
+        "thing.end();",
+        "user.release();",
+        // Property is not `release`/`end` even if object matches hint.
+        "client.query();",
+        "pool.connect();",
+        // Nested calls that don't end in release()/end().
+        "client.query('SELECT release()');",
+        "client.endOfFile;",
+        "pool.endOfStream();",
+    ],
+    invalid: [
+        // The most common bypass: db.client.release().
+        {
+            code: 'db.client.release();',
+            errors: [{ messageId: 'noRawDbClientRelease', data: { call: 'db.client.release' } }],
+        },
+        {
+            code: 'await ctx.db.client.release();',
+            errors: [{ messageId: 'noRawDbClientRelease', data: { call: 'ctx.db.client.release' } }],
+        },
+        // Direct client.release().
+        {
+            code: 'client.release();',
+            errors: [{ messageId: 'noRawDbClientRelease', data: { call: 'client.release' } }],
+        },
+        // pool.end() / poolClient.release().
+        {
+            code: 'pool.end();',
+            errors: [{ messageId: 'noRawDbClientRelease', data: { call: 'pool.end' } }],
+        },
+        {
+            code: 'poolClient.release();',
+            errors: [{ messageId: 'noRawDbClientRelease', data: { call: 'poolClient.release' } }],
+        },
+        // pgClient is also a recognised hint name.
+        {
+            code: 'pgClient.release(true);',
+            errors: [{ messageId: 'noRawDbClientRelease', data: { call: 'pgClient.release' } }],
+        },
+        // Inside a function body — still caught.
+        {
+            code: 'function shutdown() { pool.end(); }',
+            errors: [{ messageId: 'noRawDbClientRelease', data: { call: 'pool.end' } }],
+        },
+    ],
+});

package/dist/__tests__/no-raw-pg-client.test.d.ts

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

package/dist/__tests__/no-raw-pg-client.test.js

@@ -0,0 +1,77 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { afterAll, describe, it } from 'vitest';
+import { noRawPgClient } from '../rules/no-raw-pg-client.js';
+RuleTester.afterAll = afterAll;
+RuleTester.describe = describe;
+RuleTester.it = it;
+const tester = new RuleTester({
+    languageOptions: { ecmaVersion: 2022, sourceType: 'module' },
+});
+tester.run('no-raw-pg-client', noRawPgClient, {
+    valid: [
+        // Domain code that uses ctx.db is fine.
+        { code: "import { defineApi } from '@mettlecast/domain-runtime';" },
+        { code: "import { drizzle } from 'drizzle-orm/node-postgres';" },
+        // Other packages that aren't in the ban-list stay allowed.
+        { code: "import { something } from 'pg-query-emscripten';" },
+        // Subpath that isn't actually a pg client.
+        { code: "import { bar } from 'pg-mock-something-else';" },
+    ],
+    invalid: [
+        {
+            code: "import { Pool } from 'pg';",
+            errors: [
+                {
+                    messageId: 'noRawPgClient',
+                    data: { source: 'pg', label: 'node-postgres (pg)' },
+                },
+            ],
+        },
+        {
+            code: "import { Pool } from 'pg-pool';",
+            errors: [
+                {
+                    messageId: 'noRawPgClient',
+                    data: { source: 'pg-pool', label: 'pg.Pool' },
+                },
+            ],
+        },
+        {
+            code: "import { Client } from 'pg-protocol';",
+            errors: [
+                {
+                    messageId: 'noRawPgClient',
+                    data: { source: 'pg-protocol', label: 'pg-protocol' },
+                },
+            ],
+        },
+        {
+            code: "import { cursor } from 'pg-cursor';",
+            errors: [
+                {
+                    messageId: 'noRawPgClient',
+                    data: { source: 'pg-cursor', label: 'pg-cursor' },
+                },
+            ],
+        },
+        {
+            code: "import postgres from 'postgres';",
+            errors: [
+                {
+                    messageId: 'noRawPgClient',
+                    data: { source: 'postgres', label: 'postgres (porsager/postgres)' },
+                },
+            ],
+        },
+        // Subpath imports are still caught.
+        {
+            code: "import { Pool } from 'pg-pool/sub';",
+            errors: [
+                {
+                    messageId: 'noRawPgClient',
+                    data: { source: 'pg-pool/sub', label: 'pg.Pool' },
+                },
+            ],
+        },
+    ],
+});

package/dist/index.d.ts

@@ -38,6 +38,12 @@ declare const _default: {
         readonly 'prefer-result-over-throw': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferResult", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
             name: string;
         };
+        readonly 'no-raw-pg-client': import("@typescript-eslint/utils/ts-eslint").RuleModule<"noRawPgClient", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        readonly 'no-raw-db-client-release': import("@typescript-eslint/utils/ts-eslint").RuleModule<"noRawDbClientRelease", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
     };
     configs: {
         recommended: {
@@ -77,6 +83,12 @@ declare const _default: {
                         readonly 'prefer-result-over-throw': import("@typescript-eslint/utils/ts-eslint").RuleModule<"preferResult", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
                             name: string;
                         };
+                        readonly 'no-raw-pg-client': import("@typescript-eslint/utils/ts-eslint").RuleModule<"noRawPgClient", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                            name: string;
+                        };
+                        readonly 'no-raw-db-client-release': import("@typescript-eslint/utils/ts-eslint").RuleModule<"noRawDbClientRelease", [], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+                            name: string;
+                        };
                     };
                 };
             };
@@ -92,6 +104,8 @@ declare const _default: {
                 readonly '@mettlecast/domain-module/zod-defaults-required': "error";
                 readonly '@mettlecast/domain-module/api-needs-fixture': "error";
                 readonly '@mettlecast/domain-module/prefer-result-over-throw': "error";
+                readonly '@mettlecast/domain-module/no-raw-pg-client': "error";
+                readonly '@mettlecast/domain-module/no-raw-db-client-release': "error";
             };
         };
     };

package/dist/index.js

@@ -9,6 +9,8 @@ import { tanstackQueryOptions } from './rules/tanstack-query-options.js';
 import { zodDefaultsRequired } from './rules/zod-defaults-required.js';
 import { apiNeedsFixture } from './rules/api-needs-fixture.js';
 import { preferResultOverThrow } from './rules/prefer-result-over-throw.js';
+import { noRawPgClient } from './rules/no-raw-pg-client.js';
+import { noRawDbClientRelease } from './rules/no-raw-db-client-release.js';
 /**
  * All rules exported by @mettlecast/eslint-plugin-domain-module.
  */
@@ -24,6 +26,9 @@ const rules = {
     'zod-defaults-required': zodDefaultsRequired,
     'api-needs-fixture': apiNeedsFixture,
     'prefer-result-over-throw': preferResultOverThrow,
+    // Wave 6 Task 6.2 — auth/tenant bypass prevention
+    'no-raw-pg-client': noRawPgClient,
+    'no-raw-db-client-release': noRawDbClientRelease,
 };
 /**
  * Recommended flat config preset.
@@ -45,6 +50,9 @@ const recommended = {
         '@mettlecast/domain-module/zod-defaults-required': 'error',
         '@mettlecast/domain-module/api-needs-fixture': 'error',
         '@mettlecast/domain-module/prefer-result-over-throw': 'error',
+        // Wave 6 Task 6.2 — auth/tenant bypass prevention
+        '@mettlecast/domain-module/no-raw-pg-client': 'error',
+        '@mettlecast/domain-module/no-raw-db-client-release': 'error',
     },
 };
 /**

package/dist/rules/no-raw-aws-sdk.js

@@ -1,5 +1,92 @@
 import { ESLintUtils } from '@typescript-eslint/utils';
 const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/LawrenceGeeHouse/Mettlecast/blob/develop/packages/eslint-plugin-domain-module/docs/${name}.md`);
+const SDK_TARGETS = [
+    {
+        match: 'client-lambda',
+        service: 'AWS Lambda',
+        ctxMethod: 'ctx.actions.call(\'<domain>.<action>\', input)',
+        reason: 'calling Lambda directly bypasses the action envelope, so the runtime cannot inject the tenant-scoped IAM principal, the auth tenant header, or the tracing/audit context that every other action call receives.',
+    },
+    {
+        match: 'client-dynamodb',
+        service: 'DynamoDB',
+        ctxMethod: 'ctx.store.{get,put,query,update,delete}',
+        reason: 'creating a DynamoDB client from a domain handler bypasses ctx.store, which automatically prefixes the partition key with the current tenantId — a raw call cannot enforce tenant isolation.',
+    },
+    {
+        match: 'lib-dynamodb',
+        service: 'DynamoDB DocumentClient',
+        ctxMethod: 'ctx.store.{get,put,query,update,delete}',
+        reason: 'the document-client wrapper still requires tenant-scoped partition keys; ctx.store applies them for every call so domain code never sees the raw PK.',
+    },
+    {
+        match: 'util-dynamodb',
+        service: 'DynamoDB marshalling',
+        ctxMethod: 'ctx.store.{get,put,query,update,delete}',
+        reason: 'marshalling helpers belong in the store adapter; if domain code is unmarshalling manually it is almost certainly calling DynamoDB through a side channel.',
+    },
+    {
+        match: 'client-s3',
+        service: 'S3',
+        ctxMethod: 'ctx.files.{get,put,delete,list,getSignedUrl}',
+        reason: 'ctx.files prefixes every object key with `{tenantId}/`; a raw S3 client would need to re-implement that prefix and is the most common way to leak objects across tenants.',
+    },
+    {
+        match: 'client-secrets-manager',
+        service: 'Secrets Manager',
+        ctxMethod: 'ctx.secrets.<name>',
+        reason: 'ctx.secrets is the only path that runs with the tenant-scoped execution role and is auditable; reading raw secrets from a handler bypasses that.',
+    },
+    {
+        match: 'client-eventbridge',
+        service: 'EventBridge',
+        ctxMethod: 'ctx.publish(\'<domain>.<event>\', data)',
+        reason: 'ctx.publish is the only event entrypoint that the schema registry tracks; raw PutEvents calls are invisible to the event catalog and to replay tooling.',
+    },
+    {
+        match: 'client-sns',
+        service: 'SNS',
+        ctxMethod: 'ctx.publish(\'<domain>.<event>\', data)',
+        reason: 'ctx.publish is the supported event entrypoint; raw SNS publishes cannot be replayed or schema-validated.',
+    },
+    {
+        match: 'client-sqs',
+        service: 'SQS',
+        ctxMethod: 'ctx.jobs.enqueue(\'<domain>.<job>\', input)',
+        reason: 'background work belongs on ctx.jobs so retries, visibility timeouts and DLQ wiring are managed by the runtime.',
+    },
+    {
+        match: 'client-sts',
+        service: 'STS',
+        ctxMethod: 'ctx (provided execution role)',
+        reason: 'assume-role from a domain handler is always wrong: the handler already runs with a tenant-scoped role and a cross-account assume would silently break tenant isolation.',
+    },
+    {
+        match: 'client-cognito-identity',
+        service: 'Cognito Identity',
+        ctxMethod: 'ctx (provided JWT authorizer)',
+        reason: 'domain handlers must rely on the JWT authorizer already wired by the runtime; using Cognito Identity directly bypasses the verified claim set.',
+    },
+    {
+        match: 'client-cognito-identity-provider',
+        service: 'Cognito Identity Provider',
+        ctxMethod: 'ctx.integrations.cognito.* (or an internal admin action)',
+        reason: 'Cognito control-plane calls belong in a privileged integration or a system-tenancy admin action so the bootstrap secret and IAM scope are auditable.',
+    },
+];
+const FALLBACK_TARGET = {
+    match: '@aws-sdk/',
+    service: 'AWS',
+    ctxMethod: 'the corresponding ctx.* method',
+    reason: 'direct AWS SDK use in a domain handler bypasses the runtime wrappers that enforce tenancy, tracing, and the schema/registry contract.',
+};
+function classify(source) {
+    // Prefer the most-specific (longest) match so lib-dynamodb beats client-dynamodb.
+    const candidates = SDK_TARGETS
+        .filter((t) => source.includes(t.match))
+        .sort((a, b) => b.match.length - a.match.length);
+    return candidates[0] ?? FALLBACK_TARGET;
+}
 export const noRawAwsSdk = createRule({
     name: 'no-raw-aws-sdk',
     meta: {
@@ -8,7 +95,7 @@ export const noRawAwsSdk = createRule({
             description: 'Disallow direct @aws-sdk/* imports in domain handler files. Use ctx.* instead.',
         },
         messages: {
-            noRawAwsSdk: 'Direct AWS SDK import "{{source}}" is not allowed in domain handlers. Use ctx.* methods provided by DomainContext.\n  fixHint: Replace `import ... from \'{{source}}\'` with the corresponding `ctx.*` method (e.g., ctx.db for DynamoDB, ctx.publish for EventBridge).\n  kNodeRef: K:convention:tier-1-foundations',
+            noRawAwsSdk: 'Direct {{service}} SDK import "{{source}}" is not allowed in domain handlers — use {{ctxMethod}} instead.\n  why: {{reason}}\n  fixHint: Remove the `import ... from \'{{source}}\'` and route the call through the runtime context. If no ctx.* method exists for this AWS service, add one to `@mettlecast/domain-runtime` rather than reaching for the raw SDK.\n  kNodeRef: K:convention:tier-1-foundations',
         },
         schema: [],
     },
@@ -17,9 +104,19 @@ export const noRawAwsSdk = createRule({
         return {
             ImportDeclaration(node) {
                 const source = node.source.value;
-                if (typeof source === 'string' && /^@aws-sdk\//.test(source)) {
-                    context.report({ node, messageId: 'noRawAwsSdk', data: { source } });
-                }
+                if (typeof source !== 'string' || !source.startsWith('@aws-sdk/'))
+                    return;
+                const target = classify(source);
+                context.report({
+                    node,
+                    messageId: 'noRawAwsSdk',
+                    data: {
+                        source,
+                        service: target.service,
+                        ctxMethod: target.ctxMethod,
+                        reason: target.reason,
+                    },
+                });
             },
         };
     },

package/dist/rules/no-raw-db-client-release.d.ts

@@ -0,0 +1,4 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const noRawDbClientRelease: ESLintUtils.RuleModule<"noRawDbClientRelease", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/rules/no-raw-db-client-release.js

@@ -0,0 +1,88 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/LawrenceGeeHouse/Mettlecast/blob/develop/packages/eslint-plugin-domain-module/docs/${name}.md`);
+/**
+ * Method names that indicate a low-level pg pool/client teardown.
+ *
+ * `release()` returns a checked-out `pg.PoolClient` to the pool. `end()`
+ * closes the entire pool. Both must never be called from domain code:
+ *
+ *   - `client.release()` short-circuits the runtime's idempotent
+ *     `ctx.db.release()` wrapper, so the next request that checks the
+ *     client out inherits the previous request's `app.current_tenant`
+ *     session variable — which means RLS is silently evaluated against the
+ *     wrong tenant for one query.
+ *
+ *   - `pool.end()` / `poolClient.end()` tears the pool down so subsequent
+ *     requests race on a closed pool.
+ *
+ * Domain code should not call either. If a handler really needs to
+ * release early (e.g. for very long-running work), it should call
+ * `await ctx.db.release()` and let the runtime re-acquire the client —
+ * the runtime resets the session variables on every acquisition.
+ */
+const RELEASE_METHODS = new Set(['release', 'end']);
+const PROPERTY_HINTS = ['client', 'pool', 'poolClient', 'pgClient'];
+function chainText(member) {
+    // Best-effort text rendering for the diagnostic message. We don't try to
+    // resolve identifiers — we just walk the chain and concatenate names so
+    // the developer can recognise their pattern.
+    const parts = [];
+    let cur = member;
+    while (cur && cur.type === 'MemberExpression') {
+        if (cur.property.type === 'Identifier')
+            parts.unshift(cur.property.name);
+        cur = cur.object;
+    }
+    if (cur && cur.type === 'Identifier')
+        parts.unshift(cur.name);
+    return parts.join('.');
+}
+function matchesBypassPattern(member) {
+    // The pattern we care about is `<expr>.<intermediate>.release()` where
+    // `<intermediate>` is one of the pg-related hints, OR
+    // `<expr>.release()` where `<expr>` itself is one of the hints
+    // (covers `client.release()`, `pool.end()` etc.).
+    if (member.property.type !== 'Identifier')
+        return false;
+    if (!RELEASE_METHODS.has(member.property.name))
+        return false;
+    const inner = member.object;
+    if (inner.type === 'Identifier' && PROPERTY_HINTS.includes(inner.name))
+        return true;
+    if (inner.type === 'MemberExpression') {
+        if (inner.property.type !== 'Identifier')
+            return false;
+        return PROPERTY_HINTS.includes(inner.property.name);
+    }
+    return false;
+}
+export const noRawDbClientRelease = createRule({
+    name: 'no-raw-db-client-release',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow low-level pg client.release()/pool.end() calls in domain handler files. Release is managed by the runtime so session variables stay scoped.',
+        },
+        messages: {
+            noRawDbClientRelease: 'Low-level Postgres teardown "{{call}}" is not allowed in domain handlers — the runtime owns client lifecycle.\n  why: The runtime resets the Wave 5 session variables (`app.current_tenant`, `app.org_id`, `app.actor_id`) on every pool checkout. If domain code calls `client.release()` / `pool.end()` directly, the next handler that picks up the same client inherits the previous request\'s tenant binding and RLS evaluates against the wrong tenant for at least one query.\n  fixHint: Remove the manual release/end call entirely. The runtime calls `await ctx.db.release()` after the handler returns — that path is idempotent and rebinds session variables on the next acquisition. If you need to release a long-running connection early, call `await ctx.db.release()` instead of touching the pg client directly. If this is a legitimate teardown in non-domain code, narrow the lint scope or add an `// eslint-disable-next-line` with a justifying comment.\n  kNodeRef: K:convention:db-tenant-binding',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== 'MemberExpression')
+                    return;
+                if (matchesBypassPattern(callee)) {
+                    context.report({
+                        node,
+                        messageId: 'noRawDbClientRelease',
+                        data: { call: chainText(callee) },
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/no-raw-pg-client.d.ts

@@ -0,0 +1,4 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const noRawPgClient: ESLintUtils.RuleModule<"noRawPgClient", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/rules/no-raw-pg-client.js

@@ -0,0 +1,49 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/LawrenceGeeHouse/Mettlecast/blob/develop/packages/eslint-plugin-domain-module/docs/${name}.md`);
+const PG_TARGETS = [
+    { match: 'pg', label: 'node-postgres (pg)' },
+    { match: 'pg-pool', label: 'pg.Pool' },
+    { match: 'pg-cursor', label: 'pg-cursor' },
+    { match: 'postgres', label: 'postgres (porsager/postgres)' },
+    { match: 'pg-protocol', label: 'pg-protocol' },
+    { match: 'pg-query-stream', label: 'pg-query-stream' },
+];
+const FALLBACK_LABEL = 'Postgres client';
+function classify(source) {
+    const hit = PG_TARGETS.find((t) => source === t.match || source.startsWith(`${t.match}/`));
+    return hit?.label ?? FALLBACK_LABEL;
+}
+export const noRawPgClient = createRule({
+    name: 'no-raw-pg-client',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow direct Postgres client imports in domain handler files. Use ctx.db from DomainContext.',
+        },
+        messages: {
+            noRawPgClient: 'Direct Postgres client import "{{source}}" is not allowed in domain handlers — {{label}} bypasses ctx.db.\n  why: ctx.db is the only Postgres entrypoint that binds the Wave 5 session variables (`app.current_tenant`, `app.org_id`, `app.actor_id`) on the checked-out client. A raw pg client has no tenant bound, so RLS policies read stale tenant IDs from a previous request and leak rows across tenants.\n  fixHint: Remove `import ... from \'{{source}}\'` and route the query through `await ctx.db.query(...)` or `await ctx.db.client.query(...)` — both of which already carry the tenant session variables. If a new pg helper is genuinely needed, add it to `@mettlecast/domain-runtime` rather than importing the raw client.\n  kNodeRef: K:convention:db-tenant-binding',
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            ImportDeclaration(node) {
+                const source = node.source.value;
+                if (typeof source !== 'string')
+                    return;
+                // Allowlist: the runtime package itself imports `pg` to construct the
+                // tenant-bound pool, so we only flag imports when this rule runs on
+                // domain-source files (which it does via the recommended config's
+                // `files` filter in `infra/modules/eslint.config.js`).
+                if (!PG_TARGETS.some((t) => source === t.match || source.startsWith(`${t.match}/`)))
+                    return;
+                context.report({
+                    node,
+                    messageId: 'noRawPgClient',
+                    data: { source, label: classify(source) },
+                });
+            },
+        };
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/eslint-plugin-domain-module",
-  "version": "0.2.59",
+  "version": "0.2.60",
   "type": "module",
   "files": [
     "dist"