@starci/eslint-canon-be 3.4.40 → 3.4.41

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+- Changed: `operation-table-schemas` and `operation-contract-decidable` leave alone a stub table a spec keeps to itself, but judge one a spec exports (`export const`, `export { }`, `export default`); `rest-route-declared` never counts a table made in a spec as the app's declared table. The same stub table in a production file stays refused.
+- Changed: R95 requires named zod input/output schema exports for every `defineOperations` entry (`operation-table-schemas`) and a canon `OperationValidationPolicy` constructed with the same table on the route body (`operation-route-driven-by-table`). Schema provenance and route binding are proved in both editions, including strict empty inputs, aliases, mismatched tables and local imitations.
+
+## 3.4.41 - 2026-10-25
+- Changed: the bundled canon pins select @starci/stylelint-canon 2.0.11, @starci/hfs 4.7.33 and @starci/cli 1.7.33.
+
 ## 3.4.40 - 2026-10-25
 - Changed: the bundled canon pins select @starci/grammar 0.11.0, @starci/hfs 4.7.32 and @starci/cli 1.7.32.
 

package/README.md

@@ -53,14 +53,14 @@ A sample, not the list:
 | **Log safety** | A call on the `Logger` port (found by the receiver's type) passes no `Secret` or `Pii` value and no value named like a credential or a personal identifier (`no-secret-in-log`); a constructed error (its type derives from `Error`) carries no `Secret` value and no text value named like a credential (`no-secret-in-error`) |
 | **Async and types** | An `async` function awaits; handlers and public methods declare a return type; no `Function` type, no `eval`; an inline object type takes a name; no `const enum`. Casts, `x!` and `any` are refused in every file, specs included, by the typescript-eslint rules the factory turns on (`async-needs-await`, `explicit-handler-return-type`, `no-function-or-eval`, `no-inline-param-type`, `no-inline-object-type`, `no-const-enum`) |
 | **Migrations and input** | A migration's `down()` reverses its `up()`; every property of an input class has the `class-validator` decorators its type calls for (string `@MaxLength`, enum `@IsEnum`, array `@ArrayMaxSize`, nested `@ValidateNested()` and `@Type`); reads page by cursor, never by `skip`, `offset` or `OFFSET`; a door opened for `PublicReason.AuthHandshake` or `PublicReason.SignedWebhook` carries `RateTier.Strict` of `platform/http-security` on the method or its class (`migration-down-reversible`, `input-bounded`, `no-offset-pagination`, `auth-door-strict-rate-tier`) |
-| **Boundary schema** (R304, R305) | `zod` reads only boundary data that never reaches a DTO (a provider response, model output, a queue or outbox payload read back): it is imported only from a `<name>.schema.ts` of a domain, platform or integrations owner, never in a feature, a transport door or a `dto/` folder, and a schema file imports no `class-validator`, `class-transformer` or `@nestjs/graphql` (`schema-place`); every string, array, set, record and map of a schema has an upper bound and `z.any()`, `z.unknown()` and `z.json()` do not exist (`schema-bounded`) |
+| **Boundary schema** (R304, R305) | `zod` reads only boundary data that never reaches a DTO (a provider response, model output, a queue or outbox payload read back): it is imported only from a `<name>.schema.ts` of a domain, platform or integrations owner, never in a feature, a transport door or a `dto/` folder, and a schema file imports no `class-validator`, `class-transformer` or `@nestjs/graphql` (`schema-place`) and holds only zod values and types (`schema-file-values-only`; its spec is exempt from the testing module of R281 only while this holds); every string, array, set, record and map of a schema has an upper bound and `z.any()`, `z.unknown()` and `z.json()` do not exist (`schema-bounded`) |
 | **Spec quality** | A spec does not read repository source with `fs` (`spec-no-source-read`); the borrowed `consistent-type-assertions` (`never`) and `no-non-null-assertion` leave no `as` and no `x!` in a spec, and `no-ambient-clock` and `no-direct-env-read` cover specs, so no `Date.now()`, argless `new Date()` or `process.env`. A unit spec is `<name>.service.spec.ts`: it builds its subject with `Test.createTestingModule({ providers })` from `@nestjs/testing`, `.compile()` and `moduleRef.get(...)` (`spec-builds-with-testing-module`), never `new` on the service (`spec-no-new-subject`), no `imports` key and no `override*` (`spec-module-definition-only-providers`), no `jest.mock`/`doMock`/`unstable_mockModule`/`requireMock` of an own module or a library (`spec-no-module-mock`), no cast-laundering helper in a spec or fixture: a return-only generic, an `unknown` handed back as another type, `JSON.parse(JSON.stringify(x))`, `Object.assign(new X(), y)` returned as another type (`no-return-only-generic`); a provider `{ provide: TOKEN, useValue: X }` takes X from the matching `@starci/jest-preset` double, the token table being `ruleParams.be.specDoubles` of the slot manifest (`spec-infra-double-from-kit`); a unit spec asserts exact values, never `expect.any(String)`, `expect.any(Number)` or `expect.any(Date)` (`expect` being the jest global or the `@jest/globals` import): ids come from `fakeIds()` and dates from `FakeClock` (`spec-exact-values`); the EntityManager double is the kit's `mockEntityManager()`/`fakeTransaction()`, never ad hoc (`spec-typed-entity-manager`); test data goes through builders, see the **Test data builders** row |
 | **Test data builders** (R98 to R101) | Builders live only in `src/tests/fixtures/builders/<area>.builder.ts`: a module of the test tree that exports a function creating persisted rows through an EntityManager, DataSource or QueryRunner is a builder wherever it sits (`persisting-builder-in-builders-slot`, R98); a spec never runs a raw INSERT/UPDATE/DELETE or a direct write (`save`, `insert`, `upsert`, `update`, `delete`, `remove`) on a typeorm receiver and never builds the same `@Entity` class as an object literal twice (`spec-no-raw-insert`, `spec-no-repeated-row-literal`, R99); a builder never asserts and has deterministic defaults (`builder-arranges-only`, R101); nothing under `src/tests` disables or drops a constraint (`tests-keep-constraints`, R100) |
 | **CQRS** | A message extends `Command<R>` / `Query<R>` from `@nestjs/cqrs`, carries one `readonly params: ExecuteParams<X>` (no entity reachable from `X`), a handler extends `ICQRSHandler` and overrides `process`; a handler is thin: it injects only `*Service` classes and the Logger, and `process` is one `return this.<service>.<method>(...)` with no branch, loop, EntityManager or second call (`handler-is-thin`); no `*.use-case.ts`, no forwarder service, no `EventBus`, `@nestjs/event-emitter`, `EventEmitter` or RxJS `Subject` constructed or extended, and no class that stores callbacks other code registers (`handler-overrides-process`, `message-carries-params-only`, `message-typed-result`, `execute-params-shape`, `no-use-case`, `no-event-bus`) |
 | **Module layering** | Another owner is imported through its public `index.ts` (`@modules/domain/plan`, `@features/api/plan`), never through a path into it, and a same-owner import is relative and never through the own index (`import-owner-entry`); an owner has one `index.ts` (a nested one is refused) that holds only named `export { }` lines, with no `export *`, and a bounded number of names (`no-folder-reexport`); self-aliases and relative escapes are refused (`no-self-module-alias`, `no-relative-capability-escape`). Owners come from the HFS slots, aliases from the program's `compilerOptions.paths`. |
 | **Data access** | The database is reached through the shared `EntityManager` only, received as a constructor parameter with the named injector of a declared connection - a lookalike name, property injection, an injected `DataSource` or `QueryRunner` outside `platform/database` and the cli (`apps/cli`, `src/features/cli/`), `getRepository` and repository types are refused, specs included (`must-inject-entity-manager`, `named-entity-manager-only`, `no-injected-repository`); a `DataSource` or `QueryRunner` is not written as a type, awaited value or `provide:` token outside those places, and a class that receives a wrapper exposing one is refused (`named-entity-manager-only`); a class outside an application handler, a domain service and a platform persistence capability takes, holds or returns no `EntityManager`, `Repository`, `DataSource` or `QueryRunner` whatever it is called, and no exported function takes an `EntityManager` first (a statement module); `src/tests` is exempt (`no-repository-class`); a `DataSource` or `QueryRunner` is not written as a type, awaited value or `provide:` token outside those places, and a class that receives a wrapper exposing one is refused (`named-entity-manager-only`); a class outside an application handler, a domain service and a platform persistence capability takes, holds or returns no `EntityManager`, `Repository`, `DataSource` or `QueryRunner`, whatever it is called, and no exported function takes an `EntityManager` first (a statement module); the test tree (`src/tests`) is exempt (`no-repository-class`); inside a transaction callback only the manager it received is used (`no-outer-manager-in-transaction`); no call through an integration, `HttpClient` or `MessagePublisher` typed receiver spans a transaction (`no-external-call-in-transaction`); the manager is injected only in application handlers, domain services and the platform database, inbox, outbox and lease capabilities (`em-injection-slots`) |
 | **Connections** | One database is one connection and one `Inject<Conn>EntityManager()` injector: `InjectEntityManager(`, `InjectDataSource(` and `getEntityManagerToken(` are called only in `platform/database/<conn>.decorators.ts`, the cli and the test world; an exported EntityManager injector is exactly the declared connection's; `TypeOrmModule.forRoot*` and `new DataSource(` live in the platform database capability and the cli; the connection name is written once, in its `<conn>.connection.ts`; a `<conn>.config.ts` reads only keys of its `envPrefix` (`one-connection-per-database`) |
-| **Operations** | A versioned operation is declared once in the app's typed operation table (`query<Input, Output, RefusalCode>()` / `mutation<...>()` registered by `defineOperations`, declared by the platform capability `operations`): its input and output are closed types (no `any`, `unknown`, `Record<string, unknown>`, unbound generic, function or `Date`) and its refusal codes a closed union of string literals; a route that takes or answers the table's types takes `OperationRequest<Table>`, binds that body to `new OperationValidationService(RequestClass)` of `platform/http-security` and answers `Promise<OperationReply<Table>>` of one table (`operation-contract-decidable`, `operation-route-driven-by-table`) |
+| **Operations** | A versioned operation is declared once in the app's typed operation table (`query({ input, output, refusal })` / `mutation(...)` registered by `defineOperations`, declared by the platform capability `operations`): bounded input and output schemas come from an owner's `*.schema.ts` file, their inferred types are closed, and refusal codes form a closed union of string literals. A route takes `OperationRequest<Table>`, validates it with the canon `OperationValidationPolicy` constructed from that same table, and answers `Promise<OperationReply<Table>>` (`operation-contract-decidable`, `operation-table-schemas`, `operation-route-driven-by-table`) |
 | **Webhooks and realtime** | A provider webhook door injects only the `WebhookSignatureService` and domain services, verifies first (awaited when async), and hands the POST delivery to exactly one domain intake that records the inbox receipt and outbox event; a domain method may combine proof and intake. The POST returns nothing or the own-feature exported literal `PROVIDER_ACK`. One optional GET challenge handler returns only its declared domain verifier's result. The door and HTTP module import or inject no `CommandBus`, `QueryBus` or feature command handler, and its resolved domain intake dispatches no command/query bus or feature handler; a reactor or job dispatches after commit (`webhook-shape`, `webhook-verify-first`, `feature-thin`). A realtime door is one gateway or subscription that injects only the `RealtimeHub` and subscribes to a topic built from its `@CurrentPrincipal()` (`realtime-shape`, `realtime-read-only`, `realtime-topic-scope`) |
 | **Transport** | A door injects only `CommandBus` / `QueryBus` (and `RequestLocale` in REST) and dispatches exactly one message per handler, holding no branch, loop, EntityManager or call other than the bus, and pure `*.mapper.ts` functions and `unwrapOutcome` of `platform/primitives` (`transport-is-thin`); no response envelope, no `GraphQLJSON`, no `unknown` body, no `switch (input.operation)`; a REST door lives in `transport/http` and shows a public reason, a byte stream or a redirect; a capability never imports a feature (`transport-is-thin`, `no-response-envelope`, `no-graphql-json`, `door-lives-in-features`, `rest-door-needs-a-reason`, `no-capability-imports-features`) |
 | **Feature thin** (R203 BE_FEATURE_THIN) | A feature-tier file of a thin role (`<name>.handler.ts`, `.resolver.ts`, `.controller.ts`, `.consumer.ts`, `.processor.ts`, `.step.ts`, `.saga.ts`, `.saga-step.ts`, `.compensation.ts`, `.webhook.ts`, `.gateway.ts`, `.subscription.ts`, `.cli.ts`, `.mapper.ts`, `.service.ts`) maps its parameters and makes exactly one delegating call into the modules - an injected member, a bus `execute` or a modules function in statement position - with no branch, loop, `try`, `throw` or computation; free calls are pure `*.mapper.ts` functions, the `Logger` port and a webhook's first verification call when followed by one separate intake (a combined domain verification and intake call counts as the delegation). A webhook POST may return its declared literal `PROVIDER_ACK`; its optional GET challenge has one domain verifier call and echoes only that result. Webhook doors and their HTTP modules reach no command/query bus or feature command handler; orchestration (step order, compensation, claim, fencing, retry) belongs to the platform (`feature-thin`) |

package/boundary-schema.mjs

@@ -17,16 +17,17 @@
 import { hfsOf } from "./lib/hfs.mjs"
 import { normalizePath } from "./lib/path.mjs"
 import { isTransportSlot } from "./lib/transport-slots.mjs"
+import { SCHEMA_TIERS, schemaFileProblems } from "./lib/schema-values.mjs"
 
 const ZOD = /^zod(?:\/|$)/
 /** The imports of the other validation layer, which never share a file with a schema. */
 const MIXED = new Set(["class-validator", "class-transformer", "@nestjs/graphql"])
 const SCHEMA_FILE = /\.schema(?:\.spec)?\.ts$/
-/** Tiers a schema file may live in: the owners of boundary data. */
-const SCHEMA_TIERS = new Set(["domain", "platform", "integrations"])
 
 /** Constructors that build a string-valued schema and owe a `.max(n)` or `.length(n)`. */
-const STRINGY = new Set(["string", "email", "url", "httpUrl", "hostname", "base64", "base64url", "jwt", "emoji", "hex"])
+const STRINGY = new Set(["string", "email", "url", "httpUrl", "hostname", "base64", "base64url", "jwt", "emoji", "hex", "iso.datetime", "iso.date", "iso.time", "iso.duration"])
+/** The ISO namespace constructs strings; `z.date()` instead constructs a Date-valued schema. */
+const ISO_STRINGY = new Set(["datetime", "date", "time", "duration"])
 /** Constructors that build a counted container: bounded by `.max(n)`, `.length(n)` or `.size(n)`. */
 const COUNTED = new Set(["array", "set"])
 /** Constructors whose entry count only a refinement can bound. */
@@ -66,11 +67,16 @@ const chainOf = (node) => {
     return calls
 }
 
-/** Resolves a callee to the zod constructor it names, or null: `z.string`, `z.coerce.string`, or a named import `string`. */
+/** Resolves a zod constructor, including `z.iso.datetime()` and a renamed named import of `iso`. */
 const constructorOf = (callee, namespaces, named) => {
     if (callee.type === "Identifier") return named.get(callee.name) ?? null
     if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier") return null
     let object = callee.object
+    if (ISO_STRINGY.has(callee.property.name)) {
+        const importedIso = object.type === "Identifier" && named.get(object.name) === "iso"
+        const namespaceIso = object.type === "MemberExpression" && !object.computed && object.property.type === "Identifier" && object.property.name === "iso" && object.object.type === "Identifier" && namespaces.has(object.object.name)
+        if (importedIso || namespaceIso) return `iso.${callee.property.name}`
+    }
     while (object.type === "MemberExpression" && !object.computed && object.property.type === "Identifier" && PASS_THROUGH.has(object.property.name)) object = object.object
     return object.type === "Identifier" && namespaces.has(object.name) ? callee.property.name : null
 }
@@ -184,14 +190,36 @@ export const schemaPlace = {
     },
 }
 
+/** What a schema file holds: zod values and types, nothing that runs. */
+export const schemaFileValuesOnly = {
+    meta: {
+        type: "problem",
+        docs: { description: "A schema file imports zod and declares only zod schemas and their types: no class, provider, function or other logic." },
+        schema: [],
+        messages: {
+            logic: "[BE_SCHEMA_PLACE] This schema file is not a boundary schema: {{problem}}. A schema file imports zod and declares only zod values and their inferred types; logic belongs in a service, policy or mapper under its own role suffix.",
+        },
+    },
+    create(context) {
+        if (!SCHEMA_FILE.test(normalizePath(context.filename)) || context.filename.endsWith(".spec.ts")) return {}
+        return {
+            "Program:exit"(node) {
+                for (const problem of schemaFileProblems(context.sourceCode.text)) context.report({ node, messageId: "logic", data: { problem } })
+            },
+        }
+    },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
     "schema-bounded": schemaBounded,
     "schema-place": schemaPlace,
+    "schema-file-values-only": schemaFileValuesOnly,
 }
 
 /** Both start at error: no baseline exists. */
 export const recommended = {
     "starci-be/schema-bounded": "error",
     "starci-be/schema-place": "error",
+    "starci-be/schema-file-values-only": "error",
 }

package/idempotency.mjs

@@ -29,6 +29,7 @@ import { walk } from "./lib/ast.mjs"
 import { baseName, isOwnedType, ownerNameOf } from "./lib/ports.mjs"
 import { resolveVariable } from "./lib/transactions.mjs"
 import { isPackageType, typed } from "./lib/types.mjs"
+import { mutationIdempotent } from "./lib/client-idempotency.mjs"
 
 /** The `Inbox` port of `platform/inbox`. */
 const isInboxType = (context, node) => isOwnedType(context, node, { name: "Inbox", capability: "inbox", tier: "platform" })
@@ -175,9 +176,11 @@ export const inboxDedupeRequired = {
 /** The rule this law contributes to the plugin. */
 export const rules = {
     "inbox-dedupe-required": inboxDedupeRequired,
+    "mutation-idempotent": mutationIdempotent,
 }
 
 /** Starts at error: a duplicate charge or a duplicate side effect is never a warning. */
 export const recommended = {
     "starci-be/inbox-dedupe-required": "error",
+    "starci-be/mutation-idempotent": "error",
 }

package/index.mjs

@@ -62,6 +62,7 @@ import { recommended as testWorldRecommended, rules as testWorldRules } from "./
 import { recommended as transportRecommended, rules as transportRules } from "./transport.mjs"
 import { recommended as typeSafetyRecommended, rules as typeSafetyRules } from "./type-safety.mjs"
 import { recommended as unitSpecRecommended, rules as unitSpecRules } from "./unit-spec.mjs"
+import { recommended as uploadsRecommended, rules as uploadsRules } from "./uploads.mjs"
 import { recommended as userCopyRecommended, rules as userCopyRules } from "./user-copy.mjs"
 import { recommended as webhooksRecommended, rules as webhooksRules } from "./webhooks.mjs"
 import { recommended as realtimeRecommended, rules as realtimeRules } from "./realtime.mjs"
@@ -116,6 +117,7 @@ const CONTRIBUTIONS = [
     { law: "transport", rules: transportRules, recommended: transportRecommended },
     { law: "type-safety", rules: typeSafetyRules, recommended: typeSafetyRecommended },
     { law: "unit-spec", rules: unitSpecRules, recommended: unitSpecRecommended },
+    { law: "uploads", rules: uploadsRules, recommended: uploadsRecommended },
     { law: "user-copy", rules: userCopyRules, recommended: userCopyRecommended },
     { law: "webhooks", rules: webhooksRules, recommended: webhooksRecommended },
     { law: "realtime", rules: realtimeRules, recommended: realtimeRecommended },

package/infra-owner.mjs

@@ -13,8 +13,9 @@
  *
  * The test world (slot `be.tests.world`, `src/tests/world`) is an infrastructure owner like the platform capabilities: it is
  * the TEST COMPOSITION ROOT that starts docker, polls readiness, serves the network-edge fakes over `node:http` and drives the
- * apps over HTTP with a raw client, and it has no Nest container to inject a port from. It may use every library the
- * table gives an owner; a library the table owns by nobody (`[]`, `nowhere`) is still refused there. A spec does not
+ * apps over HTTP with a raw client, and it has no Nest container to inject a port from. It may use libraries the
+ * table gives an owner except logging infrastructure, whose ambient state stays inside its sole owner. A library the
+ * table owns by nobody (`[]`, `nowhere`) is still refused there. A spec does not
  * compose: specs stay refused and reach infrastructure through `useTestWorld(...)`.
  *
  * `no-framework-logger` (R40) and `no-ambient-clock` (R79) judge Nest `Logger` and `Date`; the table holds neither.
@@ -64,7 +65,7 @@ export const infraImportOwner = {
         const isWorld = inTestWorld(hfs, context.filename)
         const check = (node, name, key) => {
             const owners = table[key]
-            if (owners.includes(here) || (isWorld && owners.length > 0)) return
+            if (owners.includes(here) || (isWorld && owners.length > 0 && !owners.includes("platform/logging"))) return
             if (owners.length === 0) context.report({ node, messageId: "nowhere", data: { name } })
             else context.report({ node, messageId: "foreign", data: { name, owners: owners.map((owner) => `\`${owner}\``).join(", ") } })
         }

package/lib/client-idempotency.mjs

@@ -0,0 +1,403 @@
+/** BE-IDEMPOTENCY-3: marked client commands preserve their key and execute through the transactional inbox. */
+import ts from "typescript"
+import { hfsOf } from "./hfs.mjs"
+import { baseName, ownerNameOf } from "./ports.mjs"
+import { moduleOf, originsOfType, typed } from "./types.mjs"
+import { isTransportSlot } from "./transport-slots.mjs"
+
+/** Imported aliases and namespace access resolve to the declaring value. */
+const valueSymbol = (checker, expression, seen = new Set()) => {
+    if (!expression || seen.has(expression)) return undefined
+    seen.add(expression)
+    const name = ts.isPropertyAccessExpression(expression) ? expression.name : expression
+    const symbol = name.parent && ts.isShorthandPropertyAssignment(name.parent) && name.parent.name === name
+        ? checker.getShorthandAssignmentValueSymbol(name.parent) : checker.getSymbolAtLocation(name)
+    const target = symbol?.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol
+    const alias = target?.getDeclarations()?.find((declaration) => ts.isVariableDeclaration(declaration)
+        && declaration.parent.flags & ts.NodeFlags.Const && declaration.initializer
+        && (ts.isIdentifier(declaration.initializer) || ts.isPropertyAccessExpression(declaration.initializer)))
+    return alias ? valueSymbol(checker, alias.initializer, seen) : target
+}
+
+/** The genuine decorator belongs to its platform capability, rather than merely sharing a name. */
+const ownedValue = (checker, hfs, expression, name, capability) => {
+    const symbol = valueSymbol(checker, expression)
+    return symbol?.name === name && symbol.getDeclarations()?.some((declaration) => {
+        const file = declaration.getSourceFile().fileName
+        return moduleOf(declaration, file) === null && hfs.tierOf(file) === "platform" && ownerNameOf(hfs, file) === capability
+    })
+}
+
+/** A resolved decorator declaration and its call arguments. */
+const decorators = (checker, node) => (ts.getDecorators(node) ?? []).map((decorator) => {
+    const call = decorator.expression
+    const expression = ts.isCallExpression(call) ? call.expression : call
+    const symbol = valueSymbol(checker, expression)
+    return { expression, symbol, args: ts.isCallExpression(call) ? call.arguments : [], called: ts.isCallExpression(call) }
+})
+
+/** Whether the class carries the platform inbox's effectful marker. */
+const effectful = (checker, hfs, node) => decorators(checker, node).some((decorator) => decorator.called
+    && decorator.args.length === 0 && ownedValue(checker, hfs, decorator.expression, "Effectful", "inbox"))
+
+/** A package declaration establishes framework identity even through an import alias. */
+const fromPackage = (checker, expression, name, pkg) => {
+    const symbol = valueSymbol(checker, expression)
+    return symbol?.name === name && symbol.getDeclarations()?.some((declaration) => moduleOf(declaration, declaration.getSourceFile().fileName) === pkg)
+}
+
+/** Class inheritance keeps the Nest Command identity without relying on local spelling. */
+const commandType = (checker, type, seen = new Set()) => {
+    if (!type || seen.has(type)) return false
+    seen.add(type)
+    if (originsOfType(checker, type).some((origin) => origin.name === "Command" && origin.module === "@nestjs/cqrs")) return true
+    return type.isClassOrInterface() && (checker.getBaseTypes(type) ?? []).some((base) => commandType(checker, base, seen))
+}
+
+/** Required strings exclude optional properties, undefined, null and unconstrained types. */
+const requiredString = (checker, type, property) => {
+    const member = checker.getPropertyOfType(type, property)
+    if (!member || member.flags & ts.SymbolFlags.Optional) return false
+    const declaration = member.valueDeclaration ?? member.declarations?.[0]
+    if (!declaration) return false
+    const value = checker.getTypeOfSymbolAtLocation(member, declaration)
+    return (value.isUnion() ? value.types : [value]).every((part) => !!(part.flags & ts.TypeFlags.StringLike))
+}
+
+/** Canonical ExecuteParams carries the request, while a direct client params object carries its own key. */
+const keyContract = (checker, type) => {
+    if (requiredString(checker, type, "idempotencyKey")) return true
+    const request = checker.getPropertyOfType(type, "request")
+    const declaration = request?.valueDeclaration ?? request?.declarations?.[0]
+    return !!declaration && !(request.flags & ts.SymbolFlags.Optional)
+        && requiredString(checker, checker.getTypeOfSymbolAtLocation(request, declaration), "idempotencyKey")
+}
+
+/** A sole returned expression admits an optional await and inline expression-bodied callbacks. */
+const returned = (body) => {
+    if (!body) return null
+    let expression = ts.isBlock(body) ? body.statements.length === 1 && ts.isReturnStatement(body.statements[0]) ? body.statements[0].expression : null : body
+    while (expression && ts.isParenthesizedExpression(expression)) expression = expression.expression
+    return expression && ts.isAwaitExpression(expression) ? expression.expression : expression
+}
+
+/** Only a literal member name has a statically proved operation. */
+const memberName = (expression) => ts.isPropertyAccessExpression(expression) ? expression.name.text : null
+
+/** Computed literal names have ordinary last-write semantics; dynamic names could overwrite any field. */
+const propertyName = (name) => ts.isComputedPropertyName(name)
+    ? ts.isStringLiteralLike(name.expression) ? name.expression.text : null
+    : ts.isIdentifier(name) || ts.isStringLiteralLike(name) || ts.isNumericLiteral(name) ? name.text : null
+
+/** Property mappings retain their last assignment, including spreads, as JavaScript does. */
+const propertyValue = (checker, expression, name) => {
+    if (!expression) return null
+    if (!ts.isObjectLiteralExpression(expression)) return checker.getPropertyOfType(checker.getTypeAtLocation(expression), name) ? { base: expression, name } : null
+    let result = null
+    for (const property of expression.properties) {
+        if (ts.isSpreadAssignment(property)) {
+            const type = checker.getTypeAtLocation(property.expression)
+            if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown) || checker.getIndexTypeOfType(type, ts.IndexKind.String)) result = null
+            else if (checker.getPropertyOfType(type, name)) result = { base: property.expression, name }
+        } else if (propertyName(property.name) === null) result = null
+        else if (propertyName(property.name) === name) {
+            result = ts.isPropertyAssignment(property) ? { expression: property.initializer }
+                : ts.isShorthandPropertyAssignment(property) ? { expression: property.name } : null
+        }
+    }
+    return result
+}
+
+/** A property path is rooted in the same lexical parameter, so a renamed or shadowed value cannot invent a key. */
+const parameterPath = (checker, expression, parameter) => {
+    const path = []
+    let current = expression
+    while (current && ts.isPropertyAccessExpression(current) && !current.questionDotToken) {
+        path.unshift(current.name.text)
+        current = current.expression
+    }
+    return current && ts.isIdentifier(current) && valueSymbol(checker, current) === valueSymbol(checker, parameter.name) ? path : null
+}
+
+/** A mapped field has the expected path from the original parameter. */
+const mappedFrom = (checker, mapping, parameter, paths) => {
+    if (!mapping) return false
+    const path = parameterPath(checker, mapping.expression ?? mapping.base, parameter)
+    if (!path) return false
+    if (mapping.name) path.push(mapping.name)
+    return paths.some((expected) => path.length === expected.length && path.every((part, index) => part === expected[index]))
+}
+
+/** Type origins bind the transactional manager and inbox port to their actual owners. */
+const hasOrigin = (checker, hfs, expression, name, pkg, capability) => !!expression && originsOfType(checker, checker.getTypeAtLocation(expression)).some((origin) =>
+    origin.name === name && origin.module === pkg && (!capability || hfs.tierOf(origin.file) === "platform" && ownerNameOf(hfs, origin.file) === capability))
+
+/** Rejects visible calls, writes, constructions and explicit getter accesses before the inbox claim. */
+const pureEnvelope = (checker, expression) => {
+    let pure = true
+    const visit = (node) => {
+        if (ts.isCallExpression(node) || ts.isNewExpression(node) || ts.isAwaitExpression(node)
+            || ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && node.operatorToken.kind <= ts.SyntaxKind.LastAssignment
+            || ts.isPrefixUnaryExpression(node) && [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(node.operator)
+            || ts.isPostfixUnaryExpression(node)) pure = false
+        if (ts.isPropertyAccessExpression(node) && valueSymbol(checker, node)?.getDeclarations()?.some(ts.isGetAccessorDeclaration)) pure = false
+        ts.forEachChild(node, visit)
+    }
+    visit(expression)
+    return pure
+}
+
+/** The service returns its transaction, whose actual callback returns the inbox execution with that callback's own manager. */
+const transactionalClient = (checker, hfs, method) => {
+    const transaction = returned(method.body)
+    if (!transaction || !ts.isCallExpression(transaction) || transaction.questionDotToken || transaction.expression.questionDotToken || memberName(transaction.expression) !== "transaction"
+        || !hasOrigin(checker, hfs, transaction.expression.expression, "EntityManager", "typeorm")) return false
+    const first = transaction.arguments[0]
+    const callback = transaction.arguments.length === 1 ? first : transaction.arguments.length === 2
+        && ts.isStringLiteral(first) && ["READ UNCOMMITTED", "READ COMMITTED", "REPEATABLE READ", "SERIALIZABLE"].includes(first.text) ? transaction.arguments[1] : null
+    if (!callback || ![ts.SyntaxKind.ArrowFunction, ts.SyntaxKind.FunctionExpression].includes(callback.kind)
+        || callback.parameters.length !== 1 || !ts.isIdentifier(callback.parameters[0].name)) return false
+    const execution = returned(callback.body)
+    if (!execution || !ts.isCallExpression(execution) || execution.questionDotToken || execution.expression.questionDotToken || memberName(execution.expression) !== "runClient"
+        || !hasOrigin(checker, hfs, execution.expression.expression, "Inbox", null, "inbox") || execution.arguments.length !== 3) return false
+    const [envelope, manager, effect] = execution.arguments
+    const original = method.parameters[0]
+    if (!original || !ts.isIdentifier(original.name) || !requiredString(checker, checker.getTypeAtLocation(original), "idempotencyKey")
+        || !ts.isIdentifier(manager) || valueSymbol(checker, manager) !== valueSymbol(checker, callback.parameters[0].name)
+        || !hasOrigin(checker, hfs, manager, "EntityManager", "typeorm") || !ts.isObjectLiteralExpression(envelope)
+        || ![ts.SyntaxKind.ArrowFunction, ts.SyntaxKind.FunctionExpression].includes(effect.kind) || effect.parameters.length !== 0
+        || !pureEnvelope(checker, envelope)) return false
+    const key = propertyValue(checker, envelope, "idempotencyKey")
+    const principal = propertyValue(checker, envelope, "principalId")
+    const operation = propertyValue(checker, envelope, "operation")?.expression
+    return mappedFrom(checker, key, original, [["idempotencyKey"]]) && !!principal?.expression
+        && (parameterPath(checker, principal.expression, original)?.length ?? 0) > 0
+        && !!operation && ts.isStringLiteralLike(operation) && operation.text.length > 0
+        && !!propertyValue(checker, envelope, "request")
+}
+
+/** The CommandHandler decorator resolves its marked command declaration. */
+const handledCommand = (checker, hfs, node) => {
+    for (const decorator of decorators(checker, node)) {
+        if (!fromPackage(checker, decorator.expression, "CommandHandler", "@nestjs/cqrs") || decorator.args.length !== 1) continue
+        const command = valueSymbol(checker, decorator.args[0])?.getDeclarations()?.find(ts.isClassDeclaration)
+        if (command && effectful(checker, hfs, command)) return command
+    }
+    return null
+}
+
+/** A marked handler delegates once to a concrete domain service and preserves the request's key. */
+const delegatedMethod = (checker, hfs, handler) => {
+    const process = handler.members.find((member) => ts.isMethodDeclaration(member) && member.name.getText() === "process")
+    const call = returned(process?.body)
+    if (!process || process.parameters.length !== 1 || !ts.isIdentifier(process.parameters[0].name)
+        || !call || !ts.isCallExpression(call) || call.questionDotToken || call.expression.questionDotToken || call.arguments.length !== 1) return null
+    const method = checker.getResolvedSignature(call)?.declaration
+    if (!method || !ts.isMethodDeclaration(method) || !method.body
+        || hfs.tierOf(method.getSourceFile().fileName) !== "domain" || !baseName(method.getSourceFile().fileName).endsWith(".service.ts")) return null
+    const mapping = propertyValue(checker, call.arguments[0], "idempotencyKey")
+    return mappedFrom(checker, mapping, process.parameters[0], [["params", "idempotencyKey"], ["params", "request", "idempotencyKey"]]) ? method : null
+}
+
+/** Every reached service method is judged when that file is linted, including changed domain files. */
+const reachedByProgram = new WeakMap()
+const reachedServices = (checker, program, hfs) => {
+    const cached = reachedByProgram.get(program)
+    if (cached) return cached
+    const methods = new Set()
+    for (const source of program.getSourceFiles()) {
+        if (hfs.slotOf(source.fileName) !== "be.feature.application") continue
+        const visit = (node) => {
+            if (ts.isClassDeclaration(node) && handledCommand(checker, hfs, node)) {
+                const method = delegatedMethod(checker, hfs, node)
+                if (method) methods.add(method)
+            }
+            ts.forEachChild(node, visit)
+        }
+        visit(source)
+    }
+    reachedByProgram.set(program, methods)
+    return methods
+}
+
+/** Genuine validators must reject empty, optional and overlong wire keys. */
+const boundedKey = (checker, declaration) => {
+    if (!declaration || !ts.isPropertyDeclaration(declaration) || declaration.questionToken
+        || propertyName(declaration.name) === null
+        || !requiredString(checker, checker.getTypeAtLocation(declaration.parent), propertyName(declaration.name))) return false
+    const validators = decorators(checker, declaration).filter((decorator) => decorator.called && decorator.symbol?.getDeclarations()?.some((item) => moduleOf(item, item.getSourceFile().fileName) === "class-validator"))
+    const has = (name) => validators.some((decorator) => decorator.symbol.name === name)
+    const bound = (name, accepts) => validators.some((decorator) => decorator.symbol.name === name
+        && decorator.args.length > 0 && ts.isNumericLiteral(decorator.args[0]) && accepts(Number(decorator.args[0].text)))
+    return !has("IsOptional") && !has("ValidateIf") && (has("IsUUID") || has("IsString")
+        && bound("MinLength", (value) => value >= 1) && bound("MaxLength", (value) => value >= 1 && value <= 64))
+}
+
+/** Follow object mappings to their original property declarations rather than trusting an annotated return type. */
+const propertySymbol = (checker, expression, path) => {
+    if (path.length === 0) return valueSymbol(checker, expression)
+    if (ts.isObjectLiteralExpression(expression)) {
+        const mapping = propertyValue(checker, expression, path[0])
+        if (!mapping) return undefined
+        return mapping.expression ? propertySymbol(checker, mapping.expression, path.slice(1))
+            : propertySymbol(checker, mapping.base, [mapping.name, ...path.slice(1)])
+    }
+    let type = checker.getTypeAtLocation(expression)
+    let symbol
+    for (const name of path) {
+        symbol = checker.getPropertyOfType(type, name)
+        const declaration = symbol?.valueDeclaration ?? symbol?.declarations?.[0]
+        if (!declaration) return undefined
+        type = checker.getTypeOfSymbolAtLocation(symbol, declaration)
+    }
+    return symbol
+}
+
+/** A key mapped by a pure function must come from its actual argument, never a constant or captured replacement. */
+const mappedKeySymbol = (checker, mapping, bindings = new Map()) => {
+    if (!mapping) return undefined
+    const path = mapping.name ? [mapping.name] : []
+    let expression = mapping.expression ?? mapping.base
+    while (ts.isPropertyAccessExpression(expression) && !expression.questionDotToken) {
+        path.unshift(expression.name.text)
+        expression = expression.expression
+    }
+    const actual = bindings.get(valueSymbol(checker, expression))
+    if (actual) return propertySymbol(checker, actual, path)
+    return bindings.size > 0 ? undefined : propertySymbol(checker, expression, path)
+}
+
+/** A mapper is proved by its sole pure return expression and original argument bindings, not its function name. */
+const requestKey = (checker, expression) => {
+    if (!ts.isCallExpression(expression)) return mappedKeySymbol(checker, propertyValue(checker, expression, "idempotencyKey"))
+    const mapper = checker.getResolvedSignature(expression)?.declaration
+    const body = returned(mapper?.body)
+    if (!mapper || !body || expression.questionDotToken || mapper.parameters.length !== expression.arguments.length
+        || mapper.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword)
+        || !pureEnvelope(checker, body) || expression.arguments.some((argument) => !pureEnvelope(checker, argument))) return undefined
+    const bindings = new Map()
+    for (const [index, parameter] of mapper.parameters.entries()) {
+        if (!ts.isIdentifier(parameter.name) || parameter.initializer || parameter.dotDotDotToken) return undefined
+        bindings.set(valueSymbol(checker, parameter.name), expression.arguments[index])
+    }
+    return mappedKeySymbol(checker, propertyValue(checker, body, "idempotencyKey"), bindings)
+}
+
+/** Follow the constructor's key mapping to the original DTO property, including a whole ExecuteParams value. */
+const constructionKey = (checker, construction) => {
+    const params = construction.arguments?.[0]
+    const request = propertyValue(checker, params, "request")
+    let nestedSymbol
+    if (request?.base) {
+        const property = checker.getPropertyOfType(checker.getTypeAtLocation(request.base), request.name)
+        const declaration = property?.valueDeclaration ?? property?.declarations?.[0]
+        if (declaration) nestedSymbol = checker.getPropertyOfType(checker.getTypeOfSymbolAtLocation(property, declaration), "idempotencyKey")
+    }
+    return nestedSymbol ?? (request?.expression ? requestKey(checker, request.expression)
+        : mappedKeySymbol(checker, propertyValue(checker, params, "idempotencyKey")))
+}
+
+/** Only DTO key declarations that reach an effectful command carry this rule's transport obligation. */
+const keysByProgram = new WeakMap()
+const reachedKeys = (checker, program, hfs) => {
+    const cached = keysByProgram.get(program)
+    if (cached) return cached
+    const keys = new Set()
+    for (const source of program.getSourceFiles()) {
+        if (!isTransportSlot(hfs.slotOf(source.fileName))) continue
+        const visit = (node) => {
+            if (ts.isNewExpression(node)) {
+                const command = valueSymbol(checker, node.expression)?.getDeclarations()?.find(ts.isClassDeclaration)
+                if (command && effectful(checker, hfs, command)) {
+                    for (const declaration of constructionKey(checker, node)?.getDeclarations() ?? []) keys.add(declaration)
+                }
+            }
+            ts.forEachChild(node, visit)
+        }
+        visit(source)
+    }
+    keysByProgram.set(program, keys)
+    return keys
+}
+
+/** Effectful commands carry a bounded client key to the one atomic domain inbox execution. */
+export const mutationIdempotent = {
+    meta: {
+        type: "problem",
+        docs: { description: "An @Effectful command requires a validated client key and delegates to a domain transaction returning Inbox.runClient with that same key and manager." },
+        schema: [],
+        messages: {
+            marker: "[BE_MUTATION_IDEMPOTENT] Use @Effectful() exported by platform/inbox on a Nest Command; a local lookalike or a marker on a query does not designate an effectful command.",
+            declaration: "[BE_MUTATION_IDEMPOTENT] This @Effectful command requires idempotency in hfs.json sides.be.patterns, including its required behavior scenarios in the app's proof lane.",
+            key: "[BE_MUTATION_IDEMPOTENT] This @Effectful command requires a non-optional string idempotencyKey in its params request. Preserve the client's key through transport and handler mapping.",
+            handler: "[BE_MUTATION_IDEMPOTENT] This effectful command handler must return one domain service call carrying the original params.request.idempotencyKey. The service owns its transaction and the inbox claim.",
+            transaction: "[BE_MUTATION_IDEMPOTENT] This effectful domain method must return an EntityManager transaction whose inline callback returns Inbox.runClient({principalId, operation, idempotencyKey, request}, callbackManager, async () => outcome). Use the original key and callback manager, and put every effect in the final callback.",
+            validation: "[BE_MUTATION_IDEMPOTENT] The client idempotencyKey must be required and validated by class-validator: @IsUUID(), or @IsString() @MinLength(1) @MaxLength(64). Optional or conditional validation cannot protect an effectful command.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const slot = hfs.slotOf(context.filename)
+        if (!slot || slot.startsWith("be.tests.")) return {}
+        const { checker, program, toTs } = typed(context)
+        let reached
+        let keys
+        return {
+            Identifier(node) {
+                if (hfs.tierOf(context.filename) === "platform" && ownerNameOf(hfs, context.filename) === "inbox"
+                    || !ownedValue(checker, hfs, toTs(node), "Effectful", "inbox")) return
+                const parent = node.parent
+                const typeOnly = parent?.type?.startsWith("TS") && !["TSAsExpression", "TSTypeAssertion", "TSNonNullExpression", "TSSatisfiesExpression", "TSInstantiationExpression"].includes(parent.type)
+                if (["ImportSpecifier", "ExportSpecifier", "Decorator"].includes(parent?.type) || typeOnly) return
+                if (parent?.type === "VariableDeclarator" && parent.id === node) return
+                if (parent?.type === "Property" && parent.key === node && !parent.computed && parent.value !== node) return
+                const reference = parent?.type === "MemberExpression" && parent.property === node ? parent : node
+                if (reference.parent?.type === "CallExpression" && reference.parent.callee === reference) return
+                if (reference.parent?.type === "VariableDeclarator" && reference.parent.init === reference && reference.parent.parent.kind === "const") return
+                context.report({ node, messageId: "marker" })
+            },
+            CallExpression(node) {
+                const call = toTs(node)
+                if (ownedValue(checker, hfs, call.expression, "Effectful", "inbox") && node.parent?.type !== "Decorator") context.report({ node, messageId: "marker" })
+            },
+            ClassDeclaration(node) {
+                const declaration = toTs(node)
+                const marks = decorators(checker, declaration).filter((decorator) => decorator.symbol?.name === "Effectful")
+                if (marks.length > 0) {
+                    if (!effectful(checker, hfs, declaration) || !commandType(checker, checker.getTypeAtLocation(declaration))) {
+                        context.report({ node: node.id ?? node, messageId: "marker" })
+                    } else {
+                        if (!(hfs.patterns ?? []).includes("idempotency")) context.report({ node: node.id ?? node, messageId: "declaration" })
+                        const constructor = declaration.members.find(ts.isConstructorDeclaration)
+                        if (!constructor || constructor.parameters.length !== 1 || !keyContract(checker, checker.getTypeAtLocation(constructor.parameters[0]))) context.report({ node: node.id ?? node, messageId: "key" })
+                    }
+                }
+                if (!handledCommand(checker, hfs, declaration)) return
+                const method = delegatedMethod(checker, hfs, declaration)
+                if (!method) context.report({ node: node.id ?? node, messageId: "handler" })
+                else if (!transactionalClient(checker, hfs, method)) context.report({ node: node.id ?? node, messageId: "transaction" })
+            },
+            MethodDefinition(node) {
+                if (hfs.tierOf(context.filename) !== "domain" || !baseName(context.filename).endsWith(".service.ts")) return
+                reached ??= reachedServices(checker, program, hfs)
+                const method = toTs(node)
+                if (reached.has(method) && !transactionalClient(checker, hfs, method)) context.report({ node: node.key, messageId: "transaction" })
+            },
+            PropertyDefinition(node) {
+                if (!isTransportSlot(slot)) return
+                keys ??= reachedKeys(checker, program, hfs)
+                const declaration = toTs(node)
+                if (keys.has(declaration) && !boundedKey(checker, declaration)) context.report({ node: node.key, messageId: "validation" })
+            },
+            NewExpression(node) {
+                if (!isTransportSlot(slot)) return
+                const construction = toTs(node)
+                const command = valueSymbol(checker, construction.expression)?.getDeclarations()?.find(ts.isClassDeclaration)
+                if (!command || !effectful(checker, hfs, command)) return
+                const declarations = constructionKey(checker, construction)?.getDeclarations() ?? []
+                const localProperty = declarations.some((declaration) => ts.isPropertyDeclaration(declaration) && declaration.getSourceFile() === construction.getSourceFile())
+                if (!localProperty && !declarations.some((declaration) => boundedKey(checker, declaration))) context.report({ node, messageId: "validation" })
+            },
+        }
+    },
+}

package/lib/persistence.mjs

@@ -105,7 +105,7 @@ export const connectionFileOf = (hfs, file, role) => {
 }
 
 /** The platform capabilities that own a `persistence/` and so may hold an `EntityManager` (a pattern capability is named by its folder). */
-const PERSISTENCE_CAPABILITIES = ["database", "inbox", "event-bus", "queue", "jobs", "saga", "outbox"]
+const PERSISTENCE_CAPABILITIES = ["database", "inbox", "event-bus", "queue", "jobs", "saga", "outbox", "realtime"]
 
 /**
  * Whether a class in this file may receive an `EntityManager`: an application handler, a domain service, a projection, a typed queue producer (it takes the transaction of its caller), a platform persistence capability.