@starci/eslint-canon-be 1.2.2 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 1.7.0 - 2026-09-30
+
+- New: `named-entity-manager-only` (R83 `BE_UNNAMED_DATA_ACCESS`, in `data-access`): a bare `@InjectEntityManager()` with no connection argument, any `.getRepository(...)` call (on a DataSource, an EntityManager or a transaction manager) and an injected `DataSource` (a constructor parameter typed `DataSource`, `@InjectDataSource()`, `@InjectConnection()`) are refused. A `DataSource` is allowed only under `platform/database/` or `platform/databases/` (also `platform/db`, `platform/datasource`, `platform/typeorm`) and `apps/migrate/`; spec files are skipped. The message says to inject the shared EntityManager with the named injector and call it directly.
+- Changed: `no-injected-repository` now refuses `@InjectRepository(...)` wherever it is written (a property or a method parameter, not only a constructor parameter), and its message states the same one pattern.
+
+## 1.6.1 - 2026-09-30
+
+- Fixed: `inbox-dedupe-required` (R80 `BE_INBOX_DEDUPE_MISSING`) no longer relies only on `<event>.consumer.ts` under `transport/message/` to recognize a consumer. A method decorated `@EventPattern`, `@MessagePattern`, `@OnEvent` or `@Process`, or a class whose name ends `Consumer` or `OutboxConsumer`, is now a consumer wherever the file sits. The producer half of an outbox (typically `*-outbox.service.ts` / `*OutboxService`, which reads pending rows and publishes) carries none of those shapes and stays unflagged unless it also consumes.
+
+## 1.6.0 - 2026-09-30
+
+Round 3 back-end rules (catalog R78 to R82), each with RuleTester specs and a why code in `modules/kernel/failure-codes.yaml`.
+
+- New: `user-copy-through-catalog` (R78 `BE_USER_COPY_LITERAL`, new law `user-copy`): a literal exception message, a `subject`/`title`/`body`/`text`/`message` property of a `notify`/`send`/`publish` call, or a `message`/`description`/`title` property of a `transport/` response comes from the per-capability messages catalog through the typed `MessageCatalog` port; a short code-shaped literal (`UPPER_SNAKE`, a bare word) and a template literal are left alone. `no-ambient-clock` (R79 `BE_AMBIENT_CLOCK`, new law `temporal`): `Date.now()`, a bare `new Date()` and `performance.now()` are read only inside `platform/clock`; `new Date(value)` built from a value the caller already holds is exempt. `inbox-dedupe-required` (R80 `BE_INBOX_DEDUPE_MISSING`, new law `idempotency`): a `@Public()` webhook controller and an outbox/queue consumer (`<event>.consumer.ts`) show a reference to an inbox or dedupe port before they act. `no-hand-rolled-retry` (R81 `BE_HAND_ROLLED_RETRY`, in `resilience`): a `for`, `while` or `do...while` loop that both catches an error and calls something shaped like a delay (`sleep`, `delay`, `wait`, `backoff`, `setTimeout`) goes through `platform/retry`; a polling loop with no `catch` is exempt, same as `no-query-in-loop` exempts a polling `while`. `no-external-call-in-transaction` (R82 `BE_TRANSACTION_EXTERNAL_CALL`, in `data-access`): `fetch`, an HTTP client call or any method of a `*Client`/`*Sdk` receiver does not run inside `.transaction(async (tx) => ...)`.
+- Slot manifest (`knowledge/hfs/slots.yaml`, no version bump, additions stamped `since: 1.0.0`): `be.domain.messages` (`src/modules/{domain,integrations}/<capability>/messages/`) and `be.feature.messages` (`src/features/<feature>/messages/`), each an optional per-capability or per-feature vi/en catalog; `be.platform`'s required instances gain `clock` (the injected `Clock` port) and `i18n` (the `MessageCatalog` port); `be.domain` and `be.feature` allow a `messages/` folder.
+- Deferred (owner ruling, no rule): floating promises; core `no-await-in-loop` is not adopted.
+
+## 1.5.0 - 2026-09-30
+
+- New: `no-query-in-loop` (R77 `BE_QUERY_IN_LOOP`): a repository, entity-manager or query-builder read (`find`, `findOne`, `count`, `getOne`, a raw `SELECT`) inside a `for`, `for...of`, `for...in` or an array `map`, `forEach`, `flatMap`, `filter`, `reduce`, `some` or `every` callback is one round trip per element (N+1). A polling `while` loop and a write per element are not reported.
+
+## 1.4.0 - 2026-09-30
+
+Round 2 back-end rules (catalog R42, R68 to R76). Every rule below has RuleTester specs and a why code in `modules/kernel/failure-codes.yaml`; each was measured against nivo-backend, starci-next and mia-mia-backend before it shipped and is on at `error`.
+
+- New: `no-interpolated-sql` (R68: SQL text carries no runtime substitution; a constant column list, a `${n}` placeholder, `quoteIdent(...)`, `sqlSetClause(...)` and a ternary of fixed strings are the only substitutions), `query-needs-limit` (R69: `getMany`, `getRawMany`, `find`, `findBy` and a raw `SELECT` state a bound; a lookup by `id` and an aggregate are exempt), `http-needs-timeout` (R70: `fetch` carries a `signal`, axios and HttpService calls carry `timeout` or `signal`, `axios.create` a `timeout`), `no-secret-in-log` (R71: a logger call names no credential and no personal identifier), `no-never-cast` and `no-non-null-assertion` (R72), `async-needs-await` (R73: an `async` function that never awaits; a class that extends or implements, a decorated method and a generator are exempt), `migration-down-reversible` (R74: `down()` exists, is not empty and is not a bare throw), `explicit-handler-return-type` (R75), `json-parse-needs-guard` (R76), and `dto-needs-validator` (R42: every property of an input class carries a `class-validator` decorator).
+- New laws: `query-safety`, `resilience`, `log-safety`, `async-discipline`, `input-bounds`; `type-safety` and `schema-authority` gain rules.
+
+## 1.3.0 - 2026-09-29
+
+HFS back-end rules (catalog R18, R20, R34, R36-R38, R40-R45, R48). Every rule below has RuleTester specs and a why code in `modules/kernel/failure-codes.yaml`.
+
+- New: `catch-must-account` (R40), `error-home` (R38), `no-runtime-schema` (R34), `sql-only-in-repository` (R36), `no-entity-in-contract` (R37), `no-untyped-body` and `public-needs-reason` (R41), `no-direct-env-read` (R43), `no-secret-default` (R44), `secret-compare-timing-safe` (R41), `global-module-allowlist`, `typed-module-definition`, `static-module-register`, `no-new-injectable`, `no-module-let`, `one-module-per-file` (R45), `no-inline-suppression` (R18), `file-size-growth` (R20 ratchet; the soft budget is a hfs check report item, not a lint warning), `spec-no-source-read` and `spec-typed-doubles` (R48).
+- Fixed: `must-deep-module-import` now holds the HFS owner surface. An aliased import names the owner and stops (`@modules/domain/plan`, `@features/plan`, or the explicit `/index`); a path into a file of another owner is refused, and a tier-only or root alias still is. The retired `lib` tier no longer counts as a tier. `no-folder-reexport` accepts a named `index.ts` surface (`export { X } from "./x"`, `export type { T } from "./contracts"`), and refuses `export *`, a `*_STORE` token, a whole `types` folder and an entry wider than the manifest's `indexExports` (60). Both are on again in `starciBeConfig`.
+- Removed: no rule is off. The retired-rule list (`RETIRED`) and its export are gone, and so are the rules it switched off: `exception-name-ends-in-exception`, `exception-code-matches-class-name`, `exception-metadata-type-named-for-class`, `exception-extends-abstract`, `exception-in-errors-folder`, `require-exception-object-arg`, `throw-abstract-exception` (the Academy `AbstractException` family, replaced by `error-home`), `no-handler-encoded-failure` (expected refusals are typed unions), `handler-has-twin-spec`, `no-self-global-module` (replaced by `global-module-allowlist`), `no-line-suppression` and `require-vn-ok-reason` (replaced by `no-inline-suppression`), and the `vn-ok` exemption of `no-non-ascii-source`.
+- `starciBeConfig` refuses a recommendation that carries an `off`.
+- Slot parameters (the `@Global()` allowlist, the file line budget, the `index.ts` width) are read through `lib/slots.mjs` from `knowledge/hfs/slots.yaml` (`ruleParams.be.globalModules`, `ruleParams.be.fileLines.{soft,hardGrowth}`, and the `indexExports` budget of a `be.*` slot), with the rule catalog's values as the fallback.
+
+## 1.2.3 — 2026-09-29
+
+- `starciBeConfig({ sources, plugin, recommended })`, `linterOptions` and `RETIRED` are exported. The factory returns the one flat-config block a repository needs: the canon owns the retired-rule list (checked against the code-pattern manifest) and the warn-to-error lift, so a repository no longer hand-copies `replacedByChecks`.
+- `harness-calls-provider-directly` applies only to model harnesses, identified by an LLM provider SDK import, a house model helper or gateway symbol, or a `@harness-kind model` comment - never by the `src/tests/e2e/live/` folder. A live e2e for an identity provider (Keycloak) or any other third party is no longer reported as a model harness with no LLM SDK.
+
 ## 1.2.2 — 2026-09-29
 
 - Align module aliases and explicit public `index.ts` exports with HFS capability boundaries. Keep self-aliases, tier-only aliases, folder re-exports, and export-star public entries invalid.

package/README.md

@@ -1,6 +1,6 @@
 # @starci/eslint-canon-be
 
-**37 ESLint rules, from 15 laws, that hold a NestJS-shaped back end to one way of being written.**
+**78 ESLint rules, from 26 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
@@ -28,7 +28,24 @@ export default [
 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`.
+Prefer the factory, which owns the levels for you:
+
+```js
+import starciBe, { recommended, starciBeConfig } from "@starci/eslint-canon-be"
+
+export default [
+    // …your own ignores, language options and other plugins…
+    starciBeConfig({ sources: ["apps/**/*.ts", "src/**/*.ts"], plugin: starciBe, recommended }),
+]
+```
+
+It states `warn` as `error` for a zero-warning gate, applies
+`noInlineConfig` and unused-disable reporting, and refuses a recommendation that carries a rule switched `off`. HFS
+keeps no retired-rule list: a rule the standard no longer holds is deleted from the plugin, and every rule that ships is on.
+The parameters a rule takes from the slot manifest (the `@Global()` allowlist, the file line budget, the width of an
+`index.ts`) come through `lib/slots.mjs`, which reads `knowledge/hfs/slots.yaml` and falls back to the rule catalog's values.
+
+Also exported: `rules`, `ruleOwners`, `lawOwners`, `starciBeConfig`, `linterOptions`.
 
 ## What it actually catches
 
@@ -36,16 +53,31 @@ A sample, not the list:
 
 | Area | What the rules hold |
 |---|---|
-| **Exceptions** | Every failure carries its own identity and metadata. Concrete exceptions live in their owning feature or module capability's `errors/` folder; the shared abstract base may live at the capability root. |
+| **Errors** | A `catch` rethrows, logs through the logger port or returns an outcome carrying its cause; an error lives in its capability's `errors/`, extends `DomainError`, and no bare `Error` or framework exception escapes (`catch-must-account`, `error-home`) |
+| **Schema authority** | Migrations only: no `synchronize`, no `migrationsRun`, no runtime DDL, no entity glob; raw SQL only in a persistence repository; no ORM entity in a contract (`no-runtime-schema`, `sql-only-in-repository`, `no-entity-in-contract`) |
+| **Config and secrets** | `process.env` only in `platform/config`; no literal default for a secret, password, token, key or URL; secrets compare with `timingSafeEqual` (`no-direct-env-read`, `no-secret-default`, `secret-compare-timing-safe`) |
+| **Default deny** | Typed bodies and arguments, no `GraphQLJSON` tunnel, no `switch (operation)`, and `@Public` carries a reason (`no-untyped-body`, `public-needs-reason`) |
+| **Module shape** | `@Global()` only on the manifest allowlist; typed `ConfigurableModuleBuilder`; static `register`; one module per file; no `new` of a provider; no module-level `let` |
+| **Suppression** | No `eslint-disable`, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck` or `vn-ok` comment, anywhere (`no-inline-suppression`) |
+| **Size** | A file over its line budget is not new and does not grow past its size at the parent commit (`file-size-growth`) |
+| **Query safety** | SQL text carries no runtime substitution; a read states `take`, `limit` or `LIMIT` (`no-interpolated-sql`, `query-needs-limit`, `no-query-in-loop`) |
+| **Resilience** | An outbound HTTP call states a timeout or signal; `JSON.parse` of outside text sits in a `try`; a loop that catches and waits goes through `platform/retry` (`http-needs-timeout`, `json-parse-needs-guard`, `no-hand-rolled-retry`) |
+| **Log safety** | A logger call names no credential and no personal identifier (`no-secret-in-log`) |
+| **Async and types** | An `async` function awaits; no `as never`, no `x!`; handlers and public methods declare a return type (`async-needs-await`, `no-never-cast`, `no-non-null-assertion`, `explicit-handler-return-type`) |
+| **Migrations and input** | A migration's `down()` reverses its `up()`; every property of an input class has a `class-validator` decorator (`migration-down-reversible`, `dto-needs-validator`) |
+| **Spec quality** | A spec does not read repository source with `fs`, and doubles are `mock<T>()`, not `as never` (`spec-no-source-read`, `spec-typed-doubles`) |
 | **CQRS** | A handler does not assemble an aggregate inline; reads and writes do not share one path |
-| **Module layering** | Cross-capability imports may use an explicit public `index.ts`; self-aliases, tier-only aliases, folder re-exports, and export-star public entries are refused. |
-| **Data access** | Queries stay where the layer says they may be built |
+| **Module layering** | Another owner is imported through its public `index.ts` (`@modules/domain/plan`, `@features/plan`), never through a path into it; an `index.ts` lists a bounded set of named exports, with no `export *`, storage token or types folder; self-aliases and tier-only aliases are refused. |
+| **Data access** | Queries stay where the layer says they may be built; no transaction spans an external call (`no-external-call-in-transaction`); the database is reached through the named shared `EntityManager` only (`named-entity-manager-only`) |
 | **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 |
-| **Testing** | Unit specs sit beside their subjects, including structural specs in HFS `src/tests` categories; model-quality harness specs still call providers directly. |
+| **Observability** | A failure is logged through the logger port with a typed identity, so a log line can be traced to the law that names it |
+| **Testing** | Unit specs sit beside their subjects, including structural specs in HFS `src/tests` categories; a model-quality harness (one that imports an LLM SDK, reaches a house model helper or declares `@harness-kind model`) calls its provider directly; other live e2e specs, such as an identity provider, are not judged as model harnesses. |
 | **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` |
+| **User copy** | A literal exception message, notification text or response copy comes from the per-capability messages catalog through the typed `MessageCatalog` port (`user-copy-through-catalog`) |
+| **Temporal** | `Date.now()`, a bare `new Date()` and `performance.now()` are read only inside `platform/clock` (`no-ambient-clock`) |
+| **Idempotency** | A `@Public()` webhook handler and an outbox/queue consumer claim the event through the shared inbox before they act (`inbox-dedupe-required`) |
 
 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.
@@ -68,3 +100,46 @@ pointed at.
 ## Requirements
 
 ESLint 9+ (flat config), Node 20.9+.
+
+## HFS rules and their why codes
+
+Each rule below reports through the code-pattern gate with a catalogued Vietnamese reason (`modules/kernel/failure-codes.yaml`,
+mapped by `scripts/checks/lint-why.mjs`). The catalog id is the rule number in `knowledge/hfs/rules.yaml`.
+
+| Rule | Catalog | Why code |
+|---|---|---|
+| `catch-must-account` | R40 | `BE_LOGGER_REQUIRED` |
+| `error-home` | R38 | `BE_ERROR_HOME` |
+| `no-runtime-schema` | R34 | `BE_SCHEMA_AUTHORITY` |
+| `sql-only-in-repository` | R36 | `BE_SQL_OUTSIDE_REPOSITORY` |
+| `no-entity-in-contract` | R37 | `BE_ENTITY_IN_CONTRACT` |
+| `no-untyped-body`, `public-needs-reason`, `secret-compare-timing-safe` | R41 | `BE_DEFAULT_DENY` |
+| `no-direct-env-read` | R43 | `BE_CONFIG_OWNER` |
+| `no-secret-default` | R44 | `BE_SECRET_DEFAULT` |
+| `global-module-allowlist`, `typed-module-definition`, `static-module-register`, `no-new-injectable`, `no-module-let`, `one-module-per-file` | R45 | `BE_MODULE_SHAPE` |
+| `no-inline-suppression` | R18 | `HFS_INLINE_SUPPRESSION` |
+| `file-size-growth` | R20 | `HFS_SIZE_GROWTH` |
+| `spec-no-source-read`, `spec-typed-doubles` | R48 | `BE_SPEC_QUALITY` |
+| `must-deep-module-import`, `no-folder-reexport` | R30 | `BE_PUBLIC_SURFACE` |
+| `dto-needs-validator` | R42 | `BE_INPUT_BOUNDED` |
+| `no-interpolated-sql` | R68 | `BE_SQL_INTERPOLATED` |
+| `query-needs-limit` | R69 | `BE_QUERY_UNBOUNDED` |
+| `no-query-in-loop` | R77 | `BE_QUERY_IN_LOOP` |
+| `http-needs-timeout` | R70 | `BE_HTTP_TIMEOUT` |
+| `no-secret-in-log` | R71 | `BE_LOG_SECRET` |
+| `no-never-cast`, `no-non-null-assertion` | R72 | `BE_TYPE_ESCAPE` |
+| `async-needs-await` | R73 | `BE_ASYNC_NO_AWAIT` |
+| `migration-down-reversible` | R74 | `BE_MIGRATION_REVERSIBLE` |
+| `explicit-handler-return-type` | R75 | `BE_RETURN_TYPE` |
+| `json-parse-needs-guard` | R76 | `BE_JSON_PARSE_UNGUARDED` |
+| `user-copy-through-catalog` | R78 | `BE_USER_COPY_LITERAL` |
+| `no-ambient-clock` | R79 | `BE_AMBIENT_CLOCK` |
+| `inbox-dedupe-required` | R80 | `BE_INBOX_DEDUPE_MISSING` |
+| `no-hand-rolled-retry` | R81 | `BE_HAND_ROLLED_RETRY` |
+| `no-external-call-in-transaction` | R82 | `BE_TRANSACTION_EXTERNAL_CALL` |
+| `named-entity-manager-only`, `no-injected-repository` | R83 | `BE_UNNAMED_DATA_ACCESS` |
+
+There is no soft size-limit lint rule: a warning under a zero-warning gate is an exception in disguise. Listing files over the soft budget (`ruleParams.be.fileLines.soft`) is a report item of the hfs check or the architecture machine, as migration backlog, and never blocks.
+
+The tier direction matrix and the feature-imports-feature ban (R26, R28) are owned by the architecture machine
+(`@starci/hfs`), not by a lint rule: they need the whole import graph.

package/async-discipline.mjs

@@ -0,0 +1,83 @@
+/**
+ * The rule that keeps `async` honest.
+ *
+ * `async-needs-await` (R73 `BE_ASYNC_NO_AWAIT`) refuses an `async` function that never awaits. Such a function
+ * promises asynchronous work and does none: it turns a thrown error into a rejected promise for no reason,
+ * hides that the body is synchronous, and reads as if a suspension point existed. Delete the `async` and return the
+ * value (or the promise the body already holds); where a signature must return a `Promise`, return `Promise.resolve(x)`.
+ *
+ * Three shapes are exempt because the `async` is not the author's choice:
+ *   - a method of a class that `implements` or `extends` something (the base contract fixes the return type);
+ *   - a method that carries a decorator (the framework contract fixes it: resolvers, event handlers, lifecycle hooks);
+ *   - an `async` generator, whose `yield` is its suspension.
+ */
+import { walk } from "./lib/ast.mjs"
+import { isDeclarationFile, isTestLane } from "./lib/path.mjs"
+
+/** Whether the function body awaits, ignoring nested functions (each is judged alone). */
+const awaits = (fn) => {
+  let found = false
+  walk(fn.body, (node) => {
+    if (found) return
+    if (node.type === "AwaitExpression") found = true
+    else if (node.type === "ForOfStatement" && node.await) found = true
+  }, { intoFunctions: false })
+  return found
+}
+
+/** Whether the function is a method whose `async` a base class, interface or decorator fixes. */
+const asyncIsContractual = (fn) => {
+  const method = fn.parent?.type === "MethodDefinition" ? fn.parent : null
+  if (!method) return false
+  if (method.decorators?.length > 0) return true
+  if (method.override) return true
+  const klass = method.parent?.parent
+  if (klass && (klass.superClass || (klass.implements && klass.implements.length > 0))) return true
+  return false
+}
+
+/** An `async` function awaits something. */
+export const asyncNeedsAwait = {
+  meta: {
+    type: "problem",
+    docs: { description: "An `async` function contains an `await`, or it is not `async`." },
+    schema: [],
+    messages: {
+      noAwait:
+        "This `async` function never awaits. It promises asynchronous work and does none, so a thrown error becomes a rejected promise for no reason and a reader looks for a suspension that is not there. Remove `async` and return the value or the promise the body already holds; where the signature must return a `Promise`, return `Promise.resolve(value)`.",
+    },
+  },
+  create(context) {
+    const filename = context.filename || context.getFilename()
+    if (isTestLane(filename) || isDeclarationFile(filename)) return {}
+    const check = (node) => {
+      if (!node.async || node.generator || !node.body) return
+      if (node.body.type !== "BlockStatement" && node.type === "ArrowFunctionExpression") {
+        // an expression body has no statements to await inside; `async () => x` is judged by the expression itself
+        let has = false
+        walk(node.body, (child) => {
+          if (child.type === "AwaitExpression") has = true
+        }, { intoFunctions: false })
+        if (!has) context.report({ node, messageId: "noAwait" })
+        return
+      }
+      if (asyncIsContractual(node)) return
+      if (!awaits(node)) context.report({ node, messageId: "noAwait" })
+    }
+    return {
+      FunctionDeclaration: check,
+      FunctionExpression: check,
+      ArrowFunctionExpression: check,
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "async-needs-await": asyncNeedsAwait,
+}
+
+/** Starts at error: no baseline exists, and the repositories' fix lanes clear the debt. */
+export const recommended = {
+  "starci-be/async-needs-await": "error",
+}

package/comments.mjs

@@ -8,11 +8,8 @@
  *     restate the name - which COMMENT-3 forbids. Only declarations with a surface get the check.
  *   - `require-enum-member-jsdoc` can check that a doc EXISTS and never that it states a
  *     consequence. That half is read by a person, and the rule says so rather than pretending.
- *   - `no-non-ascii-source` exempts a marked line, because text a program matches on or emits is
- *     data wearing prose, and translating it breaks the program.
- *   - `require-vn-ok-reason` (law 6) holds the half `no-non-ascii-source` cannot: that marker is a
- *     bare escape hatch unless it says why the line stays, so a bare `vn-ok` is treated the same as
- *     no marker at all.
+ *   - `no-non-ascii-source` takes no exemption marker: HFS removed `vn-ok`, so text a program depends on
+ *     lives in a locale or data file, and a fixture lane is exempt for strings only (see the rule).
  *   - `no-restated-name-jsdoc` (law 7) holds the decidable slice of law 3 - a doc block whose only
  *     content is the declared name re-spelled in words teaches nothing beyond the import line, so it
  *     is COMMENT-3's violation wearing COMMENT-1's shape. It fires only on an exact match between the
@@ -23,9 +20,6 @@
 
 import { normalizePath } from "./lib/path.mjs"
 
-/** The marker that keeps a non-ASCII literal the program depends on. */
-const KEEP_MARKER = /\bvn-ok\b/
-
 /**
  * The character classes this refuses, and why it is NOT simply "ASCII only".
  *
@@ -161,15 +155,15 @@ export const requireEnumMemberJsdoc = {
 
 // -- COMMENT-4 -------------------------------------------------------------------------------------
 
-/** Source is English ASCII, except where a literal is data the program depends on. */
+/** Source prose is English; there is no exemption marker. */
 export const noNonAsciiSource = {
   meta: {
     type: "problem",
-    docs: { description: "Source stays English ASCII; a depended-upon literal is marked instead." },
+    docs: { description: "Source stays English; no exemption marker." },
     schema: [],
     messages: {
       nonAscii:
-        "This line carries {{offence}}. The bar is a reader who does not share the author's first language: a codebase with two languages in it has somebody for whom half the reasoning is unavailable, and it is the half explaining the surprising parts - and an emoji or an ornament carries tone rather than information, which reads differently to everybody. If this is text the program MATCHES on or EMITS, it is data rather than prose: keep it and mark the line `vn-ok: <reason>` so the next sweep does not turn it into a bug.",
+        "This line carries {{offence}}. The bar is a reader who does not share the author's first language: a codebase with two languages in it has somebody for whom half the reasoning is unavailable, and it is the half explaining the surprising parts - and an emoji or an ornament carries tone rather than information, which reads differently to everybody. There is no exemption marker: write the text in English, or keep product copy in a locale or data file.",
     },
   },
   create(context) {
@@ -187,8 +181,8 @@ export const noNonAsciiSource = {
      * chuyen khoan" - is feeding it data, and translating it would test a system nobody uses.
      *
      * Measured before it was written: of 92 findings in one back end, 89 were fixture strings and 3
-     * were comments. Demanding `vn-ok` on all 92 would have put a marker on every line of every
-     * conversation fixture, which is noise that teaches a reader to stop seeing the marker.
+     * were comments. Marking all 92 would have put an exemption on every line of every
+     * conversation fixture, which is noise; the whole lane is exempt for strings instead.
      *
      * The exemption is for STRINGS ONLY. A Vietnamese comment in a spec is the same problem it is
      * anywhere else - the next reader still cannot follow the reasoning - so it is still refused.
@@ -207,7 +201,6 @@ export const noNonAsciiSource = {
         const lines = sourceCode.getLines()
         for (let index = 0; index < lines.length; index += 1) {
           const line = lines[index]
-          if (KEEP_MARKER.test(line)) continue
           // in a fixture lane only prose is policed; the data the fixture feeds is the point of it
           if (commentLines && !commentLines.has(index + 1)) continue
           const offence = offenceIn(line)
@@ -229,45 +222,6 @@ export const noNonAsciiSource = {
   },
 }
 
-// -- law 6 -------------------------------------------------------------------------------------
-
-/** The line-level test for law 6: `vn-ok` present, with a colon and at least one reason character after it. */
-const REASON_AFTER_MARKER = /\bvn-ok\s*:\s*\S/
-
-/** Every `vn-ok` marker carries a reason; a bare marker is not an exemption. */
-export const requireVnOkReason = {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "COMMENT-5, law 6: a `vn-ok` marker carries a reason - a bare marker is not an exemption.",
-    },
-    schema: [],
-    messages: {
-      bareMarker:
-        "`vn-ok` on this line has no reason after it. The marker exists so the next sweep can read WHY the line stays instead of \"fixing\" it into a bug - a bare marker is only a way of switching that check off. Write `vn-ok: <reason>` and say what the marker is protecting.",
-    },
-  },
-  create(context) {
-    const sourceCode = context.sourceCode || context.getSourceCode()
-    return {
-      "Program:exit"(node) {
-        const lines = sourceCode.getLines()
-        for (let index = 0; index < lines.length; index += 1) {
-          const line = lines[index]
-          if (!KEEP_MARKER.test(line)) continue
-          if (REASON_AFTER_MARKER.test(line)) continue
-          context.report({
-            node,
-            loc: { line: index + 1, column: 0 },
-            messageId: "bareMarker",
-          })
-        }
-      },
-    }
-  },
-}
-
 // -- law 7 -------------------------------------------------------------------------------------
 
 /** Splits a declared name into its lowercase words, so `readUser` compares against "read user". */
@@ -367,7 +321,6 @@ export const rules = {
   "require-export-jsdoc": requireExportJsdoc,
   "require-enum-member-jsdoc": requireEnumMemberJsdoc,
   "no-non-ascii-source": noNonAsciiSource,
-  "require-vn-ok-reason": requireVnOkReason,
   "no-restated-name-jsdoc": noRestatedNameJsdoc,
 }
 
@@ -383,6 +336,5 @@ export const recommended = {
   "starci-be/require-export-jsdoc": "error",
   "starci-be/require-enum-member-jsdoc": "error",
   "starci-be/no-non-ascii-source": "error",
-  "starci-be/require-vn-ok-reason": "error",
   "starci-be/no-restated-name-jsdoc": "error",
 }

package/config-owner.mjs

@@ -0,0 +1,252 @@
+/**
+ * The rules that hold HFS configuration and secrets (catalog R43 `BE_CONFIG_OWNER`, R44 `BE_SECRET_DEFAULT`,
+ * and the secret-comparison half of R41 `BE_DEFAULT_DENY`).
+ *
+ *   - `no-direct-env-read` keeps `process.env` inside `platform/config`. Everything else receives typed options
+ *     from `<capability>.config.ts`; a `readEnvironment()` call inside a `useFactory` is the same read in
+ *     disguise and is refused too.
+ *   - `no-secret-default` refuses a literal default for a secret, password, token, key or URL: an `env.X ?? "..."`
+ *     fallback, a property or variable of that name holding a non-empty string, a `.default("...")` on a
+ *     schema of that name, and a path built from `process.cwd()` and `src` or `.starcistacks`. A missing value
+ *     must stop the boot, naming the key.
+ *   - `secret-compare-timing-safe` refuses `===` and `!==` on a secret-named identifier. A secret compares with
+ *     `timingSafeEqual`, because the length of the matching prefix is a measurable side channel.
+ *
+ * Test lanes are outside the default and env rules: a spec arranges its own environment and fake credentials.
+ * They are not outside the comparison rule.
+ */
+import { keyName, staticText, walk, wordsOf } from "./lib/ast.mjs"
+import { isDeclarationFile, isTestLane, normalizePath } from "./lib/path.mjs"
+
+const PLATFORM_CONFIG = /\/src\/modules\/platform\/config\//
+
+/** `process.env` or `process["env"]`. */
+const isProcessEnv = (node) =>
+    node.type === "MemberExpression" &&
+    node.object.type === "Identifier" &&
+    node.object.name === "process" &&
+    (node.computed ? node.property.type === "Literal" && node.property.value === "env" : keyName(node.property) === "env")
+
+/** Only the platform config capability reads the process environment. */
+export const noDirectEnvRead = {
+    meta: {
+        type: "problem",
+        docs: { description: "`process.env` is read only inside `platform/config`." },
+        schema: [],
+        messages: {
+            env: "`process.env` is read outside `platform/config`. Add the key to the capability's `<capability>.config.ts` (zod) and receive the value through its `<capability>.options.ts`.",
+            factory: "`readEnvironment()` inside a `useFactory` reads the environment per module. `main.ts` reads it once and passes options through `AppModule.register`.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename) || isTestLane(filename) || PLATFORM_CONFIG.test(filename)) return {}
+        return {
+            MemberExpression(node) {
+                if (isProcessEnv(node)) context.report({ node, messageId: "env" })
+            },
+            CallExpression(node) {
+                if (node.callee.type !== "Identifier" || node.callee.name !== "readEnvironment") return
+                for (let parent = node.parent; parent; parent = parent.parent) {
+                    if (parent.type === "Property" && keyName(parent.key) === "useFactory") {
+                        context.report({ node, messageId: "factory" })
+                        return
+                    }
+                }
+            },
+        }
+    },
+}
+
+const SECRET_WORDS = new Set(["password", "passwd", "passphrase", "secret", "token", "credential", "credentials", "apikey", "signature", "hmac"])
+const KEY_PREFIXES = new Set(["api", "secret", "private", "access", "signing", "encryption", "master", "auth", "jwt", "session"])
+const URL_WORDS = new Set(["url", "uri", "dsn", "endpoint"])
+const NOT_A_VALUE_WORDS = new Set(["type", "kind", "length", "count", "ttl", "name", "prefix", "header", "scheme", "field", "path", "regex", "pattern"])
+
+/** Whether a config name is a secret, or an infrastructure URL: `POSTGRES_PASSWORD`, `webhookSecret`, `redisUrl`. */
+const configKind = (name) => {
+    const words = wordsOf(name)
+    const last = words.at(-1)
+    if (!last || NOT_A_VALUE_WORDS.has(last)) return null
+    if (SECRET_WORDS.has(last)) return "secret"
+    if (last === "key" && words.length > 1 && KEY_PREFIXES.has(words.at(-2))) return "secret"
+    if (URL_WORDS.has(last)) return "url"
+    return null
+}
+
+/** The name an env read spells: `process.env.X`, `env.X`, `env["X"]`, `config.get("X")`. */
+const envReadName = (node) => {
+    if (node.type === "MemberExpression") {
+        const object = node.object
+        const isEnvObject = isProcessEnv(object) || (object.type === "Identifier" && /^env$/i.test(object.name))
+        if (!isEnvObject) return null
+        return node.computed ? staticText(node.property) : keyName(node.property)
+    }
+    if (node.type === "CallExpression" && node.callee.type === "MemberExpression" && keyName(node.callee.property) === "get") {
+        return staticText(node.arguments[0])
+    }
+    return null
+}
+
+const isNonEmptyText = (node) => {
+    const text = staticText(node)
+    return text !== null && text.trim() !== ""
+}
+
+/** An UPPER_SNAKE literal is the NAME of an environment key (`const API_KEY = "API_KEY"`), not a secret value. */
+const isKeyName = (node, name) => {
+    const text = staticText(node) ?? ""
+    if (/^[A-Z][A-Z0-9_]*$/.test(text)) return true
+    // `const MEDIA_SIGNING_SECRET_KEY = "mediaSigningSecret"`: a constant that names a lookup key holds the key's name
+    return /^[A-Z][A-Z0-9_]*_KEY$/.test(name ?? "") && /^[a-z][A-Za-z0-9]*$/.test(text)
+}
+
+const hasScheme = (node) => /^[a-z][a-z0-9+.-]*:\/\//i.test(staticText(node) ?? "")
+
+const targetName = (node) => {
+    if (node.type === "Property" || node.type === "PropertyDefinition") return keyName(node.key)
+    if (node.type === "VariableDeclarator" && node.id.type === "Identifier") return node.id.name
+    if (node.type === "AssignmentPattern" && node.left.type === "Identifier") return node.left.name
+    return null
+}
+
+/** No secret, password, token, key or URL config has a literal default; a missing value stops the boot. */
+export const noSecretDefault = {
+    meta: {
+        type: "problem",
+        docs: { description: "A secret or URL config value never has a literal default." },
+        schema: [],
+        messages: {
+            fallback: "`{{name}}` falls back to a literal. A missing {{kind}} must stop the boot with an error naming `{{name}}`, not start the app with a value from source.",
+            literal: "`{{name}}` holds a literal {{kind}}. A {{kind}} is supplied by configuration, never written in source.",
+            schemaDefault: "`.default(...)` gives `{{name}}` a value in source. Remove the default so a missing {{kind}} fails validation at boot.",
+            cwdPath: "A path built from `process.cwd()` and `{{segment}}` depends on where the process was started. Resolve it from a configured root.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename) || isTestLane(filename)) return {}
+        const report = (node, messageId, name, kind) => context.report({ node, messageId, data: { name, kind: kind === "url" ? "URL" : "secret" } })
+        const checkLiteralTarget = (node, value) => {
+            const name = targetName(node)
+            const kind = name ? configKind(name) : null
+            if (kind && value && isNonEmptyText(value) && (kind === "url" ? hasScheme(value) : !isKeyName(value, name))) report(node, "literal", name, kind)
+        }
+        return {
+            LogicalExpression(node) {
+                if (node.operator !== "??" && node.operator !== "||") return
+                const name = envReadName(node.left)
+                const kind = name ? configKind(name) : null
+                if (kind && isNonEmptyText(node.right) && (kind === "url" ? hasScheme(node.right) : !isKeyName(node.right, name))) report(node, "fallback", name, kind)
+            },
+            Property(node) {
+                checkLiteralTarget(node, node.value)
+            },
+            PropertyDefinition(node) {
+                checkLiteralTarget(node, node.value)
+            },
+            VariableDeclarator(node) {
+                checkLiteralTarget(node, node.init)
+            },
+            AssignmentPattern(node) {
+                checkLiteralTarget(node, node.right)
+            },
+            CallExpression(node) {
+                const callee = node.callee
+                if (callee.type === "MemberExpression" && keyName(callee.property) === "default" && isNonEmptyText(node.arguments[0])) {
+                    for (let parent = node.parent; parent; parent = parent.parent) {
+                        if (parent.type === "Property") {
+                            const name = keyName(parent.key)
+                            const kind = name ? configKind(name) : null
+                            if (kind && (kind !== "url" || hasScheme(node.arguments[0]))) report(node, "schemaDefault", name, kind)
+                            return
+                        }
+                    }
+                    return
+                }
+                if (callee.type === "MemberExpression" && ["join", "resolve"].includes(keyName(callee.property) ?? "")) {
+                    let cwd = false
+                    walk(node, (child) => {
+                        if (child.type === "CallExpression" && child.callee.type === "MemberExpression" && keyName(child.callee.property) === "cwd") cwd = true
+                    })
+                    if (!cwd) return
+                    for (const argument of node.arguments) {
+                        const text = staticText(argument)
+                        const segment = text === null ? null : text.split(/[\\/]/).find((part) => part === "src" || part === ".starcistacks")
+                        if (segment) context.report({ node, messageId: "cwdPath", data: { segment } })
+                    }
+                }
+            },
+        }
+    },
+}
+
+const SECRET_COMPARE_WORDS = new Set(["secret", "password", "passwd", "passphrase", "token", "signature", "hmac", "credential", "credentials", "apikey"])
+
+/** The identifier or property a comparison operand ends in, else null. */
+const operandName = (node) => {
+    if (node.type === "Identifier") return node.name
+    if (node.type === "MemberExpression" && !node.computed && node.property.type === "Identifier") return node.property.name
+    return null
+}
+
+/** Words before the last one that make a token a counter or a cursor, not a credential. */
+const NOT_A_CREDENTIAL_QUALIFIERS = new Set(["fencing", "idempotency", "cursor", "page", "next", "continuation", "pagination", "sync", "csrf"])
+
+const isSecretName = (name) => {
+    // an UPPER_SNAKE name is a constant naming a key, not the value it names
+    if (/^[A-Z][A-Z0-9_]*$/.test(name)) return false
+    const words = wordsOf(name)
+    const last = words.at(-1)
+    if (!last || NOT_A_VALUE_WORDS.has(last) || words.some((word) => NOT_A_CREDENTIAL_QUALIFIERS.has(word))) return false
+    return SECRET_COMPARE_WORDS.has(last) || (last === "key" && words.length > 1 && KEY_PREFIXES.has(words.at(-2)))
+}
+
+/** An emptiness or presence check reveals nothing a timing attack could use. */
+const isPresenceOperand = (node) =>
+    (node.type === "Literal" && (node.value === null || node.value === "" || typeof node.value === "boolean")) ||
+    (node.type === "Identifier" && node.name === "undefined") ||
+    (node.type === "UnaryExpression" && node.operator === "typeof")
+
+/** A secret is compared with `timingSafeEqual`, never with an equality operator. */
+export const secretCompareTimingSafe = {
+    meta: {
+        type: "problem",
+        docs: { description: "A secret-named value is compared with `timingSafeEqual`, not `===` or `!==`." },
+        schema: [],
+        messages: {
+            compare: "`{{name}}` is a secret compared with `{{operator}}`. Compare secrets with `crypto.timingSafeEqual` on equal-length buffers so the comparison time does not leak the match.",
+        },
+    },
+    create(context) {
+        const filename = normalizePath(context.filename || context.getFilename())
+        if (isDeclarationFile(filename)) return {}
+        return {
+            BinaryExpression(node) {
+                if (!["===", "!==", "==", "!="].includes(node.operator)) return
+                if (isPresenceOperand(node.left) || isPresenceOperand(node.right)) return
+                for (const side of [node.left, node.right]) {
+                    const name = operandName(side)
+                    if (name && isSecretName(name)) {
+                        context.report({ node, messageId: "compare", data: { name, operator: node.operator } })
+                        return
+                    }
+                }
+            },
+        }
+    },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+    "no-direct-env-read": noDirectEnvRead,
+    "no-secret-default": noSecretDefault,
+    "secret-compare-timing-safe": secretCompareTimingSafe,
+}
+
+/** All three start at error: a secret in source or a timing leak is never a warning. */
+export const recommended = {
+    "starci-be/no-direct-env-read": "error",
+    "starci-be/no-secret-default": "error",
+    "starci-be/secret-compare-timing-safe": "error",
+}