@starci/eslint-canon-be 3.4.39 → 3.4.41

package/lib/schema-values.mjs

@@ -0,0 +1,90 @@
+import fs from "node:fs"
+import path from "node:path"
+import ts from "typescript"
+import { normalizePath } from "./path.mjs"
+
+/** Tiers a schema file may live in: the owners of boundary data (R304). */
+export const SCHEMA_TIERS = new Set(["domain", "platform", "integrations"])
+
+const ZOD = /^zod(?:\/|$)/
+/** A sibling schema module: its exports are schemas too, so a chain may start from them. */
+const SIBLING_SCHEMA = /^\.{1,2}\/(?:.*\/)?[^/]+\.schema(?:\.[cm]?[jt]s)?$/
+
+/** The local names the imports of a source file bind whose module specifier matches `specifier`. */
+const importedNames = (sourceFile, specifier) => {
+    const names = new Set()
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !specifier.test(statement.moduleSpecifier.text)) continue
+        const clause = statement.importClause
+        if (clause?.name) names.add(clause.name.text)
+        const bindings = clause?.namedBindings
+        if (bindings && ts.isNamespaceImport(bindings)) names.add(bindings.name.text)
+        if (bindings && ts.isNamedImports(bindings)) for (const element of bindings.elements) names.add(element.name.text)
+    }
+    return names
+}
+
+/** The identifier a call/member chain starts from (`z.string().max(5)` gives `z`), or null when it starts from anything else. */
+const rootOf = (expression) => {
+    let current = expression
+    for (;;) {
+        if (ts.isIdentifier(current)) return current.text
+        if (ts.isCallExpression(current) || ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current)
+            || ts.isNonNullExpression(current) || ts.isParenthesizedExpression(current) || ts.isAsExpression(current)) current = current.expression
+        else return null
+    }
+}
+
+/** A literal bound (`100`, `-1`, `"x"`, `true`): data a schema reads, nothing that runs. */
+const isLiteral = (expression) => ts.isNumericLiteral(expression) || ts.isStringLiteralLike(expression)
+    || expression.kind === ts.SyntaxKind.TrueKeyword || expression.kind === ts.SyntaxKind.FalseKeyword
+    || (ts.isPrefixUnaryExpression(expression) && ts.isNumericLiteral(expression.operand))
+
+/** A statement a schema file may hold: an import, a type, or `export const X = <zod chain or a sibling schema>`. */
+const statementProblem = (statement, zodNames, declared) => {
+    if (ts.isImportDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isInterfaceDeclaration(statement)) return null
+    if (ts.isExportDeclaration(statement)) return null
+    if (!ts.isVariableStatement(statement)) return `a ${ts.SyntaxKind[statement.kind]} is logic, not a schema value`
+    for (const declaration of statement.declarationList.declarations) {
+        const init = declaration.initializer
+        if (init && isLiteral(init) && ts.isIdentifier(declaration.name)) { declared.add(declaration.name.text); continue }
+        const root = init ? rootOf(init) : null
+        if (!ts.isIdentifier(declaration.name) || root === null || !(zodNames.has(root) || declared.has(root))) {
+            return `${declaration.name.getText()} is not a zod schema (a schema file declares only zod chains and types)`
+        }
+        declared.add(declaration.name.text)
+    }
+    return null
+}
+
+/**
+ * The reasons a source text is not a pure boundary schema file: it imports zod and holds nothing but imports, types and
+ * `const X = <zod chain>` values, with no class, function, provider or other logic. An empty list means a value-only schema file.
+ */
+export const schemaFileProblems = (text) => {
+    const sourceFile = ts.createSourceFile("subject.schema.ts", text, ts.ScriptTarget.Latest, true)
+    const zodNames = importedNames(sourceFile, ZOD)
+    if (zodNames.size === 0) return ["it imports no zod, so it is not a boundary schema"]
+    const declared = importedNames(sourceFile, SIBLING_SCHEMA)
+    return sourceFile.statements.flatMap((statement) => {
+        const problem = statementProblem(statement, zodNames, declared)
+        return problem === null ? [] : [problem]
+    })
+}
+
+const CACHE = new Map()
+
+/**
+ * Whether the sibling `<name>.schema.ts` of a `<name>.schema.spec.ts` is a real boundary schema: it exists, lives in an owner tier of R304 and is
+ * value-only (schemaFileProblems). Read from disk once per file and modification time.
+ */
+export const siblingIsValueSchema = (hfs, specFile) => {
+    const sibling = normalizePath(path.resolve(specFile.replace(/\.spec\.ts$/u, ".ts")))
+    if (!fs.existsSync(sibling) || !SCHEMA_TIERS.has(hfs.tierOf(sibling))) return false
+    const stamp = fs.statSync(sibling).mtimeMs
+    const cached = CACHE.get(sibling)
+    if (cached?.stamp === stamp) return cached.ok
+    const ok = schemaFileProblems(fs.readFileSync(sibling, "utf8")).length === 0
+    CACHE.set(sibling, { stamp, ok })
+    return ok
+}

package/lib/unit-spec.mjs

@@ -66,6 +66,12 @@ export const unitRoleOfSpec = (hfs, filename) => {
     return [...unitRoles(hfs), ...optionalRoles(hfs)].find((role) => name.endsWith(`.${role.spec}.ts`) && inRoleSlot(hfs, role, filename)) ?? null
 }
 
+/** Whether a file is the spec of a value role (`ruleParams.be.valueRoles`: a zod schema): its subject is a declared value, so the spec parses it and builds no testing module. */
+export const isValueRoleSpec = (hfs, filename) => {
+    const role = unitRoleOfSpec(hfs, filename)?.role
+    return role !== undefined && (hfs.ruleParams.valueRoles ?? []).includes(role)
+}
+
 /**
  * The unit-tested role whose subject a file is (`<name>.<role>.ts`, in the role's slot, outside the test tree), or null.
  *

package/operations.mjs

@@ -1,9 +1,9 @@
 /**
  * The rules that hold BE-OPERATIONS-1 (R95 `BE_OPERATION_CONTRACT`).
  *
- * A versioned operation is declared once, in the app's typed operation table (`platform/operations`: `query<Input, Output,
- * RefusalCode>()` and `mutation<...>()` registered by `defineOperations`), and the contract emit derives `contracts/<app>/openapi.json`
- * from that table with the type checker. An operation whose input or output the checker cannot express (`any`, `unknown`,
+ * A versioned operation is declared once, in the app's typed operation table (`platform/operations`: `query({ input, output })`
+ * and `mutation({ input, output })` registered by `defineOperations`), and the contract emit derives `contracts/<app>/openapi.json`
+ * from its bounded zod schemas. An operation whose input or output the checker cannot express (`any`, `unknown`,
  * `Record<string, unknown>`, an unbound generic) says nothing to a client, and a route that takes or answers those types by another
  * road than the table's own `OperationRequest` and `OperationReply` is a second, untyped contract.
  *
@@ -38,6 +38,129 @@ const isCanonType = (hfs, checker, symbol, name) => declarationsOfSymbol(checker
 
 const F = ts.TypeFlags
 
+/** Optional object fields can be absent; an operation's root input/value must itself be a JSON value. */
+const rootMayBeAbsent = (type) => Boolean(type.flags & (F.Undefined | F.Void)) || (type.isUnion() && type.types.some(rootMayBeAbsent))
+
+/** Follow constant aliases and declaration wrappers without trusting an asserted type. */
+const expressionOf = (checker, node, seen = new Set()) => {
+    if (!node || seen.has(node)) return node
+    seen.add(node)
+    if (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isSatisfiesExpression(node) || ts.isParenthesizedExpression(node) || ts.isNonNullExpression(node)) return expressionOf(checker, node.expression, seen)
+    if (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node) || ts.isQualifiedName(node)) {
+        for (const declaration of declarationsOfSymbol(checker, checker.getSymbolAtLocation(node))) {
+            if (ts.isShorthandPropertyAssignment(declaration)) {
+                const value = checker.getShorthandAssignmentValueSymbol(declaration)
+                const home = declarationsOfSymbol(checker, value).find((candidate) => ts.isVariableDeclaration(candidate) && candidate.initializer)
+                if (home) return expressionOf(checker, home.initializer, seen)
+            }
+            if ((ts.isVariableDeclaration(declaration) || ts.isPropertyAssignment(declaration)) && declaration.initializer) return expressionOf(checker, declaration.initializer, seen)
+        }
+    }
+    return node
+}
+
+/** A schema is a named declaration of its boundary owner, including re-exports and local aliases. */
+const ownerSchema = (hfs, checker, node, seen = new Set()) => {
+    if (!node || seen.has(node)) return false
+    seen.add(node)
+    if (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isSatisfiesExpression(node) || ts.isParenthesizedExpression(node) || ts.isNonNullExpression(node)) return ownerSchema(hfs, checker, node.expression, seen)
+    if (!ts.isIdentifier(node) && !ts.isPropertyAccessExpression(node)) return false
+    const type = checker.getTypeAtLocation(node)
+    const parser = type.getProperty("safeParse")
+    if (!(parser?.getDeclarations() ?? []).some((declaration) => /\/node_modules\/zod\//.test(declaration.getSourceFile().fileName.replace(/\\/g, "/")))) return false
+    for (const declaration of declarationsOfSymbol(checker, checker.getSymbolAtLocation(node))) {
+        const source = declaration.getSourceFile()
+        const file = source.fileName
+        const module = checker.getSymbolAtLocation(source)
+        const exported = module && checker.getExportsOfModule(module).some((symbol) => declarationsOfSymbol(checker, symbol).includes(declaration))
+        if (/\.schema\.ts$/.test(file) && ["domain", "platform", "integrations"].includes(hfs.tierOf(file)) && exported) return true
+        if (ts.isVariableDeclaration(declaration) && declaration.initializer && ownerSchema(hfs, checker, declaration.initializer, seen)) return true
+        if (ts.isShorthandPropertyAssignment(declaration)) {
+            for (const home of declarationsOfSymbol(checker, checker.getShorthandAssignmentValueSymbol(declaration))) {
+                if (ts.isVariableDeclaration(home) && home.initializer && ownerSchema(hfs, checker, home.initializer, seen)) return true
+            }
+        }
+    }
+    return false
+}
+
+/** Read a property initializer from a closed declaration object, following an alias of that object. */
+const propertyValue = (checker, expression, name) => {
+    const object = expressionOf(checker, expression)
+    if (!object) return null
+    const property = checker.getTypeAtLocation(object).getProperty(name)
+    for (const declaration of property?.getDeclarations() ?? []) {
+        if (ts.isPropertyAssignment(declaration)) return declaration.initializer
+        if (ts.isShorthandPropertyAssignment(declaration)) return declaration.name
+    }
+    return null
+}
+
+/** A spec registers tables to test the platform capability; such a table is local to the spec and serves no operation. */
+const isSpecFile = (filename) => /\.(?:spec|e2e-spec|integration-spec|contract-spec)\.ts$/.test(filename.replaceAll("\\", "/"))
+
+const TS_WRAPPERS = new Set(["TSAsExpression", "TSSatisfiesExpression", "TSNonNullExpression", "TSTypeAssertion"])
+
+/**
+ * Whether the table a `defineOperations` call makes leaves its file: `export const X = ...`, `export { X }` or `export default X`.
+ * A spec may keep a stub table to itself; one it exports can be imported by production code, so it is judged like any table.
+ *
+ * @param {object} node - The CallExpression (ESTree).
+ * @returns {boolean} True when the registered table is exported.
+ */
+const tableLeavesFile = (node) => {
+    let value = node
+    while (TS_WRAPPERS.has(value.parent?.type)) value = value.parent
+    const parent = value.parent
+    if (parent?.type === "ExportDefaultDeclaration") return true
+    if (parent?.type !== "VariableDeclarator" || parent.init !== value || parent.id.type !== "Identifier") return false
+    if (parent.parent?.parent?.type === "ExportNamedDeclaration") return true
+    let program = parent
+    while (program.parent) program = program.parent
+    return program.body.some((statement) => {
+        if (statement.type === "ExportDefaultDeclaration") return statement.declaration?.type === "Identifier" && statement.declaration.name === parent.id.name
+        return statement.type === "ExportNamedDeclaration" && statement.specifiers.some((specifier) => specifier.local.name === parent.id.name)
+    })
+}
+
+/** The operation table must supply the runtime schemas that a generic request type cannot validate. */
+export const operationTableSchemas = {
+    meta: {
+        type: "problem",
+        docs: { description: "Every defineOperations entry declares bounded input and output schemas from an owner's *.schema.ts file." },
+        schema: [],
+        messages: {
+            schemas: "Operation {{operation}} has no boundary schemas. Declare query({ input: InputSchema, output: OutputSchema }) or mutation(...), using named bounded zod schema exports from an owner's `*.schema.ts` file (R304/R305).",
+            table: "The operation table must be a nonempty closed declaration whose entries supply runtime input and output schemas.",
+        },
+    },
+    create(context) {
+        const inSpec = isSpecFile(context.filename)
+        const hfs = hfsOf(context)
+        const { checker, toTs } = typed(context)
+        return {
+            CallExpression(node) {
+                const call = toTs(node)
+                if (!isCanonType(hfs, checker, checker.getSymbolAtLocation(call.expression), "defineOperations")) return
+                if (inSpec && !tableLeavesFile(node)) return
+                const argument = expressionOf(checker, call.arguments[0])
+                const entries = argument ? checker.getPropertiesOfType(checker.getTypeAtLocation(argument)) : []
+                if (entries.length === 0) {
+                    context.report({ node, messageId: "table" })
+                    return
+                }
+                for (const entry of entries) {
+                    const declaration = entry.getDeclarations()?.find((candidate) => ts.isPropertyAssignment(candidate) || ts.isShorthandPropertyAssignment(candidate))
+                    const value = declaration && expressionOf(checker, ts.isShorthandPropertyAssignment(declaration) ? declaration.name : declaration.initializer)
+                    const helper = value && ts.isCallExpression(value) && ["query", "mutation"].some((name) => isCanonType(hfs, checker, checker.getSymbolAtLocation(value.expression), name))
+                    const options = helper ? value.arguments[0] : null
+                    if (!["input", "output"].every((name) => ownerSchema(hfs, checker, propertyValue(checker, options, name)))) context.report({ node, messageId: "schemas", data: { operation: entry.getName() } })
+                }
+            },
+        }
+    },
+}
+
 /**
  * Why a type says nothing on the wire, or null when the checker can express it.
  *
@@ -46,7 +169,7 @@ const F = ts.TypeFlags
  * @param {Set<object>} seen - The types already judged (recursive types).
  * @returns {string | null} The reason, or null.
  */
-const whyUndecidable = (checker, type, seen = new Set()) => {
+const whyUndecidable = (checker, type, seen = new Set(), schemaBacked = false) => {
     if (seen.has(type)) return null
     seen.add(type)
     const flags = type.flags
@@ -59,7 +182,7 @@ const whyUndecidable = (checker, type, seen = new Set()) => {
     if (type.isUnion() || type.isIntersection()) {
         for (const member of type.types) {
             if (member.flags & (F.Undefined | F.Void)) continue
-            const why = whyUndecidable(checker, member, seen)
+            const why = whyUndecidable(checker, member, seen, schemaBacked)
             if (why) return why
         }
         return null
@@ -68,7 +191,7 @@ const whyUndecidable = (checker, type, seen = new Set()) => {
         if (type.getCallSignatures().length || type.getConstructSignatures().length) return "a function"
         if (checker.isArrayType(type) || checker.isTupleType(type)) {
             for (const item of checker.getTypeArguments(type)) {
-                const why = whyUndecidable(checker, item, seen)
+                const why = whyUndecidable(checker, item, seen, schemaBacked)
                 if (why) return why
             }
             return null
@@ -77,13 +200,15 @@ const whyUndecidable = (checker, type, seen = new Set()) => {
         if (own && !own.getName().startsWith("__") && (own.getDeclarations() ?? []).some((declaration) => /[\\/]typescript[\\/]lib[\\/]lib\./.test(declaration.getSourceFile().fileName))) return `${own.getName()}, which is not a JSON value`
         const props = checker.getPropertiesOfType(type)
         const index = checker.getIndexInfosOfType(type)
-        if (props.length === 0 && index.length === 0) return "an object type with no members"
+        if (props.length === 0 && index.length === 0 && !schemaBacked) return "an object type with no members"
         for (const info of index) {
-            const why = whyUndecidable(checker, info.type, seen)
+            // Zod's strict empty object infers Record<string, never>: no key is permitted, rather than an unknown value.
+            if (schemaBacked && (info.type.flags & F.Never)) continue
+            const why = whyUndecidable(checker, info.type, seen, schemaBacked)
             if (why) return `a record of ${why}`
         }
         for (const prop of props) {
-            const why = whyUndecidable(checker, checker.getTypeOfSymbol(prop), seen)
+            const why = whyUndecidable(checker, checker.getTypeOfSymbol(prop), seen, schemaBacked)
             if (why) return `${prop.getName()}: ${why}`
         }
     }
@@ -104,15 +229,18 @@ export const operationContractDecidable = {
         },
     },
     create(context) {
+        const inSpec = isSpecFile(context.filename)
         const hfs = hfsOf(context)
         const { checker, toTs } = typed(context)
-        if (declaredByOperations(hfs, context.filename.replace(/\\/g, "/"))) return {}
-        const judge = (node, contract) => {
+        const inOwner = declaredByOperations(hfs, context.filename.replace(/\\/g, "/"))
+        const judge = (node, contract, schemaCall = null) => {
             const symbol = contract.aliasSymbol ?? contract.getSymbol()
             if (!isCanonType(hfs, checker, symbol, "OperationContract")) return
+            const call = schemaCall ?? (node.type === "CallExpression" ? toTs(node) : null)
+            const schemaBacked = call && ["query", "mutation"].some((name) => isCanonType(hfs, checker, checker.getSymbolAtLocation(call.expression), name)) && ["input", "output"].every((name) => ownerSchema(hfs, checker, propertyValue(checker, call.arguments[0], name)))
             const [input, output, refusal] = (contract.objectFlags & ts.ObjectFlags.Reference) !== 0 ? checker.getTypeArguments(contract) : (contract.aliasTypeArguments ?? [])
             for (const [label, type] of [["input", input], ["output", output]]) {
-                const why = type ? whyUndecidable(checker, type) : null
+                const why = type ? rootMayBeAbsent(type) ? "undefined or void at the root" : whyUndecidable(checker, type, new Set(), schemaBacked) : null
                 if (why) context.report({ node, messageId: "type", data: { label, why } })
             }
             if (refusal && !(refusal.flags & F.Never)) {
@@ -122,12 +250,34 @@ export const operationContractDecidable = {
         }
         return {
             TSTypeReference(node) {
+                // The capability declares generic OperationContract/OperationTable bounds here; concrete registrations below
+                // still owe the same closed parsed types as operations declared anywhere else.
+                if (inOwner || inSpec) return
                 const tsNode = toTs(node)
                 const type = checker.getTypeFromTypeNode(tsNode)
                 if (type.getSymbol() || type.aliasSymbol) judge(node, type)
             },
             CallExpression(node) {
-                const type = checker.getTypeAtLocation(toTs(node))
+                const call = toTs(node)
+                if ((inOwner || inSpec) && isCanonType(hfs, checker, checker.getSymbolAtLocation(call.expression), "defineOperations")) {
+                    if (inSpec && !tableLeavesFile(node)) return
+                    const argument = call.arguments[0]
+                    const source = expressionOf(checker, argument)
+                    const entries = argument ? checker.getPropertiesOfType(checker.getTypeAtLocation(argument)) : []
+                    for (const entry of entries) {
+                        const contract = checker.getTypeOfSymbol(entry)
+                        const actual = source ? propertyValue(checker, source, entry.getName()) : null
+                        const value = expressionOf(checker, actual)
+                        // Plain helper calls are judged once by their own CallExpression. A declaration annotation can widen
+                        // that result before registration, so its served type also needs a check.
+                        const helper = value && ts.isCallExpression(value) && ["query", "mutation"].some((name) => isCanonType(hfs, checker, checker.getSymbolAtLocation(value.expression), name)) ? value : null
+                        if (inSpec || !helper || contract !== checker.getTypeAtLocation(helper)) judge(node, contract, helper)
+                    }
+                    return
+                }
+                if (inSpec) return
+                if (inOwner &&!["query", "mutation"].some((name) => isCanonType(hfs, checker, checker.getSymbolAtLocation(call.expression), name))) return
+                const type = checker.getTypeAtLocation(call)
                 if (type.getSymbol()) judge(node, type)
             },
         }
@@ -136,6 +286,19 @@ export const operationContractDecidable = {
 
 // -- operation-route-driven-by-table -----------------------------------------------------------------------------
 
+/** The runtime table named by a `typeof OPERATIONS` type argument, including named aliases of that type. */
+const tableExpressionOf = (checker, type, seen = new Set()) => {
+    if (!type || seen.has(type)) return null
+    seen.add(type)
+    if (ts.isTypeQueryNode(type)) return expressionOf(checker, type.exprName)
+    if (ts.isParenthesizedTypeNode(type)) return tableExpressionOf(checker, type.type, seen)
+    if (!ts.isTypeReferenceNode(type)) return null
+    for (const declaration of declarationsOfSymbol(checker, checker.getSymbolAtLocation(type.typeName))) {
+        if (ts.isTypeAliasDeclaration(declaration)) return tableExpressionOf(checker, declaration.type, seen)
+    }
+    return null
+}
+
 /** The canon alias a type annotation node names (`OperationRequest`, `OperationReply`), with its table type argument. */
 const canonReference = (hfs, checker, toTs, annotation) => {
     let node = annotation
@@ -146,7 +309,7 @@ const canonReference = (hfs, checker, toTs, annotation) => {
     for (const name of ["OperationRequest", "OperationReply"]) {
         if (isCanonType(hfs, checker, symbol, name)) {
             const argument = tsNode.typeArguments?.[0]
-            return { name, table: argument ? checker.getTypeFromTypeNode(argument) : null }
+            return { name, table: argument ? checker.getTypeFromTypeNode(argument) : null, expression: tableExpressionOf(checker, argument) }
         }
     }
     return null
@@ -186,7 +349,8 @@ export const operationRouteEvidence = (context) => {
             ts.forEachChild(node, visit)
         }
         for (const source of program.getSourceFiles()) {
-            if (!source.isDeclarationFile && hfs.slotOf(source.fileName)) visit(source)
+            // A table made in a spec is never an app's declared table, even when the spec exports it.
+            if (!source.isDeclarationFile && !isSpecFile(source.fileName) && hfs.slotOf(source.fileName)) visit(source)
         }
         return tables
     }
@@ -328,28 +492,16 @@ export const restRouteDeclared = {
     },
 }
 
-/** True when a pipe argument is `new OperationValidationService(...)`, the class declared by the platform capability `http-security` (resolved by symbol). */
-const isOperationPipe = (hfs, checker, toTs, argument) => {
-    if (argument?.type !== "NewExpression") return false
-    const target = toTs(argument.callee)
-    if (!target) return false
-    return declarationsOfSymbol(checker, checker.getSymbolAtLocation(target)).some((declaration) => {
-        const file = String(declaration.getSourceFile().fileName).replace(/\\/g, "/")
-        return declaration.name?.text === "OperationValidationService" && hfs.slotOf(file) === "be.platform" && hfs.ownerOf(file)?.split("/").pop() === "http-security"
-    })
-}
-
 /** An operation route takes the table's `OperationRequest` and answers its `OperationReply`, of one table, and validates the body it takes. */
 export const operationRouteDrivenByTable = {
     meta: {
         type: "problem",
-        docs: { description: "A route that takes or answers the operation table's types takes OperationRequest<Table> and answers Promise<OperationReply<Table>> of the same table." },
+        docs: { description: "An operation route takes OperationRequest<Table>, validates it with OperationValidationPolicy(Table), and answers Promise<OperationReply<Table>>." },
         schema: [],
         messages: {
             half: "This route takes or answers `{{one}}` but not `{{other}}`. An operation route is driven by the table on both sides: `@Body() request: OperationRequest<Table>` and `Promise<OperationReply<Table>>`.",
             table: "The request and the reply of this route name different operation tables. One route serves one table.",
-            unvalidated:
-                "The body of this operation route is typed by an alias, which leaves no class at run time, so the global pipe validates nothing. Bind it to the request class with `@Body(new OperationValidationService(RequestClass))` of `platform/http-security`.",
+            validation: "A generic OperationRequest is not checked by ValidationPipe. Use `@Body(new OperationValidationPolicy(OPERATIONS))` from platform/operations with the same table as OperationRequest<Table>.",
         },
     },
     create(context) {
@@ -373,9 +525,20 @@ export const operationRouteDrivenByTable = {
                     context.report({ node: node.key, messageId: "table" })
                     return
                 }
-                const body = params[references.indexOf(request)]
-                const pipes = (body.decorators ?? []).filter((decorator) => isImportedFrom(context, decoratorCallee(decorator), "@nestjs/common", "Body")).flatMap(decoratorArguments)
-                if (!pipes.some((pipe) => isOperationPipe(hfs, checker, toTs, pipe))) context.report({ node: body, messageId: "unvalidated" })
+                const validated = params.some((param) => {
+                    const reference = canonReference(hfs, checker, toTs, param.typeAnnotation ?? param.parameter?.typeAnnotation)
+                    if (reference?.name !== "OperationRequest") return false
+                    return (param.decorators ?? []).some((decorator) => {
+                        if (!isImportedFrom(context, decoratorCallee(decorator), "@nestjs/common", "Body")) return false
+                        const args = decoratorArguments(decorator)
+                        if (args.length !== 1) return false
+                        const pipe = expressionOf(checker, toTs(args[0]))
+                        if (!pipe || !ts.isNewExpression(pipe) || !isCanonType(hfs, checker, checker.getSymbolAtLocation(pipe.expression), "OperationValidationPolicy")) return false
+                        const table = expressionOf(checker, pipe.arguments?.[0])
+                        return pipe.arguments?.length === 1 && table && request.expression && table === request.expression
+                    })
+                })
+                if (!validated) context.report({ node: node.key, messageId: "validation" })
             },
         }
     },
@@ -384,6 +547,7 @@ export const operationRouteDrivenByTable = {
 /** Every rule of this law. */
 export const rules = {
     "operation-contract-decidable": operationContractDecidable,
+    "operation-table-schemas": operationTableSchemas,
     "operation-route-driven-by-table": operationRouteDrivenByTable,
     "rest-route-declared": restRouteDeclared,
 }
@@ -391,6 +555,7 @@ export const rules = {
 /** Every rule of this law at `error`. */
 export const recommended = {
     "starci-be/operation-contract-decidable": "error",
+    "starci-be/operation-table-schemas": "error",
     "starci-be/operation-route-driven-by-table": "error",
     "starci-be/rest-route-declared": "error",
 }

package/package.json

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

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -1,6 +1,6 @@
 schema: starci/canon-pins@1
 purpose: >-
-  The exact version of every dependency a StarCi product repository pins. One version per dependency for the whole
+  The exact version of every shared dependency in the StarCi family, including package-owned runtime dependencies. One version per dependency for the whole
   family. Raising a version is a change to this file first (with the package bump when it is a @starci package),
   then the repositories' own upgrade lane (each sets the exact version and reinstalls; nothing else installs a @starci package). Read on 2026-09-29 from the packages under
   .claude/packages and from the installed node_modules of the six product repositories; where they disagreed the
@@ -10,7 +10,8 @@ purpose: >-
   two, pinned here with a why (2026-10-01: every such conflict but graphql was already pinned). The runtime's example apps
   merged the same way on 2026-10-01: no dependency outside this file was declared at two versions across their sides, so
   every choice is a pin (each side's older @starci pins and graphql moved to the version here). `side` names the side whose code uses
-  the dependency; the app root package.json carries the pins of both.
+  the dependency; the app root package.json declares the direct dependencies and tools its sides need. Package-owned
+  runtime dependencies are declared by their package, not by the app.
 pins:
   # --- @starci packages. Every @starci package is a PUBLISHED npm package (install: registry): a product repository
   # installs the exact pinned version from the npm registry in the root and every workspace package.json, never `file:`.
@@ -22,28 +23,28 @@ pins:
     source: packages/heroicons/package.json
     why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
   '@starci/grammar':
-    version: 0.10.0
+    version: 0.12.0
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.39
+    version: 3.4.41
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.38
+    version: 8.4.40
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/stylelint-canon':
-    version: 2.0.10
+    version: 2.0.11
     group: starci
     install: registry
     side: fe
@@ -62,7 +63,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.3.5
+    version: 2.3.6
     group: starci
     install: registry
     side: be
@@ -76,14 +77,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.31
+    version: 1.7.33
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.31
+    version: 4.7.33
     group: starci
     install: registry
     side: both
@@ -238,6 +239,11 @@ pins:
     group: framework
     side: be
     why: 'the Postgres driver behind TypeORM; the reference app declares ^8.12.0 and resolves 8.23.1.'
+  bullmq:
+    version: 6.3.11
+    group: framework
+    side: be
+    why: 'the queue transport of both editions behind platform/queue (ruling:R212/case-10); starci app add queue|job declares it in a lite app together with its Redis, and both example apps resolve this version.'
   reflect-metadata:
     version: 0.2.2
     group: framework
@@ -305,6 +311,11 @@ pins:
     group: framework
     side: fe
     why: 'the GraphQL client of every front end (fe-stack graphql): auth and no-auth clients with the link chain in modules/api/graphql; version read from the starci-academy package-lock on 2026-10-13.'
+  graphql-ws:
+    version: 6.2.1
+    group: framework
+    side: both
+    why: 'the subscription transport: the front end opens it only in the Apollo clients folder (fe-stack graphql, GraphQLWsLink of @apollo/client/link/subscriptions) and the back end serves it only from platform/realtime; the version resolved by the full-app lockfile on 2026-10-24.'
   '@graphql-codegen/cli':
     version: 7.4.6
     group: tooling
@@ -370,6 +381,16 @@ pins:
     group: ui
     side: fe
     why: 'the base of the one application icon set (fe-stack icons, with @starci/heroicons for the glyphs it lacks); eslint-canon-fe (icon.mjs) admits @heroicons/react/24/outline and /16/solid.'
+  '@dicebear/core':
+    version: 10.4.0
+    group: ui
+    side: fe
+    why: 'runtime dependency of @starci/grammar for its seeded circle avatars; apps use the Avatar seed prop and never declare or import @dicebear/*; pinned with @dicebear/styles.'
+  '@dicebear/styles':
+    version: 10.4.0
+    group: ui
+    side: fe
+    why: 'runtime dependency of @starci/grammar supplying its fixed avatar DNA style; apps use the Avatar seed prop and never declare or import @dicebear/*; pinned with @dicebear/core.'
   'next-themes':
     version: 0.4.6
     group: ui
@@ -481,6 +502,16 @@ pins:
     group: framework
     side: be
     why: 'the Apollo driver of @nestjs/graphql; the full-app resolution on 2026-10-13. Stays on 13.x with @nestjs/graphql (accepted advisory, major deferred to alpha.19).'
+  '@aws-sdk/client-s3':
+    version: 3.1150.0
+    group: framework
+    side: be
+    why: 'the S3 transport of integrations/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces, Supabase Storage); 3.1150.0 is the release of 2026-10-12, chosen over newer ones that had not aged two weeks.'
+  '@aws-sdk/s3-request-presigner':
+    version: 3.1150.0
+    group: framework
+    side: be
+    why: 'signs the presigned PUT and GET of integrations/object-storage locally, the same release as client-s3.'
   '@apollo/server':
     version: 5.5.1
     group: framework
@@ -496,6 +527,31 @@ pins:
     group: framework
     side: be
     why: 'the socket.io platform of @nestjs/websockets; the @nestjs/core pin line.'
+  socket.io:
+    version: 4.8.3
+    group: framework
+    side: be
+    why: 'the socket.io server the IoAdapter of platform/realtime builds (types and the adapter contract); the exact version @nestjs/platform-socket.io 11.2.5 depends on, so the workspace keeps one copy (4.8.4 is the latest on 2026-10-24).'
+  '@socket.io/postgres-adapter':
+    version: 0.5.0
+    group: framework
+    side: be
+    why: 'the stateless socket.io adapter of a back end without Redis that runs several api replicas (LISTEN/NOTIFY, no sticky sessions, websocket only), imported only by platform/realtime (knowledge/patterns/be/realtime.yaml BE-REALTIME-7); the latest registry version on 2026-10-24.'
+  '@socket.io/redis-adapter':
+    version: 8.3.0
+    group: framework
+    side: be
+    why: 'the sharded Redis adapter (createShardedAdapter, Redis 7 or later) of a back end with Redis declared that runs several api replicas, imported only by platform/realtime; the latest registry version on 2026-10-24.'
+  ioredis:
+    version: 5.11.1
+    group: framework
+    side: be
+    why: 'the one Redis client of a back end: the cache, the optional peer bullmq loads for the queue of platform/queue, and the Redis hub and sharded socket.io adapter of platform/realtime (its docs recommend ioredis over redis); the latest 5.x on 2026-10-24, because typeorm 0.3.31 declares ioredis ^5.0.4 as a peer and ioredis 6.0.0 (the latest) does not satisfy it.'
+  '@types/pg':
+    version: 8.23.1
+    group: framework
+    side: be
+    why: 'the types of the pg driver the Postgres hub of platform/realtime opens a LISTEN connection with; the pg pin line, the latest registry version on 2026-10-24.'
   '@as-integrations/express5':
     version: 1.1.2
     group: framework