@starci/eslint-canon-be 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @starci/eslint-canon-be
+
+**37 ESLint rules, from 15 laws, that hold a NestJS-shaped back end to one way of being written.**
+
+Not a style pack. These rules enforce *architecture*: which layer may import which, whether a
+failure carries its own identity, where a query is allowed to be built, what an end-to-end test is
+permitted to assume. Prettier decides how code looks; this decides what it is allowed to be.
+
+```bash
+npm i -D @starci/eslint-canon-be
+```
+
+## Use it
+
+```js
+import starciBe, { recommended } from "@starci/eslint-canon-be"
+
+export default [
+    // …your own ignores, language options and other plugins…
+    {
+        files: ["src/**/*.ts"],
+        plugins: { "starci-be": starciBe },
+        rules: recommended,
+    },
+]
+```
+
+Which globs the law applies to is your repository's fact. What the law says is not — so there is no
+option to switch a rule off or lower it to a warning.
+
+Also exported: `rules`, `ruleOwners`, `lawOwners`.
+
+## What it actually catches
+
+A sample, not the list:
+
+| Area | What the rules hold |
+|---|---|
+| **Exceptions** | Every failure throws a domain exception carrying its own identity and metadata — never a bare `Error`, never a framework built-in, never an exception declared outside the exceptions folder |
+| **CQRS** | A handler does not assemble an aggregate inline; reads and writes do not share one path |
+| **Module layering** | An import that climbs a layer it was not given is a build failure, not a review comment |
+| **Data access** | Queries stay where the layer says they may be built |
+| **Transport** | The wire shape is declared, not inferred from whatever a handler happened to return |
+| **Observability** | A failure is logged as a typed exception, so a log line can be traced to the law that names it |
+| **End-to-end flows** | One file, one flow, named steps, and **never sleep** — poll until the state settles, with a deadline |
+| **CDC · event delivery** | Projections and events follow the declared delivery contract |
+| **Comments · naming · type safety** | Comments say why; no double cast through `unknown` |
+
+Every rule names the law that declares it — `ruleOwners` maps rule name to law, so a failing build
+line leads straight to the document that explains why.
+
+## Companion
+
+- **[@starci/eslint-canon-fe](https://www.npmjs.com/package/@starci/eslint-canon-fe)** — the
+  front-end half: 58 rules from 16 laws covering component tiers, structure contracts, the
+  fetch/draw split, vendor boundaries and the design-token scale.
+
+## Where the laws live
+
+Each rule is the enforceable half of a written law. The prose — why the rule exists, what it
+refuses, which cases sit just outside it — is published openly at
+[starci183/starci-claude-skills](https://github.com/starci183/starci-claude-skills).
+
+A rule that cannot be pointed at in real code is a proposal, not a law. Everything here is
+pointed at.
+
+## Requirements
+
+ESLint 9+ (flat config), Node 20.9+.

package/cdc.mjs

@@ -1,44 +1,44 @@
-const isProjectionListener = (filename) => /projection\.listener\.ts$/.test(
-  String(filename || "").replace(/\\/g, "/"),
-) && !String(filename || "").replace(/\\/g, "/").endsWith("/abstract-projection.listener.ts")
-
-const memberName = (member) => member.key && (member.key.name || member.key.value)
-
-/** A projection listener declares mapping while AbstractProjectionListener owns Kafka lifecycle. */
-export const projectionListenerContract = {
-  meta: {
-    type: "problem",
-    docs: { description: "Projection CDC listeners share one Kafka lifecycle contract." },
-    schema: [],
-    messages: {
-      base: "A projection CDC listener extends AbstractProjectionListener; the shared base owns subscription, envelope parsing and failure isolation.",
-      member: "A projection CDC listener must declare `{{name}}`.",
-      lifecycle: "A concrete projection listener must not override `onModuleInit`; Kafka lifecycle belongs to AbstractProjectionListener.",
-    },
-  },
-  create(context) {
-    if (!isProjectionListener(context.filename || context.getFilename())) return {}
-    return {
-      ClassDeclaration(node) {
-        if (!node.superClass || node.superClass.name !== "AbstractProjectionListener") {
-          context.report({ node: node.id || node, messageId: "base" })
-        }
-        const members = node.body.body || []
-        const names = new Set(members.map(memberName))
-        for (const name of ["groupId", "topics", "deriveTargets", "recomputeTarget"]) {
-          if (!names.has(name)) {
-            context.report({ node: node.id || node, messageId: "member", data: { name } })
-          }
-        }
-        const lifecycle = members.find((member) => memberName(member) === "onModuleInit")
-        if (lifecycle) context.report({ node: lifecycle.key, messageId: "lifecycle" })
-      },
-    }
-  },
-}
-
-export const rules = { "projection-listener-contract": projectionListenerContract }
-
-export const recommended = {
-  "starci-be/projection-listener-contract": "error",
-}
+const isProjectionListener = (filename) => /projection\.listener\.ts$/.test(
+  String(filename || "").replace(/\\/g, "/"),
+) && !String(filename || "").replace(/\\/g, "/").endsWith("/abstract-projection.listener.ts")
+
+const memberName = (member) => member.key && (member.key.name || member.key.value)
+
+/** A projection listener declares mapping while AbstractProjectionListener owns Kafka lifecycle. */
+export const projectionListenerContract = {
+  meta: {
+    type: "problem",
+    docs: { description: "Projection CDC listeners share one Kafka lifecycle contract." },
+    schema: [],
+    messages: {
+      base: "A projection CDC listener extends AbstractProjectionListener; the shared base owns subscription, envelope parsing and failure isolation.",
+      member: "A projection CDC listener must declare `{{name}}`.",
+      lifecycle: "A concrete projection listener must not override `onModuleInit`; Kafka lifecycle belongs to AbstractProjectionListener.",
+    },
+  },
+  create(context) {
+    if (!isProjectionListener(context.filename || context.getFilename())) return {}
+    return {
+      ClassDeclaration(node) {
+        if (!node.superClass || node.superClass.name !== "AbstractProjectionListener") {
+          context.report({ node: node.id || node, messageId: "base" })
+        }
+        const members = node.body.body || []
+        const names = new Set(members.map(memberName))
+        for (const name of ["groupId", "topics", "deriveTargets", "recomputeTarget"]) {
+          if (!names.has(name)) {
+            context.report({ node: node.id || node, messageId: "member", data: { name } })
+          }
+        }
+        const lifecycle = members.find((member) => memberName(member) === "onModuleInit")
+        if (lifecycle) context.report({ node: lifecycle.key, messageId: "lifecycle" })
+      },
+    }
+  },
+}
+
+export const rules = { "projection-listener-contract": projectionListenerContract }
+
+export const recommended = {
+  "starci-be/projection-listener-contract": "error",
+}

package/e2e-flow.mjs

@@ -1,213 +1,172 @@
-/**
- * The rules that hold `e2e-flow.md`.
- *
- * FIVE OF THE TWELVE RULES HAVE A MACHINE-CHECKABLE HALF HERE. That is the honest number rather
- * than a gap somebody should close. A rule earns its place by being exact: it must fire on a syntactic shape, not on a
- * judgement, or it becomes something authors learn to disable and the law is worse off than when
- * nothing enforced it.
- *
- * What was measured and left alone, so the next reader does not "finish the job":
- *
- *   - E2E-1 (one file, one flow, named for the sentence). A filename cannot be checked against a
- *     business sentence. `course-purchase.e2e-spec.ts` and `resolver-group.e2e-spec.ts` are the same
- *     shape to a parser and opposite things to a reader.
- *   - E2E-2 (named steps, not one long case). Counting `it` blocks would refuse a flow that is
- *     genuinely one step, and a rule whose first false positive is legitimate teaches authors that
- *     the rule is wrong rather than that they are.
- *   - E2E-5, E2E-6 and E2E-9 turn on WHAT is asserted or WHO is acting, which is meaning.
- *   - E2E-8 (one place stands the world up) is a fact about a repository's fixtures, not about a
- *     file, so it belongs to a gate that can see the tree rather than to a rule that sees one file.
- *   - E2E-10 (a flow logs nothing) is already held: `no-console` and `no-framework-logger` in the
- *     observability law cover every call site, and a second rule saying the same thing in this lane
- *     would double every report.
- *
- * The rules below enforce only exact syntax: transport bypass, absence of any persisted-state read,
- * direct provider imports, sleeps and branches. They do not pretend to judge business meaning.
- */
-
-/** Files this law governs. A flow is a named lane, not every file that happens to touch a database. */
-const isE2eSpec = (filename) => /\.e2e-spec\.ts$/.test(String(filename || "").replace(/\\/g, "/"))
-
-/** Names a repository sleeps by. Awaiting any of them is waiting for a duration instead of a state. */
-const SLEEPERS = new Set(["sleep", "delay", "wait", "pause", "setTimeout"])
-
-/** E2E enters through production transport and never invokes an internal actor directly. */
-export const e2eUsesProductionTransport = {
-  meta: {
-    type: "problem",
-    docs: { description: "Operational E2E keeps the production transport boundary in the proof." },
-    schema: [],
-    messages: {
-      busImport: "`{{name}}` is an internal dispatcher. Enter through GraphQL, HTTP, socket, broker or scheduler.",
-      direct: "Direct `.{{method}}()` skips production routing and delivery semantics.",
-      actor: "Calling `{{name}}` directly bypasses the broker/CQRS boundary that owns it.",
-    },
-  },
-  create(context) {
-    if (!isE2eSpec(context.filename || context.getFilename())) return {}
-    const buses = new Set(["CommandBus", "QueryBus", "EventBus"])
-    return {
-      ImportDeclaration(node) {
-        if (node.source.value !== "@nestjs/cqrs") return
-        for (const specifier of node.specifiers) {
-          if (specifier.type !== "ImportSpecifier") continue
-          const imported = specifier.imported.name || specifier.imported.value
-          if (buses.has(imported)) context.report({ node: specifier, messageId: "busImport", data: { name: imported } })
-        }
-      },
-      CallExpression(node) {
-        const callee = node.callee
-        if (callee.type !== "MemberExpression" || callee.computed) return
-        const method = callee.property.name
-        if (method === "execute" || method === "process") {
-          context.report({ node: callee.property, messageId: "direct", data: { method } })
-          return
-        }
-        let receiver = callee.object
-        while (receiver && ["TSAsExpression", "TSTypeAssertion", "ChainExpression"].includes(receiver.type)) receiver = receiver.expression
-        if (receiver && receiver.type === "Identifier" && /(?:Worker|Handler)$/.test(receiver.name)) {
-          context.report({ node: callee.property, messageId: "actor", data: { name: receiver.name } })
-        }
-      },
-    }
-  },
-}
-
-/** E2E reads the consequence from persistent state rather than only its response envelope. */
-export const e2eAssertsPersistedState = {
-  meta: {
-    type: "problem",
-    docs: { description: "E2E reads a persisted business consequence." },
-    schema: [],
-    messages: { state: "This E2E never reads persisted state back; an envelope alone is not a business consequence." },
-  },
-  create(context) {
-    if (!isE2eSpec(context.filename || context.getFilename())) return {}
-    let readsState = false
-    const readers = /^(?:entityManager|dataSource|EntityManager|DataSource|getRepository|queryRunner)$/
-    return {
-      Identifier(node) { if (readers.test(node.name)) readsState = true },
-      "Program:exit"(node) { if (!readsState) context.report({ node, messageId: "state" }) },
-    }
-  },
-}
-
-/** Model quality belongs in harness; E2E scripts only the provider boundary. */
-export const noModelCallInE2e = {
-  meta: {
-    type: "problem",
-    docs: { description: "E2E never reaches a paid or nondeterministic model provider." },
-    schema: [],
-    messages: { provider: "`{{source}}` reaches a model provider from E2E. Script the external result and keep internal policy real." },
-  },
-  create(context) {
-    if (!isE2eSpec(context.filename || context.getFilename())) return {}
-    const providers = /^(?:@anthropic-ai\/|openai$|openai\/|ollama$|@google\/generative-ai|@mistralai\/|cohere-ai)/
-    return {
-      ImportDeclaration(node) {
-        const source = node.source.value
-        if (typeof source === "string" && providers.test(source)) context.report({ node, messageId: "provider", data: { source } })
-      },
-    }
-  },
-}
-
-// -- E2E-3 ----------------------------------------------------------------------------------------
-
-/** A flow polls until the state settles; it never waits for a duration. */
-export const noSleepInFlow = {
-  meta: {
-    type: "problem",
-    docs: { description: "A flow polls for the state it needs, with a deadline. It never sleeps." },
-    schema: [],
-    messages: {
-      sleep:
-        "`{{name}}` waits for a DURATION, and a duration is a guess about somebody else's machine. It is too long on the machine that passes - every run pays it - and too short on the one that matters, where it fails as a flake nobody can reproduce. Poll for the state you are actually waiting for, with a deadline, so the test says what it wanted rather than how long it was willing to sit there.",
-      timer:
-        "A promise around `setTimeout` is a sleep with the name taken off. The objection is the same: nothing here says which state the flow is waiting for, so the failure message when it expires names a timeout instead of the thing that never happened. Poll the state, with a deadline.",
-    },
-  },
-  create(context) {
-    if (!isE2eSpec(context.filename || context.getFilename())) return {}
-    return {
-      CallExpression(node) {
-        const callee = node.callee
-        if (!callee || callee.type !== "Identifier" || !SLEEPERS.has(callee.name)) return
-        // A `setTimeout` wrapped in `new Promise` is reported once, as `timer`, by the branch below.
-        // Reporting it here as well would put two findings on one sleep and teach nobody anything.
-        for (let current = node.parent; current; current = current.parent) {
-          if (current.type === "NewExpression" && current.callee && current.callee.name === "Promise") return
-        }
-        context.report({ node, messageId: "sleep", data: { name: callee.name } })
-      },
-      NewExpression(node) {
-        if (!node.callee || node.callee.name !== "Promise") return
-        const source = context.sourceCode || context.getSourceCode()
-        if (/setTimeout/.test(source.getText(node))) context.report({ node, messageId: "timer" })
-      },
-    }
-  },
-}
-
-// -- E2E-7 ----------------------------------------------------------------------------------------
-
-/** A step asserts one outcome. A branch means the test is prepared for either, which is no assertion. */
-export const noBranchInFlowStep = {
-  meta: {
-    type: "problem",
-    docs: { description: "A flow step takes no branch: it asserts the one outcome the business promises." },
-    schema: [],
-    messages: {
-      branch:
-        "A branch inside a step means this test passes down either path, so a green run stops being evidence that the business worked - it only proves the code reached the end. The flow knows which outcome it is asserting: state it. If two outcomes are both legitimate, they are two steps, or two flows.",
-    },
-  },
-  create(context) {
-    if (!isE2eSpec(context.filename || context.getFilename())) return {}
-    const source = context.sourceCode || context.getSourceCode()
-
-    /** True when this node sits inside the callback of an `it(...)`. */
-    const insideStep = (node) => {
-      for (let current = node.parent; current; current = current.parent) {
-        if (current.type !== "CallExpression") continue
-        const callee = current.callee
-        const name = callee && (callee.name || (callee.object && callee.object.name))
-        if (name === "it" || name === "test") return true
-      }
-      return false
-    }
-
-    const report = (node) => {
-      if (insideStep(node)) context.report({ node, messageId: "branch" })
-    }
-
-    return {
-      IfStatement: report,
-      ConditionalExpression: report,
-      SwitchStatement: report,
-      LogicalExpression(node) {
-        // `a && b` used as a STATEMENT is a hidden if; the same operator inside an assertion is not
-        if (node.parent && node.parent.type === "ExpressionStatement") report(node)
-        // touching the source keeps the helper honest if the shape ever changes
-        void source
-      },
-    }
-  },
-}
-
-/** The rules this law contributes to the plugin. */
-export const rules = {
-  "e2e-uses-production-transport": e2eUsesProductionTransport,
-  "e2e-asserts-persisted-state": e2eAssertsPersistedState,
-  "no-model-call-in-e2e": noModelCallInE2e,
-  "no-sleep-in-flow": noSleepInFlow,
-  "no-branch-in-flow-step": noBranchInFlowStep,
-}
-
-/**
- * The level this law asks for, as the plugin's own opinion.
- *
- * Both are exact and both fire on a syntactic shape rather than on a judgement, so neither carries
- * the false-positive risk that would justify adopting it at `warn`.
- */
-export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-be/${name}`, "error"]))
+/**
+ * The rules that hold `e2e-flow.md`.
+ *
+ * FIVE OF THE TWELVE RULES HAVE A MACHINE-CHECKABLE HALF HERE. That is the honest number rather
+ * than a gap somebody should close. A rule earns its place by being exact: it must fire on a syntactic shape, not on a
+ * judgement, or it becomes something authors learn to disable and the law is worse off than when
+ * nothing enforced it.
+ *
+ * What was measured and left alone, so the next reader does not "finish the job":
+ *
+ *   - E2E-1 (one file, one flow, named for the sentence). A filename cannot be checked against a
+ *     business sentence. `course-purchase.e2e-spec.ts` and `resolver-group.e2e-spec.ts` are the same
+ *     shape to a parser and opposite things to a reader.
+ *   - E2E-2 (named steps, not one long case). Counting `it` blocks would refuse a flow that is
+ *     genuinely one step, and a rule whose first false positive is legitimate teaches authors that
+ *     the rule is wrong rather than that they are.
+ *   - E2E-5, E2E-6 and E2E-9 turn on WHAT is asserted or WHO is acting, which is meaning.
+ *   - E2E-8 (one place stands the world up) is a fact about a repository's fixtures, not about a
+ *     file, so it belongs to a gate that can see the tree rather than to a rule that sees one file.
+ *   - E2E-10 (a flow logs nothing) is already held: `no-console` and `no-framework-logger` in the
+ *     observability law cover every call site, and a second rule saying the same thing in this lane
+ *     would double every report.
+ *
+ * The rules below enforce only exact syntax: transport bypass, absence of any persisted-state read,
+ * direct provider imports, sleeps and branches. They do not pretend to judge business meaning.
+ */
+
+/** Files this law governs. A flow is a named lane, not every file that happens to touch a database. */
+const isE2eSpec = (filename) => /\.e2e-spec\.ts$/.test(String(filename || "").replace(/\\/g, "/"))
+
+/** Names a repository sleeps by. Awaiting any of them is waiting for a duration instead of a state. */
+const SLEEPERS = new Set(["sleep", "delay", "wait", "pause", "setTimeout"])
+
+/** E2E enters through production transport and never invokes an internal actor directly. */
+export const e2eUsesProductionTransport = {
+  meta: {
+    type: "problem",
+    docs: { description: "Operational E2E keeps the production transport boundary in the proof." },
+    schema: [],
+    messages: {
+      busImport: "`{{name}}` is an internal dispatcher. Enter through GraphQL, HTTP, socket, broker or scheduler.",
+      direct: "Direct `.{{method}}()` skips production routing and delivery semantics.",
+      actor: "Calling `{{name}}` directly bypasses the broker/CQRS boundary that owns it.",
+    },
+  },
+  create(context) {
+    if (!isE2eSpec(context.filename || context.getFilename())) return {}
+    const buses = new Set(["CommandBus", "QueryBus", "EventBus"])
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== "@nestjs/cqrs") return
+        for (const specifier of node.specifiers) {
+          if (specifier.type !== "ImportSpecifier") continue
+          const imported = specifier.imported.name || specifier.imported.value
+          if (buses.has(imported)) context.report({ node: specifier, messageId: "busImport", data: { name: imported } })
+        }
+      },
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== "MemberExpression" || callee.computed) return
+        const method = callee.property.name
+        if (method === "execute" || method === "process") {
+          context.report({ node: callee.property, messageId: "direct", data: { method } })
+          return
+        }
+        let receiver = callee.object
+        while (receiver && ["TSAsExpression", "TSTypeAssertion", "ChainExpression"].includes(receiver.type)) receiver = receiver.expression
+        if (receiver && receiver.type === "Identifier" && /(?:Worker|Handler)$/.test(receiver.name)) {
+          context.report({ node: callee.property, messageId: "actor", data: { name: receiver.name } })
+        }
+      },
+    }
+  },
+}
+
+// -- E2E-3 ----------------------------------------------------------------------------------------
+
+/** A flow polls until the state settles; it never waits for a duration. */
+export const noSleepInFlow = {
+  meta: {
+    type: "problem",
+    docs: { description: "A flow polls for the state it needs, with a deadline. It never sleeps." },
+    schema: [],
+    messages: {
+      sleep:
+        "`{{name}}` waits for a DURATION, and a duration is a guess about somebody else's machine. It is too long on the machine that passes - every run pays it - and too short on the one that matters, where it fails as a flake nobody can reproduce. Poll for the state you are actually waiting for, with a deadline, so the test says what it wanted rather than how long it was willing to sit there.",
+      timer:
+        "A promise around `setTimeout` is a sleep with the name taken off. The objection is the same: nothing here says which state the flow is waiting for, so the failure message when it expires names a timeout instead of the thing that never happened. Poll the state, with a deadline.",
+    },
+  },
+  create(context) {
+    if (!isE2eSpec(context.filename || context.getFilename())) return {}
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (!callee || callee.type !== "Identifier" || !SLEEPERS.has(callee.name)) return
+        // A `setTimeout` wrapped in `new Promise` is reported once, as `timer`, by the branch below.
+        // Reporting it here as well would put two findings on one sleep and teach nobody anything.
+        for (let current = node.parent; current; current = current.parent) {
+          if (current.type === "NewExpression" && current.callee && current.callee.name === "Promise") return
+        }
+        context.report({ node, messageId: "sleep", data: { name: callee.name } })
+      },
+      NewExpression(node) {
+        if (!node.callee || node.callee.name !== "Promise") return
+        const source = context.sourceCode || context.getSourceCode()
+        if (/setTimeout/.test(source.getText(node))) context.report({ node, messageId: "timer" })
+      },
+    }
+  },
+}
+
+// -- E2E-7 ----------------------------------------------------------------------------------------
+
+/** A step asserts one outcome. A branch means the test is prepared for either, which is no assertion. */
+export const noBranchInFlowStep = {
+  meta: {
+    type: "problem",
+    docs: { description: "A flow step takes no branch: it asserts the one outcome the business promises." },
+    schema: [],
+    messages: {
+      branch:
+        "A branch inside a step means this test passes down either path, so a green run stops being evidence that the business worked - it only proves the code reached the end. The flow knows which outcome it is asserting: state it. If two outcomes are both legitimate, they are two steps, or two flows.",
+    },
+  },
+  create(context) {
+    if (!isE2eSpec(context.filename || context.getFilename())) return {}
+    const source = context.sourceCode || context.getSourceCode()
+
+    /** True when this node sits inside the callback of an `it(...)`. */
+    const insideStep = (node) => {
+      for (let current = node.parent; current; current = current.parent) {
+        if (current.type !== "CallExpression") continue
+        const callee = current.callee
+        const name = callee && (callee.name || (callee.object && callee.object.name))
+        if (name === "it" || name === "test") return true
+      }
+      return false
+    }
+
+    const report = (node) => {
+      if (insideStep(node)) context.report({ node, messageId: "branch" })
+    }
+
+    return {
+      IfStatement: report,
+      ConditionalExpression: report,
+      SwitchStatement: report,
+      LogicalExpression(node) {
+        // `a && b` used as a STATEMENT is a hidden if; the same operator inside an assertion is not
+        if (node.parent && node.parent.type === "ExpressionStatement") report(node)
+        // touching the source keeps the helper honest if the shape ever changes
+        void source
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "e2e-uses-production-transport": e2eUsesProductionTransport,
+  "no-sleep-in-flow": noSleepInFlow,
+  "no-branch-in-flow-step": noBranchInFlowStep,
+}
+
+/**
+ * The level this law asks for, as the plugin's own opinion.
+ *
+ * Both are exact and both fire on a syntactic shape rather than on a judgement, so neither carries
+ * the false-positive risk that would justify adopting it at `warn`.
+ */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-be/${name}`, "error"]))

package/event-delivery.mjs

@@ -1,40 +1,40 @@
-const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
-
-/** The NATS bridge rejects self-echo and claims redelivery before local fan-out. */
-export const natsBridgeDeliveryContract = {
-  meta: {
-    type: "problem",
-    docs: { description: "The central NATS bridge preserves cross-instance delivery invariants." },
-    schema: [],
-    messages: {
-      origin: "Drop envelopes whose producer id matches this instance before local emit.",
-      digest: "Claim/check the envelope digest before local emit so redelivery is idempotent.",
-    },
-  },
-  create(context) {
-    if (!normalizePath(context.filename || context.getFilename()).endsWith(
-      "/event/nats/nats-bridge.service.ts",
-    )) return {}
-    return {
-      "Program:exit"(node) {
-        const source = context.sourceCode || context.getSourceCode()
-        const text = source.getText()
-        const originIndex = text.search(/parsed\.id\s*===\s*this\.instanceService\.getId\(\)/)
-        const digestIndex = text.indexOf("parsed.digest")
-        const emitIndex = text.indexOf("this.eventEmitter.emit")
-        if (originIndex < 0 || emitIndex < 0 || originIndex > emitIndex) {
-          context.report({ node, messageId: "origin" })
-        }
-        if (digestIndex < 0 || emitIndex < 0 || digestIndex > emitIndex) {
-          context.report({ node, messageId: "digest" })
-        }
-      },
-    }
-  },
-}
-
-export const rules = { "nats-bridge-delivery-contract": natsBridgeDeliveryContract }
-
-export const recommended = {
-  "starci-be/nats-bridge-delivery-contract": "error",
-}
+const normalizePath = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** The NATS bridge rejects self-echo and claims redelivery before local fan-out. */
+export const natsBridgeDeliveryContract = {
+  meta: {
+    type: "problem",
+    docs: { description: "The central NATS bridge preserves cross-instance delivery invariants." },
+    schema: [],
+    messages: {
+      origin: "Drop envelopes whose producer id matches this instance before local emit.",
+      digest: "Claim/check the envelope digest before local emit so redelivery is idempotent.",
+    },
+  },
+  create(context) {
+    if (!normalizePath(context.filename || context.getFilename()).endsWith(
+      "/event/nats/nats-bridge.service.ts",
+    )) return {}
+    return {
+      "Program:exit"(node) {
+        const source = context.sourceCode || context.getSourceCode()
+        const text = source.getText()
+        const originIndex = text.search(/parsed\.id\s*===\s*this\.instanceService\.getId\(\)/)
+        const digestIndex = text.indexOf("parsed.digest")
+        const emitIndex = text.indexOf("this.eventEmitter.emit")
+        if (originIndex < 0 || emitIndex < 0 || originIndex > emitIndex) {
+          context.report({ node, messageId: "origin" })
+        }
+        if (digestIndex < 0 || emitIndex < 0 || digestIndex > emitIndex) {
+          context.report({ node, messageId: "digest" })
+        }
+      },
+    }
+  },
+}
+
+export const rules = { "nats-bridge-delivery-contract": natsBridgeDeliveryContract }
+
+export const recommended = {
+  "starci-be/nats-bridge-delivery-contract": "error",
+}

package/index.mjs

@@ -54,12 +54,29 @@ const CONTRIBUTIONS = [
 /** Every gathered law. */
 export const lawOwners = CONTRIBUTIONS.map((entry) => entry.law)
 
+/**
+ * Every (law, rule name) pair as DECLARED, before any collapsing.
+ *
+ * This exists because `ruleOwners` and `rules` below are both built with `Object.fromEntries`, which
+ * silently keeps the last writer when two laws declare one name. A test that walks either of them
+ * therefore cannot see a collision: the duplicate is already gone by the time it looks, so every
+ * name appears exactly once BY CONSTRUCTION and the check passes forever while being blind.
+ *
+ * That is exactly what happened - three back-end rules were declared by two laws each, one copy was
+ * discarded on import, and the guard reported green the whole time. A gate that cannot fail is
+ * indistinguishable from no gate, so the raw declarations are published here and the guard walks
+ * these instead.
+ */
+export const ruleDeclarations = CONTRIBUTIONS.flatMap((entry) =>
+  Object.keys(entry.rules).map((name) => ({ law: entry.law, name })),
+)
+
 /**
  * Which law declares each rule.
  *
  * Exported because a failing rule is a question about a LAW, and the shortest path from a build log
- * to the document that explains it is this map. It is also what the twin test walks to prove no two
- * laws claim one name.
+ * to the document that explains it is this map. It answers "who owns this name" for a name that
+ * SHIPPED; proving no two laws claim one name is `ruleDeclarations`' job, not this map's.
  */
 export const ruleOwners = Object.fromEntries(
     CONTRIBUTIONS.flatMap((entry) => Object.keys(entry.rules).map((name) => [name, entry.law])),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-be",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
   "type": "module",
   "license": "UNLICENSED",

package/testing.mjs

@@ -171,50 +171,6 @@ export const noModelCallInE2e = {
   },
 }
 
-// -- TESTING-3 -------------------------------------------------------------------------------------
-
-/** CQRS application buses are internal dispatchers, never production entry points. */
-const APPLICATION_BUSES = new Set(["CommandBus", "QueryBus", "EventBus"])
-
-/** Methods whose direct invocation skips the transport owned by production. */
-const INTERNAL_ENTRY_METHODS = new Set(["execute", "process"])
-
-/** An e2e enters through a production transport rather than an application object. */
-export const e2eUsesProductionTransport = {
-  meta: {
-    type: "problem",
-    docs: { description: "An e2e enters through GraphQL, HTTP, socket, broker or scheduler transport." },
-    schema: [],
-    messages: {
-      busImport:
-        "`{{name}}` is an application dispatcher, not a production transport. An e2e must enter through GraphQL, HTTP, a real socket, a broker message or the scheduler boundary so routing, guards, validation and serialization are part of the proof.",
-      direct:
-        "Direct `.{{method}}()` invocation skips the production transport and starts inside the application. Move this decision/wiring test to the integration lane, or drive the flow through GraphQL, HTTP, a real socket, broker or scheduler boundary.",
-    },
-  },
-  create(context) {
-    if (!isE2eSpec(context.filename || context.getFilename())) return {}
-    return {
-      ImportDeclaration(node) {
-        if (!node.source || node.source.value !== "@nestjs/cqrs") return
-        for (const specifier of node.specifiers) {
-          if (specifier.type !== "ImportSpecifier") continue
-          const imported = specifier.imported && (specifier.imported.name || specifier.imported.value)
-          if (!APPLICATION_BUSES.has(imported)) continue
-          context.report({ node: specifier, messageId: "busImport", data: { name: imported } })
-        }
-      },
-      CallExpression(node) {
-        const callee = node.callee
-        if (!callee || callee.type !== "MemberExpression" || callee.computed) return
-        const method = callee.property && callee.property.name
-        if (!INTERNAL_ENTRY_METHODS.has(method)) return
-        context.report({ node: callee.property, messageId: "direct", data: { method } })
-      },
-    }
-  },
-}
-
 // -- TESTING-10 ------------------------------------------------------------------------------------
 
 /** Official provider clients that a harness may call without a house routing layer. */
@@ -326,7 +282,6 @@ export const rules = {
   "no-call-only-spec": noCallOnlySpec,
   "e2e-asserts-persisted-state": e2eAssertsPersistedState,
   "no-model-call-in-e2e": noModelCallInE2e,
-  "e2e-uses-production-transport": e2eUsesProductionTransport,
   "harness-calls-provider-directly": harnessCallsProviderDirectly,
 }
 
@@ -348,6 +303,5 @@ export const recommended = {
   "starci-be/no-call-only-spec": "error", // no=0 of 182 - burned down from 1
   "starci-be/e2e-asserts-persisted-state": "error", // no=0 of 47 - burned down from 1
   "starci-be/no-model-call-in-e2e": "error", // no=0 of 47
-  "starci-be/e2e-uses-production-transport": "error",
   "starci-be/harness-calls-provider-directly": "error",
 }

package/transport.mjs

@@ -1,103 +1,103 @@
-const normalize = (filename) => String(filename || "").replace(/\\/g, "/")
-
-/** The decorator's own name, whether it was written `@Controller` or `@Controller("x")`. */
-const decoratorName = (node) => {
-  const expression = node.expression
-  if (!expression) return null
-  if (expression.type === "Identifier") return expression.name
-  if (expression.type === "CallExpression" && expression.callee.type === "Identifier") {
-    return expression.callee.name
-  }
-  return null
-}
-
-/** The route string, or "" for `@Controller()` and for a path given as an object. */
-const routeOf = (node) => {
-  const expression = node.expression
-  if (!expression || expression.type !== "CallExpression") return ""
-  const first = expression.arguments[0]
-  if (first && first.type === "Literal" && typeof first.value === "string") return first.value
-  return ""
-}
-
-/**
- * Which of the four sanctioned reasons this file shows, if any.
- *
- * READ OFF THE FILE, NOT OFF A LIST. A registry of blessed routes rots the moment somebody adds a
- * route and forgets it; the evidence here is the same evidence a reader would use.
- */
-const reasonFor = (route, filename, text) => {
-  const path = normalize(filename)
-  // a probe answers when the app is degraded, before the feature layer is necessarily up
-  if (/^healthz?$/.test(route) || /\/health(z)?[./]/.test(path)) return "probe"
-  // something outside posts to a URL we gave it, and it will never send a GraphQL document
-  if (/webhook/i.test(route) || /webhook/i.test(path)) return "external"
-  // bytes, not fields: multipart in, stream out
-  if (/FileInterceptor|FilesInterceptor|AnyFilesInterceptor|StreamableFile|@Res\s*\(|createReadStream/.test(text)) {
-    return "bytes"
-  }
-  // a machine registering itself, with no user session to carry
-  if (/^(pods|internal|agents)\//.test(route)) return "machine"
-  // an identity that is not a user session - a platform operator or a service token
-  if (/^api\/ops(\/|$)/.test(route) || /Operator[A-Za-z]*Guard|ServiceToken|OPS_TOKEN/.test(text)) {
-    return "operator"
-  }
-  return null
-}
-
-/** A REST door exists only where GraphQL cannot go, and the file has to show which case it is. */
-export const restDoorNeedsAReason = {
-  meta: {
-    type: "problem",
-    docs: { description: "A @Controller is permitted only where GraphQL cannot serve." },
-    schema: [],
-    messages: {
-      unjustified:
-        "This REST door shows none of the four reasons a door may not be GraphQL: an external system posting to a fixed URL, a payload of bytes rather than fields, a machine with no user session, or an identity that is not one. A plain JSON read belongs in the GraphQL schema, where the client already is.",
-    },
-  },
-  create(context) {
-    const filename = context.filename || context.getFilename()
-    const text = (context.sourceCode || context.getSourceCode()).getText()
-    return {
-      Decorator(node) {
-        if (decoratorName(node) !== "Controller") return
-        if (reasonFor(routeOf(node), filename, text)) return
-        context.report({ node, messageId: "unjustified" })
-      },
-    }
-  },
-}
-
-/** A door is a door whatever its transport, and every door in this repository lives in features/. */
-export const doorLivesInFeatures = {
-  meta: {
-    type: "problem",
-    docs: { description: "HTTP doors sit under features/, beside the GraphQL ones." },
-    schema: [],
-    messages: {
-      wrongTree:
-        "A @Controller under src/modules/ is a door parked among the capabilities it calls, where it reads as one and gets imported like one. Every GraphQL door in this repository already lives under features/; transport was never what decided the address.",
-    },
-  },
-  create(context) {
-    const path = normalize(context.filename || context.getFilename())
-    if (!/\/src\/modules\//.test(path)) return {}
-    return {
-      Decorator(node) {
-        if (decoratorName(node) !== "Controller") return
-        context.report({ node, messageId: "wrongTree" })
-      },
-    }
-  },
-}
-
-export const rules = {
-  "rest-door-needs-a-reason": restDoorNeedsAReason,
-  "door-lives-in-features": doorLivesInFeatures,
-}
-
-export const recommended = {
-  "starci-be/rest-door-needs-a-reason": "error",
-  "starci-be/door-lives-in-features": "error",
-}
+const normalize = (filename) => String(filename || "").replace(/\\/g, "/")
+
+/** The decorator's own name, whether it was written `@Controller` or `@Controller("x")`. */
+const decoratorName = (node) => {
+  const expression = node.expression
+  if (!expression) return null
+  if (expression.type === "Identifier") return expression.name
+  if (expression.type === "CallExpression" && expression.callee.type === "Identifier") {
+    return expression.callee.name
+  }
+  return null
+}
+
+/** The route string, or "" for `@Controller()` and for a path given as an object. */
+const routeOf = (node) => {
+  const expression = node.expression
+  if (!expression || expression.type !== "CallExpression") return ""
+  const first = expression.arguments[0]
+  if (first && first.type === "Literal" && typeof first.value === "string") return first.value
+  return ""
+}
+
+/**
+ * Which of the four sanctioned reasons this file shows, if any.
+ *
+ * READ OFF THE FILE, NOT OFF A LIST. A registry of blessed routes rots the moment somebody adds a
+ * route and forgets it; the evidence here is the same evidence a reader would use.
+ */
+const reasonFor = (route, filename, text) => {
+  const path = normalize(filename)
+  // a probe answers when the app is degraded, before the feature layer is necessarily up
+  if (/^healthz?$/.test(route) || /\/health(z)?[./]/.test(path)) return "probe"
+  // something outside posts to a URL we gave it, and it will never send a GraphQL document
+  if (/webhook/i.test(route) || /webhook/i.test(path)) return "external"
+  // bytes, not fields: multipart in, stream out
+  if (/FileInterceptor|FilesInterceptor|AnyFilesInterceptor|StreamableFile|@Res\s*\(|createReadStream/.test(text)) {
+    return "bytes"
+  }
+  // a machine registering itself, with no user session to carry
+  if (/^(pods|internal|agents)\//.test(route)) return "machine"
+  // an identity that is not a user session - a platform operator or a service token
+  if (/^api\/ops(\/|$)/.test(route) || /Operator[A-Za-z]*Guard|ServiceToken|OPS_TOKEN/.test(text)) {
+    return "operator"
+  }
+  return null
+}
+
+/** A REST door exists only where GraphQL cannot go, and the file has to show which case it is. */
+export const restDoorNeedsAReason = {
+  meta: {
+    type: "problem",
+    docs: { description: "A @Controller is permitted only where GraphQL cannot serve." },
+    schema: [],
+    messages: {
+      unjustified:
+        "This REST door shows none of the four reasons a door may not be GraphQL: an external system posting to a fixed URL, a payload of bytes rather than fields, a machine with no user session, or an identity that is not one. A plain JSON read belongs in the GraphQL schema, where the client already is.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    const text = (context.sourceCode || context.getSourceCode()).getText()
+    return {
+      Decorator(node) {
+        if (decoratorName(node) !== "Controller") return
+        if (reasonFor(routeOf(node), filename, text)) return
+        context.report({ node, messageId: "unjustified" })
+      },
+    }
+  },
+}
+
+/** A door is a door whatever its transport, and every door in this repository lives in features/. */
+export const doorLivesInFeatures = {
+  meta: {
+    type: "problem",
+    docs: { description: "HTTP doors sit under features/, beside the GraphQL ones." },
+    schema: [],
+    messages: {
+      wrongTree:
+        "A @Controller under src/modules/ is a door parked among the capabilities it calls, where it reads as one and gets imported like one. Every GraphQL door in this repository already lives under features/; transport was never what decided the address.",
+    },
+  },
+  create(context) {
+    const path = normalize(context.filename || context.getFilename())
+    if (!/\/src\/modules\//.test(path)) return {}
+    return {
+      Decorator(node) {
+        if (decoratorName(node) !== "Controller") return
+        context.report({ node, messageId: "wrongTree" })
+      },
+    }
+  },
+}
+
+export const rules = {
+  "rest-door-needs-a-reason": restDoorNeedsAReason,
+  "door-lives-in-features": doorLivesInFeatures,
+}
+
+export const recommended = {
+  "starci-be/rest-door-needs-a-reason": "error",
+  "starci-be/door-lives-in-features": "error",
+}