@sarj/eslint-plugin 16.2.5 → 16.3.0

package/dist/index.js

@@ -298,69 +298,34 @@ function commentLineEnd(sourceText, start) {
 // src/rules/require-explicit-contract-implementation.ts
 var REQUIRE_EXPLICIT_CONTRACT_IMPLEMENTATION_DOCUMENTATION = {
   defaultLevel: "warning",
-  summary: "Require owned classes supplied as typed collaborators to explicitly implement their contract.",
-  rationale: "Structural assignment checks a fake only at the use site; an implements clause keeps its obligations visible at the class declaration.",
-  remediation: "Add an implements clause for the actual injected interface, or inherit an abstract class that declares it.",
+  summary: "Require nominal inheritance when an injected abstract class is rejected by an instanceof guard.",
+  rationale: "A structurally assignable fake can still fail a constructor's nominal runtime guard. Pure structural interfaces do not require an implements clause.",
+  remediation: "Use an implementation inheriting the existing abstract class, or remove the nominal guard if the boundary is intentionally structural.",
   category: "architecture",
   autofix: "none",
   limitations: [
-    "Only class instances whose concrete class and selected constructor parameter resolve through the TypeScript checker are checked.",
-    "Object literals, casts, any, callback-valued data properties, unresolved heritage, dynamic factories, and third-party classes are excluded."
+    "Requires direct construction of both owned consumer and collaborator classes, with a first-statement consumer constructor guard rejecting the exact parameter with if (!(parameter instanceof Contract)) throw.",
+    "The contract must resolve to an abstract class without decorators, unresolved ancestors, or custom computed static members in its resolved hierarchy.",
+    "Structural interfaces, non-rejecting branches, reassignment before the guard, casts, unresolved heritage, dynamic factories, explicit implementation constructors or initializers, modules referencing prototype-mutator members or assigning prototypes, and third-party classes are excluded."
   ],
   examples: [
     {
-      id: "structural-fake-at-injection",
-      title: "A fake reaches a typed collaborator without implementing its interface",
+      id: "runtime-nominal-guard-with-structural-fake",
+      title: "A structurally compatible fake fails the constructor's runtime guard",
       outcome: "match",
-      files: [{ path: "src/service.ts", source: "interface Publisher { publish(): void } class Consumer { constructor(readonly publisher: Publisher) {} } class FakePublisher { publish() {} } new Consumer(new FakePublisher());" }],
+      files: [{ path: "src/service.ts", source: "abstract class Publisher { abstract publish(): void } class Consumer { constructor(readonly publisher: Publisher) { if (!(publisher instanceof Publisher)) throw new TypeError('Nominal publisher required'); } } class FakePublisher { publish() {} } new Consumer(new FakePublisher());" }],
       focusPath: "src/service.ts",
       expectedCount: 1,
       public: true
     },
     {
-      id: "explicit-fake-at-injection",
-      title: "The fake names its actual interface",
+      id: "runtime-nominal-guard-with-inherited-fake",
+      title: "The fake satisfies the existing nominal runtime contract",
       outcome: "no-match",
-      files: [{ path: "src/service.ts", source: "interface Publisher { publish(): void } class Consumer { constructor(readonly publisher: Publisher) {} } class FakePublisher implements Publisher { publish() {} } new Consumer(new FakePublisher());" }],
+      files: [{ path: "src/service.ts", source: "abstract class Publisher { abstract publish(): void } class Consumer { constructor(readonly publisher: Publisher) { if (!(publisher instanceof Publisher)) throw new TypeError('Nominal publisher required'); } } class FakePublisher extends Publisher { publish() {} } new Consumer(new FakePublisher());" }],
       focusPath: "src/service.ts",
       expectedCount: 0,
       public: true
-    },
-    {
-      id: "inherited-implementation",
-      title: "The fake inherits an implementation of the port",
-      outcome: "no-match",
-      files: [{ path: "src/service.ts", source: "interface Publisher { publish(): void } class Consumer { constructor(readonly publisher: Publisher) {} } class BasePublisher implements Publisher { publish() {} } class FakePublisher extends BasePublisher {} new Consumer(new FakePublisher());" }],
-      focusPath: "src/service.ts",
-      expectedCount: 0,
-      public: false
-    },
-    {
-      id: "non-contract-data-argument",
-      title: "A data object is not a service port",
-      outcome: "no-match",
-      files: [{ path: "src/service.ts", source: "interface Options { name: string } class Consumer { constructor(readonly options: Options) {} } class FakeOptions { name = 'test' } new Consumer(new FakeOptions());" }],
-      focusPath: "src/service.ts",
-      expectedCount: 0,
-      public: false
-    },
-    {
-      id: "explicit-cast-origin-unknown",
-      title: "A cast hides the concrete source",
-      outcome: "no-match",
-      files: [{ path: "src/service.ts", source: "interface Publisher { publish(): void } class Consumer { constructor(readonly publisher: Publisher) {} } class FakePublisher { publish() {} } new Consumer(new FakePublisher() as Publisher);" }],
-      focusPath: "src/service.ts",
-      expectedCount: 0,
-      public: false
-    },
-    {
-      id: "unrelated-interface",
-      title: "Implementing another interface does not declare the supplied port",
-      outcome: "match",
-      files: [{ path: "src/service.ts", source: "interface Publisher { publish(): void } interface Other { publish(): void } class Consumer { constructor(readonly publisher: Publisher) {} } class FakePublisher implements Other { publish() {} } new Consumer(new FakePublisher());" }],
-      focusPath: "src/service.ts",
-      expectedCount: 1,
-      public: false
     }
   ]
 };
@@ -371,7 +336,7 @@ function behavioralContract(checker, type) {
     return behavioralContract(checker, substantive[0]);
   }
   if ((type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0) return null;
-  const declaration = type.getSymbol()?.declarations?.find((item) => ts.isInterfaceDeclaration(item) || ts.isTypeAliasDeclaration(item) || ts.isClassDeclaration(item) && item.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AbstractKeyword));
+  const declaration = type.getSymbol()?.declarations?.find((item) => ts.isClassDeclaration(item) && item.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AbstractKeyword));
   if (declaration === void 0) return null;
   return checker.getPropertiesOfType(type).some((property) => {
     if (!property.declarations?.some((member) => ts.isMethodSignature(member) || ts.isMethodDeclaration(member))) return false;
@@ -379,43 +344,86 @@ function behavioralContract(checker, type) {
     return propertyType.getCallSignatures().length > 0;
   }) ? type : null;
 }
-function ownedClass(type) {
+function ownedClass(checker, expression) {
+  if (!ts.isNewExpression(expression)) return null;
+  const type = checker.getTypeAtLocation(expression);
   if ((type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0) return null;
   const declaration = type.getSymbol()?.declarations?.find(ts.isClassDeclaration);
-  if (declaration === void 0 || declaration.getSourceFile().isDeclarationFile || /(?:^|[/\\])(?:node_modules|vendor|generated)(?:[/\\])/u.test(declaration.getSourceFile().fileName)) return null;
+  const constructed = canonicalSymbol(checker, expression.expression)?.declarations?.find(ts.isClassDeclaration);
+  if (declaration === void 0 || declaration !== constructed || declaration.getSourceFile().isDeclarationFile || /(?:^|[/\\])(?:node_modules|vendor|generated)(?:[/\\])/u.test(declaration.getSourceFile().fileName)) return null;
   return declaration;
 }
-function explicitlyImplements(checker, declaration, target, seen) {
+function memberName(node) {
+  if (ts.isPropertyAccessExpression(node)) return node.name.text;
+  if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) return node.argumentExpression.text;
+  return null;
+}
+function hasPrototypeMutation(source) {
+  function visit(node) {
+    const member = memberName(node);
+    if (member === "setPrototypeOf" || member === "__proto__" || member === "hasInstance") return true;
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && node.operatorToken.kind <= ts.SyntaxKind.LastAssignment && memberName(node.left) === "prototype") return true;
+    return ts.forEachChild(node, visit);
+  }
+  return visit(source) === true;
+}
+function nominallyInherits(checker, declaration, target, seen) {
+  if (ts.canHaveDecorators(declaration) && ts.getDecorators(declaration)?.length) return null;
+  if (hasPrototypeMutation(declaration.getSourceFile()) || declaration.members.some((member) => ts.isConstructorDeclaration(member) || ts.isPropertyDeclaration(member) && member.initializer !== void 0)) return null;
   const symbol = declaration.name === void 0 ? void 0 : canonicalSymbol(checker, declaration.name);
   if (symbol !== void 0) {
     if (seen.has(symbol)) return null;
     seen.add(symbol);
   }
-  let unknown = false;
-  for (const clause of declaration.heritageClauses ?? []) {
-    for (const parent of clause.types) {
-      const parentSymbol = canonicalSymbol(checker, parent.expression);
-      if (parentSymbol === void 0) {
-        unknown = true;
-        continue;
-      }
-      if (parentSymbol === target) return true;
-      const inherited = parentSymbol.declarations?.find((item) => ts.isClassDeclaration(item) || ts.isInterfaceDeclaration(item));
-      if (inherited === void 0) {
-        unknown = true;
-        continue;
-      }
-      const relationship = explicitlyImplements(checker, inherited, target, new Set(seen));
-      if (relationship === true) return true;
-      unknown ||= relationship === null;
-    }
-  }
-  return unknown ? null : false;
+  const parents = declaration.heritageClauses?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword)?.types;
+  if (parents === void 0) return false;
+  if (parents.length !== 1) return null;
+  const parentSymbol = canonicalSymbol(checker, parents[0].expression);
+  if (parentSymbol === void 0) return null;
+  if (parentSymbol === target) return true;
+  const inherited = parentSymbol.declarations?.find(ts.isClassDeclaration);
+  return inherited === void 0 ? null : nominallyInherits(checker, inherited, target, new Set(seen));
 }
 function canonicalSymbol(checker, node) {
   const symbol = checker.getSymbolAtLocation(node);
   return symbol === void 0 ? void 0 : (symbol.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(symbol) : symbol;
 }
+function hasNominalRejectionGuard(checker, signature, parameter, contract) {
+  const declaration = signature.getDeclaration();
+  if (declaration === void 0 || !ts.isConstructorDeclaration(declaration)) return false;
+  if (ts.canHaveDecorators(declaration.parent) && ts.getDecorators(declaration.parent)?.length) return false;
+  if (hasPrototypeMutation(declaration.getSourceFile())) return false;
+  const first = declaration.body?.statements[0];
+  if (first === void 0 || !ts.isIfStatement(first) || !alwaysThrows(first.thenStatement)) return false;
+  const condition = unparenthesized(first.expression);
+  if (!ts.isPrefixUnaryExpression(condition) || condition.operator !== ts.SyntaxKind.ExclamationToken) return false;
+  const comparison = unparenthesized(condition.operand);
+  if (!ts.isBinaryExpression(comparison) || comparison.operatorToken.kind !== ts.SyntaxKind.InstanceOfKeyword) return false;
+  if (canonicalSymbol(checker, comparison.left) !== parameter || canonicalSymbol(checker, comparison.right) !== contract) return false;
+  const target = contract.declarations?.find(ts.isClassDeclaration);
+  return target !== void 0 && hasOrdinaryInstanceCheck(checker, target, /* @__PURE__ */ new Set());
+}
+function unparenthesized(expression) {
+  let current = expression;
+  while (ts.isParenthesizedExpression(current)) current = current.expression;
+  return current;
+}
+function alwaysThrows(statement) {
+  return ts.isThrowStatement(statement) || ts.isBlock(statement) && statement.statements.length === 1 && ts.isThrowStatement(statement.statements[0]);
+}
+function hasOrdinaryInstanceCheck(checker, declaration, seen) {
+  if (seen.has(declaration) || ts.getDecorators(declaration)?.length || hasPrototypeMutation(declaration.getSourceFile())) return false;
+  seen.add(declaration);
+  if (declaration.members.some((member) => member.name !== void 0 && ts.isComputedPropertyName(member.name) && ts.canHaveModifiers(member) && ts.getModifiers(member)?.some((modifier) => modifier.kind === ts.SyntaxKind.StaticKeyword))) return false;
+  for (const clause of declaration.heritageClauses ?? []) {
+    if (clause.token !== ts.SyntaxKind.ExtendsKeyword) continue;
+    for (const parent of clause.types) {
+      const ancestor = canonicalSymbol(checker, parent.expression)?.declarations?.find(ts.isClassDeclaration);
+      if (ancestor === void 0 || !hasOrdinaryInstanceCheck(checker, ancestor, seen)) return false;
+    }
+  }
+  return true;
+}
 var require_explicit_contract_implementation_default = createRule({
   name: "require-explicit-contract-implementation",
   documentation: REQUIRE_EXPLICIT_CONTRACT_IMPLEMENTATION_DOCUMENTATION,
@@ -424,7 +432,7 @@ var require_explicit_contract_implementation_default = createRule({
     docs: { description: REQUIRE_EXPLICIT_CONTRACT_IMPLEMENTATION_DOCUMENTATION.summary },
     schema: [],
     messages: {
-      declareActualContract: "`{{implementation}}` is supplied as `{{contract}}` without explicitly implementing that contract."
+      declareActualContract: "`{{implementation}}` structurally matches `{{contract}}` but fails the rejecting instanceof guard; use nominal inheritance or make the boundary structural."
     }
   },
   defaultOptions: [],
@@ -435,25 +443,27 @@ var require_explicit_contract_implementation_default = createRule({
     const checker = services.program.getTypeChecker();
     function inspect(node) {
       const tsNode = services.esTreeNodeToTSNodeMap.get(node);
-      if (!ts.isCallExpression(tsNode) && !ts.isNewExpression(tsNode)) return;
+      if (!ts.isNewExpression(tsNode)) return;
+      const consumer = canonicalSymbol(checker, tsNode.expression)?.declarations?.find(ts.isClassDeclaration);
+      if (consumer === void 0) return;
       const signature = checker.getResolvedSignature(tsNode);
-      if (signature === void 0) return;
+      if (signature === void 0 || signature.getDeclaration()?.parent !== consumer) return;
       const parameters = signature.getParameters();
       for (const [index, argument] of node.arguments.entries()) {
-        if (argument.type === AST_NODE_TYPES.SpreadElement || argument.type === AST_NODE_TYPES.TSAsExpression || argument.type === AST_NODE_TYPES.TSTypeAssertion || argument.type === AST_NODE_TYPES.TSSatisfiesExpression) continue;
+        if (argument.type !== AST_NODE_TYPES.NewExpression) continue;
         const parameter = parameters[index];
         if (parameter === void 0) continue;
         const parameterType = checker.getTypeOfSymbolAtLocation(parameter, tsNode);
         const contractType = behavioralContract(checker, parameterType);
         if (contractType === null) continue;
         const contractSymbol = contractType.getSymbol();
-        if (contractSymbol === void 0) continue;
+        if (contractSymbol === void 0 || !hasNominalRejectionGuard(checker, signature, parameter, contractSymbol)) continue;
         const tsArgument = services.esTreeNodeToTSNodeMap.get(argument);
         const actualType = checker.getTypeAtLocation(tsArgument);
         if (!checker.isTypeAssignableTo(actualType, contractType)) continue;
-        const implementation = ownedClass(actualType);
+        const implementation = ownedClass(checker, tsArgument);
         if (implementation === null) continue;
-        const relationship = explicitlyImplements(checker, implementation, contractSymbol, /* @__PURE__ */ new Set());
+        const relationship = nominallyInherits(checker, implementation, contractSymbol, /* @__PURE__ */ new Set());
         if (relationship !== false) continue;
         context.report({
           node: argument,
@@ -463,7 +473,6 @@ var require_explicit_contract_implementation_default = createRule({
       }
     }
     return {
-      CallExpression: inspect,
       NewExpression: inspect
     };
   }
@@ -581,7 +590,7 @@ var propertySignatureTypes = (members) => {
 };
 var fileTypeIndex = (program) => {
   const objects = /* @__PURE__ */ new Map();
-  const functionAliases = /* @__PURE__ */ new Set();
+  const functionAliases = localFunctionAliases(program);
   function collectDeclaredType(statement) {
     const declaration = statement.type === AST_NODE_TYPES2.ExportNamedDeclaration ? statement.declaration : statement;
     if (declaration?.type === AST_NODE_TYPES2.TSInterfaceDeclaration) {
@@ -590,10 +599,6 @@ var fileTypeIndex = (program) => {
     }
     if (declaration?.type !== AST_NODE_TYPES2.TSTypeAliasDeclaration) return;
     const aliased = declaration.typeAnnotation;
-    if (aliased.type === AST_NODE_TYPES2.TSFunctionType || aliased.type === AST_NODE_TYPES2.TSConstructorType) {
-      functionAliases.add(declaration.id.name);
-      return;
-    }
     const literals = aliased.type === AST_NODE_TYPES2.TSTypeLiteral ? [aliased] : aliased.type === AST_NODE_TYPES2.TSIntersectionType ? aliased.types.filter((part) => part.type === AST_NODE_TYPES2.TSTypeLiteral) : [];
     if (literals.length === 0) return;
     const merged = /* @__PURE__ */ new Map();
@@ -609,6 +614,28 @@ var fileTypeIndex = (program) => {
   }
   return { objects, functionAliases };
 };
+function localFunctionAliases(program) {
+  const names = /* @__PURE__ */ new Set();
+  const parents = /* @__PURE__ */ new Map();
+  for (const statement of program.body) {
+    const declaration = statement.type === AST_NODE_TYPES2.ExportNamedDeclaration ? statement.declaration : statement;
+    if (declaration?.type !== AST_NODE_TYPES2.TSTypeAliasDeclaration) continue;
+    const annotation = declaration.typeAnnotation;
+    if (annotation.type === AST_NODE_TYPES2.TSFunctionType || annotation.type === AST_NODE_TYPES2.TSConstructorType) names.add(declaration.id.name);
+    if (annotation.type === AST_NODE_TYPES2.TSTypeReference && annotation.typeName.type === AST_NODE_TYPES2.Identifier) parents.set(declaration.id.name, annotation.typeName.name);
+  }
+  for (let pass = 0; pass < parents.size; pass += 1) {
+    let changed = false;
+    for (const [name, parent] of parents) {
+      if (names.has(parent) && !names.has(name)) {
+        names.add(name);
+        changed = true;
+      }
+    }
+    if (!changed) break;
+  }
+  return names;
+}
 var typeParameterNames = (...declarations) => {
   const names = /* @__PURE__ */ new Set();
   for (const declaration of declarations) {
@@ -620,12 +647,15 @@ var readConstructor = (ctor, declared, typeParameters) => {
   const body2 = ctor.value.body;
   const storedFieldsFrom = /* @__PURE__ */ new Map();
   const storedMemberFieldsFrom = /* @__PURE__ */ new Map();
+  const constructedFieldNames = /* @__PURE__ */ new Set();
+  const localBindings2 = /* @__PURE__ */ new Set();
   let constructedFields = 0;
   if (body2 !== null && body2 !== void 0) scanStoredFields(body2);
   function scanStoredFields(body3) {
     const pending = [...body3.body];
     function recordStoredField(current) {
       if (current.type === AST_NODE_TYPES2.ArrowFunctionExpression || current.type === AST_NODE_TYPES2.FunctionExpression || current.type === AST_NODE_TYPES2.FunctionDeclaration || current.type === AST_NODE_TYPES2.ClassExpression || current.type === AST_NODE_TYPES2.ClassDeclaration) return;
+      if (current.type === AST_NODE_TYPES2.VariableDeclarator && current.id.type === AST_NODE_TYPES2.Identifier) localBindings2.add(current.id.name);
       const expression = current.type === AST_NODE_TYPES2.ExpressionStatement ? current.expression : null;
       const storedField = expression?.type === AST_NODE_TYPES2.AssignmentExpression && expression.left.type === AST_NODE_TYPES2.MemberExpression && expression.left.object.type === AST_NODE_TYPES2.ThisExpression ? staticMemberName(expression.left) : null;
       if (expression?.type !== AST_NODE_TYPES2.AssignmentExpression || !STORAGE_ASSIGNMENT_OPERATORS.has(expression.operator) || expression.left.type !== AST_NODE_TYPES2.MemberExpression || expression.left.object.type !== AST_NODE_TYPES2.ThisExpression || storedField === null) {
@@ -636,6 +666,7 @@ var readConstructor = (ctor, declared, typeParameters) => {
       while (source.type === AST_NODE_TYPES2.TSNonNullExpression || source.type === AST_NODE_TYPES2.TSAsExpression || source.type === AST_NODE_TYPES2.TSSatisfiesExpression || source.type === AST_NODE_TYPES2.TSTypeAssertion) source = source.expression;
       if (source.type === AST_NODE_TYPES2.NewExpression) {
         constructedFields += 1;
+        constructedFieldNames.add(storedField);
       } else if (source.type === AST_NODE_TYPES2.Identifier) {
         const fields = storedFieldsFrom.get(source.name) ?? /* @__PURE__ */ new Set();
         fields.add(storedField);
@@ -668,15 +699,19 @@ var readConstructor = (ctor, declared, typeParameters) => {
   const collaborators = [];
   function collectCollaborators(parameter) {
     for (const reference of parameterCollaborators(parameter, declared, storedMemberFieldsFrom)) {
-      const fields = parameter.type === AST_NODE_TYPES2.TSParameterProperty ? [reference.name] : reference.fields.length > 0 ? reference.fields : [...storedFieldsFrom.get(reference.name) ?? []];
-      if (fields.length === 0) continue;
+      if (localBindings2.has(reference.name)) continue;
+      let fields = reference.fields;
+      if (parameter.type === AST_NODE_TYPES2.TSParameterProperty) fields = [reference.name];
+      else if (fields.length === 0) fields = [...storedFieldsFrom.get(reference.name) ?? []];
+      const injectedFields = fields.filter((field) => !constructedFieldNames.has(field));
+      if (injectedFields.length === 0) continue;
       if (CONFIGISH_TYPE_RE.test(reference.typeName)) continue;
       if (CONFIGISH_NAME_RE.test(reference.name)) continue;
       if (typeParameters.has(reference.typeName)) continue;
       if (BUILTIN_CONTAINER_TYPE_RE.test(reference.typeName)) continue;
       if (VALUE_TYPE_RE.test(reference.typeName)) continue;
       if (declared().functionAliases.has(reference.typeName)) continue;
-      collaborators.push({ ...reference, fields });
+      collaborators.push({ ...reference, fields: injectedFields });
     }
   }
   for (const parameter of ctor.value.params) {
@@ -895,11 +930,7 @@ function declaredMemberName(member) {
 function localInterfaceSurfaces(program) {
   const interfaces = /* @__PURE__ */ new Map();
   const parents = /* @__PURE__ */ new Map();
-  const functionAliases = /* @__PURE__ */ new Set();
-  for (const statement of program.body) {
-    const declaration = statement.type === AST_NODE_TYPES2.ExportNamedDeclaration ? statement.declaration : statement;
-    if (declaration?.type === AST_NODE_TYPES2.TSTypeAliasDeclaration && (declaration.typeAnnotation.type === AST_NODE_TYPES2.TSFunctionType || declaration.typeAnnotation.type === AST_NODE_TYPES2.TSConstructorType)) functionAliases.add(declaration.id.name);
-  }
+  const functionAliases = localFunctionAliases(program);
   function collectInterfaceSurface(statement) {
     const declaration = statement.type === AST_NODE_TYPES2.ExportNamedDeclaration ? statement.declaration : statement;
     if (declaration?.type === AST_NODE_TYPES2.TSTypeAliasDeclaration) {
@@ -911,6 +942,10 @@ function localInterfaceSurfaces(program) {
           inherited.push(part.typeName.name);
           continue;
         }
+        if (part.type === AST_NODE_TYPES2.TSTypeReference) {
+          inherited.push("*");
+          continue;
+        }
         if (part.type !== AST_NODE_TYPES2.TSTypeLiteral) continue;
         addCallableMembers(part.members, callables2);
       }
@@ -1074,30 +1109,18 @@ function createServiceOperationResolver(program) {
     if (retained.size === 0) return [];
     const callers = /* @__PURE__ */ new Map();
     const active = /* @__PURE__ */ new Set();
-    for (const member of node.body.body) {
-      if (member.type !== AST_NODE_TYPES2.MethodDefinition || member.kind !== "method" || member.value.body === null) continue;
-      const name = declaredMemberName(member);
-      if (name === null) continue;
-      const visit = (current) => {
-        if (current.type === AST_NODE_TYPES2.FunctionDeclaration || current.type === AST_NODE_TYPES2.FunctionExpression || current.type === AST_NODE_TYPES2.ClassDeclaration || current.type === AST_NODE_TYPES2.ClassExpression) return;
-        if (current.type === AST_NODE_TYPES2.IfStatement && current.test.type === AST_NODE_TYPES2.Literal && typeof current.test.value === "boolean") {
-          visit(current.test.value ? current.consequent : current.alternate ?? current.test);
-          return;
-        }
-        if (current.type === AST_NODE_TYPES2.CallExpression) {
-          if (retained.has(invokedInstanceField(current) ?? "")) active.add(name);
-          if (current.callee.type === AST_NODE_TYPES2.MemberExpression && current.callee.object.type === AST_NODE_TYPES2.ThisExpression) {
-            const callee = staticMemberName(current.callee);
-            if (callee !== null) {
-              const linked = callers.get(callee) ?? /* @__PURE__ */ new Set();
-              linked.add(name);
-              callers.set(callee, linked);
-            }
+    for (const [name, body2] of serviceOperationBodies(node)) {
+      forEachServiceCall(body2, (call) => {
+        if (retained.has(invokedInstanceField(call) ?? "")) active.add(name);
+        if (call.callee.type === AST_NODE_TYPES2.MemberExpression && call.callee.object.type === AST_NODE_TYPES2.ThisExpression) {
+          const callee = staticMemberName(call.callee);
+          if (callee !== null) {
+            const linked = callers.get(callee) ?? /* @__PURE__ */ new Set();
+            linked.add(name);
+            callers.set(callee, linked);
           }
         }
-        forEachOwnAstChild(current, visit);
-      };
-      for (const statement of member.value.body.body) visit(statement);
+      });
     }
     const pending = [...active];
     while (pending.length > 0) {
@@ -1112,38 +1135,127 @@ function createServiceOperationResolver(program) {
     return publicMethodNames(node.body, declared().functionAliases).filter((name) => active.has(name));
   };
 }
+function serviceOperationBodies(node) {
+  const bodies = /* @__PURE__ */ new Map();
+  for (const member of node.body.body) {
+    if (member.type !== AST_NODE_TYPES2.MethodDefinition && member.type !== AST_NODE_TYPES2.PropertyDefinition) continue;
+    if (member.static || member.decorators.length > 0) continue;
+    if (member.type === AST_NODE_TYPES2.MethodDefinition && member.kind !== "method") continue;
+    if (member.value?.type !== AST_NODE_TYPES2.FunctionExpression && member.value?.type !== AST_NODE_TYPES2.ArrowFunctionExpression) continue;
+    const name = declaredMemberName(member);
+    if (name !== null && member.value.body !== null) bodies.set(name, member.value.body);
+  }
+  return bodies;
+}
+function forEachServiceCall(node, onCall) {
+  if (node.type === AST_NODE_TYPES2.FunctionDeclaration || node.type === AST_NODE_TYPES2.FunctionExpression || node.type === AST_NODE_TYPES2.ArrowFunctionExpression || node.type === AST_NODE_TYPES2.ClassDeclaration || node.type === AST_NODE_TYPES2.ClassExpression) return;
+  if (node.type === AST_NODE_TYPES2.BlockStatement) {
+    for (const statement of node.body) {
+      forEachServiceCall(statement, onCall);
+      if (terminatesOperation(statement)) break;
+    }
+    return;
+  }
+  const branch = literalExecutionBranch(node);
+  if (branch !== null) {
+    forEachServiceCall(branch, onCall);
+    return;
+  }
+  if (node.type === AST_NODE_TYPES2.CallExpression) onCall(node);
+  forEachOwnAstChild(node, (child) => {
+    forEachServiceCall(child, onCall);
+  });
+}
+function literalExecutionBranch(node) {
+  if (node.type === AST_NODE_TYPES2.WhileStatement && node.test.type === AST_NODE_TYPES2.Literal && node.test.value === false) return node.test;
+  if ((node.type === AST_NODE_TYPES2.IfStatement || node.type === AST_NODE_TYPES2.ConditionalExpression) && node.test.type === AST_NODE_TYPES2.Literal && typeof node.test.value === "boolean") {
+    return node.test.value ? node.consequent : node.alternate ?? node.test;
+  }
+  if (node.type !== AST_NODE_TYPES2.LogicalExpression || node.left.type !== AST_NODE_TYPES2.Literal || typeof node.left.value !== "boolean") return null;
+  if (node.operator === "&&") return node.left.value ? node.right : node.left;
+  if (node.operator === "||") return node.left.value ? node.left : node.right;
+  return node.left;
+}
+function terminatesOperation(node) {
+  if (node.type === AST_NODE_TYPES2.ReturnStatement || node.type === AST_NODE_TYPES2.ThrowStatement) return true;
+  if (node.type === AST_NODE_TYPES2.BlockStatement) return node.body.some(terminatesOperation);
+  if (node.type !== AST_NODE_TYPES2.IfStatement) return false;
+  const branch = literalExecutionBranch(node);
+  if (branch !== null) return terminatesOperation(branch);
+  return node.alternate !== null && terminatesOperation(node.consequent) && terminatesOperation(node.alternate);
+}
 function hasDeclaredServiceContract(node, operations, program) {
-  const classes = localClassAbstractness(program);
   const interfaces = localInterfaceSurfaces(program);
-  if (node.implements.length > 0) return implementedSurfaceCovers(node, operations, classes, interfaces);
-  if (node.superClass === null) return false;
-  if (node.superClass.type !== AST_NODE_TYPES2.Identifier) return null;
-  const baseName = node.superClass.name;
-  const isAbstract = classes.get(baseName);
-  if (isAbstract === void 0) return null;
-  if (!isAbstract) return false;
-  const base = program.body.flatMap((statement) => {
-    const declaration = statement.type === AST_NODE_TYPES2.ExportNamedDeclaration ? statement.declaration : statement;
-    return declaration?.type === AST_NODE_TYPES2.ClassDeclaration && declaration.id?.name === baseName ? [declaration] : [];
-  })[0];
-  if (base === void 0) return null;
-  const abstractOperations = new Set(base.body.body.flatMap(
-    (member) => member.type === AST_NODE_TYPES2.TSAbstractMethodDefinition && member.accessibility !== "private" && member.accessibility !== "protected" && !member.static ? [declaredMemberName(member)] : []
-  ));
-  return operations.every((name) => abstractOperations.has(name) || publicMethodNames(base.body, /* @__PURE__ */ new Set()).includes(name));
+  const classes = localClassDeclarations(program);
+  const functionAliases = fileTypeIndex(program).functionAliases;
+  const covered2 = /* @__PURE__ */ new Set();
+  const pending = [node];
+  const seen = /* @__PURE__ */ new Set();
+  function addImplementedContracts(current) {
+    for (const implementation of current.implements) {
+      if (implementation.expression.type !== AST_NODE_TYPES2.Identifier) return false;
+      const name = implementation.expression.name;
+      const surface = interfaces.get(name);
+      const base = classes.get(name);
+      if (surface === void 0 && base === void 0) return false;
+      if (surface?.has("*")) return false;
+      for (const method of surface ?? []) covered2.add(method);
+      if (base?.abstract) pending.push(base);
+    }
+    return true;
+  }
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (current === void 0 || seen.has(current)) continue;
+    seen.add(current);
+    if (current.decorators.length > 0) return null;
+    if (current.abstract) {
+      for (const method of abstractContractOperations(current, functionAliases)) covered2.add(method);
+    }
+    if (!addImplementedContracts(current)) return null;
+    if (current.superClass === null) continue;
+    if (current.superClass.type !== AST_NODE_TYPES2.Identifier) return null;
+    const base = classes.get(current.superClass.name);
+    if (base === void 0) return null;
+    pending.push(base);
+  }
+  return operations.every((name) => covered2.has(name));
+}
+function localClassDeclarations(program) {
+  const classes = /* @__PURE__ */ new Map();
+  for (const statement of program.body) {
+    const declaration = statement.type === AST_NODE_TYPES2.ExportNamedDeclaration || statement.type === AST_NODE_TYPES2.ExportDefaultDeclaration ? statement.declaration : statement;
+    if (declaration?.type === AST_NODE_TYPES2.ClassDeclaration && declaration.id !== null) classes.set(declaration.id.name, declaration);
+  }
+  return classes;
+}
+function abstractContractOperations(node, functionAliases) {
+  const methods = new Set(publicMethodNames(node.body, functionAliases));
+  for (const member of node.body.body) {
+    if (member.type !== AST_NODE_TYPES2.TSAbstractMethodDefinition && member.type !== AST_NODE_TYPES2.TSAbstractPropertyDefinition) continue;
+    if (member.static || member.accessibility === "private" || member.accessibility === "protected") continue;
+    if (member.type === AST_NODE_TYPES2.TSAbstractPropertyDefinition) {
+      const annotation = member.typeAnnotation?.typeAnnotation;
+      if (annotation?.type !== AST_NODE_TYPES2.TSFunctionType && !(annotation?.type === AST_NODE_TYPES2.TSTypeReference && annotation.typeName.type === AST_NODE_TYPES2.Identifier && functionAliases.has(annotation.typeName.name))) continue;
+    }
+    const name = declaredMemberName(member);
+    if (name !== null) methods.add(name);
+  }
+  return methods;
 }
 
 // src/rules/require-explicit-service-contract.ts
 var REQUIRE_EXPLICIT_SERVICE_CONTRACT_DOCUMENTATION = {
   defaultLevel: "warning",
   summary: "Require explicit contracts for classes that invoke retained collaborators.",
-  rationale: "A one-operation service can orchestrate a collaborator without declaring the contract that its callers and fakes must implement.",
-  remediation: "Export a focused interface or abstract class and explicitly implement or extend it.",
+  rationale: "A one-operation service can orchestrate a collaborator without declaring the contract that callers consume and implementations and fakes satisfy.",
+  remediation: "Explicitly implement a focused interface or extend an abstract class covering the service operations. Export the contract only when its consumers need it.",
   category: "architecture",
   autofix: "none",
   limitations: [
     "The rule checks service, store, and provider class declarations whose constructor stores a typed behavioral collaborator and whose public method reaches that collaborator.",
-    "Imported or dynamic base classes with unavailable declarations are unresolved and do not produce a finding.",
+    "Existing local interfaces, type aliases, and inherited contracts can cover the operations; the compiler owns signature compatibility.",
+    "Imported or dynamic base classes with unavailable declarations and decorated classes or operations are unresolved and do not produce a finding.",
     "Generated files and JavaScript without implements syntax are excluded."
   ],
   examples: [
@@ -1165,7 +1277,7 @@ var REQUIRE_EXPLICIT_SERVICE_CONTRACT_DOCUMENTATION = {
       outcome: "no-match",
       files: [{
         path: "src/service.ts",
-        source: "export interface Runner { run(): void } class OrchestratorService implements Runner { constructor(private readonly worker: Worker) {} run(): void { this.worker.run(); } }"
+        source: "interface Runner { run(): void } class OrchestratorService implements Runner { constructor(private readonly worker: Worker) {} run(): void { this.worker.run(); } }"
       }],
       focusPath: "src/service.ts",
       expectedCount: 0,
@@ -1181,7 +1293,7 @@ var require_explicit_service_contract_default = createRule({
     docs: { description: REQUIRE_EXPLICIT_SERVICE_CONTRACT_DOCUMENTATION.summary },
     schema: [],
     messages: {
-      requireExplicitServiceContract: "`{{name}}` invokes a retained collaborator from {{operations}} without explicitly implementing a public contract for those operations."
+      requireExplicitServiceContract: "`{{name}}` invokes a retained collaborator from {{operations}} without a declared interface or abstract-class contract covering those operations. Implement a focused contract; it can remain local."
     }
   },
   defaultOptions: [],
@@ -1192,7 +1304,7 @@ var require_explicit_service_contract_default = createRule({
     const isExportedServiceClass = createExportedServiceClassResolver(program);
     return {
       ClassDeclaration(node) {
-        if (node.id === null || node.abstract || !isServiceRole(node.id.name, context.filename)) return;
+        if (node.id === null || node.abstract || node.decorators.length > 0 || !isServiceRole(node.id.name, context.filename)) return;
         if (isExportedServiceClass(node) && !isTestFile(context.filename) && !isStoryFile(context.filename) && !isScriptFile(context.filename)) return;
         const operations = operationsFor(node);
         if (operations.length === 0 || hasDeclaredServiceContract(node, operations, program) !== false) return;
@@ -7031,7 +7143,7 @@ var RESHAPING_METHODS = /* @__PURE__ */ new Set([
 function importedName2(specifier) {
   return specifier.imported.type === AST_NODE_TYPES34.Identifier ? specifier.imported.name : typeof specifier.imported.value === "string" ? specifier.imported.value : null;
 }
-function memberName(node) {
+function memberName2(node) {
   if (!node.computed && node.property.type === AST_NODE_TYPES34.Identifier) {
     return node.property.name;
   }
@@ -7116,7 +7228,7 @@ var no_impossible_zod_literal_bounds_default = createRule({
         if (callee.type !== AST_NODE_TYPES34.MemberExpression || callee.object.type !== AST_NODE_TYPES34.CallExpression) {
           return null;
         }
-        const method = memberName(callee);
+        const method = memberName2(callee);
         if (method === null) return null;
         calls.push({ method, node: current });
         current = callee.object;
@@ -7130,7 +7242,7 @@ var no_impossible_zod_literal_bounds_default = createRule({
       if (callee.type !== AST_NODE_TYPES34.MemberExpression || callee.object.type !== AST_NODE_TYPES34.Identifier || !namespaces.has(callee.object.name) || !resolvesToTrackedImport(callee.object)) {
         return null;
       }
-      const name = memberName(callee);
+      const name = memberName2(callee);
       return name !== null && KINDS.has(name) ? name : null;
     }
     function isInsideReshapingCall(node) {
@@ -7139,7 +7251,7 @@ var no_impossible_zod_literal_bounds_default = createRule({
       while (parent !== void 0 && parent.type !== AST_NODE_TYPES34.Program) {
         if (parent.type === AST_NODE_TYPES34.CallExpression) {
           const callee = parent.callee;
-          if (callee.type === AST_NODE_TYPES34.MemberExpression && RESHAPING_METHODS.has(memberName(callee) ?? "") && (callee.object.type === AST_NODE_TYPES34.CallExpression || callee.object.type === AST_NODE_TYPES34.Identifier && namespaces.has(callee.object.name) && resolvesToTrackedImport(callee.object))) {
+          if (callee.type === AST_NODE_TYPES34.MemberExpression && RESHAPING_METHODS.has(memberName2(callee) ?? "") && (callee.object.type === AST_NODE_TYPES34.CallExpression || callee.object.type === AST_NODE_TYPES34.Identifier && namespaces.has(callee.object.name) && resolvesToTrackedImport(callee.object))) {
             return true;
           }
           if (callee.type === AST_NODE_TYPES34.Identifier && preprocessors.has(callee.name) && resolvesToTrackedImport(callee)) {
@@ -7405,7 +7517,7 @@ var NO_REDUNDANT_OPTIONAL_ARRAY_DEFAULT_DOCUMENTATION = {
 function importedName3(specifier) {
   return specifier.imported.type === AST_NODE_TYPES35.Identifier ? specifier.imported.name : typeof specifier.imported.value === "string" ? specifier.imported.value : null;
 }
-function memberName2(node) {
+function memberName3(node) {
   if (!node.computed && node.property.type === AST_NODE_TYPES35.Identifier) {
     return node.property.name;
   }
@@ -7457,7 +7569,7 @@ var no_redundant_optional_array_default_default = createRule({
         return arrayConstructors.has(callee.name) && resolvesToTrackedImport(callee);
       }
       if (callee.type !== AST_NODE_TYPES35.MemberExpression) return false;
-      const method = memberName2(callee);
+      const method = memberName3(callee);
       if (method === "array" && (callee.object.type === AST_NODE_TYPES35.Identifier ? namespaces.has(callee.object.name) && resolvesToTrackedImport(callee.object) : isZodSchemaExpression(callee.object))) {
         return true;
       }
@@ -7498,12 +7610,12 @@ var no_redundant_optional_array_default_default = createRule({
       },
       CallExpression(node) {
         const defaultCallee = node.callee;
-        if (defaultCallee.type !== AST_NODE_TYPES35.MemberExpression || memberName2(defaultCallee) !== "default" || defaultCallee.object.type !== AST_NODE_TYPES35.CallExpression) {
+        if (defaultCallee.type !== AST_NODE_TYPES35.MemberExpression || memberName3(defaultCallee) !== "default" || defaultCallee.object.type !== AST_NODE_TYPES35.CallExpression) {
           return;
         }
         const optionalCall = defaultCallee.object;
         const optionalCallee = optionalCall.callee;
-        if (optionalCallee.type !== AST_NODE_TYPES35.MemberExpression || memberName2(optionalCallee) !== "optional" || optionalCall.arguments.length !== 0 || !isArraySchemaExpression(optionalCallee.object) || sourceCode.getCommentsInside(optionalCall).length > 0) {
+        if (optionalCallee.type !== AST_NODE_TYPES35.MemberExpression || memberName3(optionalCallee) !== "optional" || optionalCall.arguments.length !== 0 || !isArraySchemaExpression(optionalCallee.object) || sourceCode.getCommentsInside(optionalCall).length > 0) {
           return;
         }
         context.report({
@@ -7527,12 +7639,12 @@ import * as ts8 from "typescript";
 import {
   AST_NODE_TYPES as AST_NODE_TYPES36
 } from "@typescript-eslint/utils";
-function memberName3(member) {
+function memberName4(member) {
   return !member.computed && member.key.type === AST_NODE_TYPES36.Identifier ? member.key.name : null;
 }
 function convertibleMemberName(member) {
   if (member.type !== AST_NODE_TYPES36.MethodDefinition && member.type !== AST_NODE_TYPES36.PropertyDefinition && member.type !== AST_NODE_TYPES36.AccessorProperty) return null;
-  return memberName3(member);
+  return memberName4(member);
 }
 
 // src/rules/interface-contract-members-private.ts
@@ -8134,7 +8246,7 @@ var LOWER_CAMEL_CASE_RE = /^[a-z][A-Za-z0-9]*$/;
 function propertyName2(node) {
   return node.type === AST_NODE_TYPES40.Identifier ? node.name : null;
 }
-function memberName4(node) {
+function memberName5(node) {
   let current = node;
   while (current.type === AST_NODE_TYPES40.TSAsExpression || current.type === AST_NODE_TYPES40.TSNonNullExpression || current.type === AST_NODE_TYPES40.TSTypeAssertion) {
     current = current.expression;
@@ -8198,7 +8310,7 @@ var no_bespoke_api_case_conversion_default = createRule({
       Property(node) {
         if (node.computed || node.method || node.shorthand) return;
         const key = propertyName2(node.key);
-        const value = memberName4(node.value);
+        const value = memberName5(node.value);
         if (key === null || value === null || !isDirectCaseTranslation(key, value)) return;
         if (!hasApiReceiver(node.value)) return;
         const wireName = SNAKE_CASE_RE2.test(key) ? key : value;
@@ -8971,9 +9083,9 @@ var no_positional_tuple_return_default = createRule({
       TSMethodSignature(node) {
         const owner = owningInterface(node);
         const alias = owningTypeAlias(node);
-        const memberName8 = staticMemberName4(node.key);
-        if ((owner === null || !isExportedInterface(owner, typeExports)) && (alias === null || !typeExports.has(alias.id.name)) || node.returnType === void 0 || memberName8 === null) return;
-        report2(node.returnType.typeAnnotation, `${owner?.id.name ?? alias?.id.name ?? "type"}.${memberName8}`);
+        const memberName9 = staticMemberName4(node.key);
+        if ((owner === null || !isExportedInterface(owner, typeExports)) && (alias === null || !typeExports.has(alias.id.name)) || node.returnType === void 0 || memberName9 === null) return;
+        report2(node.returnType.typeAnnotation, `${owner?.id.name ?? alias?.id.name ?? "type"}.${memberName9}`);
       },
       TSTypeAliasDeclaration(node) {
         if (!typeExports.has(node.id.name)) return;
@@ -8984,11 +9096,11 @@ var no_positional_tuple_return_default = createRule({
         const owner = owningInterface(node);
         const alias = owningTypeAlias(node);
         const annotation = node.typeAnnotation?.typeAnnotation;
-        const memberName8 = staticMemberName4(node.key);
-        if ((owner === null || !isExportedInterface(owner, typeExports)) && (alias === null || !typeExports.has(alias.id.name)) || memberName8 === null || annotation === void 0) return;
+        const memberName9 = staticMemberName4(node.key);
+        if ((owner === null || !isExportedInterface(owner, typeExports)) && (alias === null || !typeExports.has(alias.id.name)) || memberName9 === null || annotation === void 0) return;
         const returnType = callableReturnType(annotation, aliases);
         if (returnType !== null) {
-          report2(returnType, `${owner?.id.name ?? alias?.id.name ?? "type"}.${memberName8}`);
+          report2(returnType, `${owner?.id.name ?? alias?.id.name ?? "type"}.${memberName9}`);
         }
       },
       PropertyDefinition(node) {
@@ -14723,7 +14835,8 @@ var PREFER_IMMUTABLE_MODULE_CONSTANT_DOCUMENTATION = {
   remediation: "Expose literals with `as const` or a readonly type, and expose Set or Map values through ReadonlySet or ReadonlyMap.",
   category: "correctness",
   limitations: [
-    "Generated, test and JavaScript files are skipped. Private constants with observed direct or alias mutation are excluded; exported mutable collections remain advisory candidates. Reassigned aliases are conservatively followed, not flow-proven."
+    "Generated, test and JavaScript files are skipped. Private constants with observed direct or alias mutation are excluded; exported mutable collections remain advisory candidates. Reassigned aliases are conservatively followed, not flow-proven.",
+    "Local type aliases are resolved before recognizing standard readonly types; imported or otherwise unknown type declarations are not inferred from their names. Readonly types have no runtime enforcement."
   ],
   examples: [
     {
@@ -14743,6 +14856,26 @@ var PREFER_IMMUTABLE_MODULE_CONSTANT_DOCUMENTATION = {
       focusPath: "src/constants.ts",
       expectedCount: 1,
       public: true
+    },
+    {
+      id: "shadowed-readonly-alias",
+      scenarioId: "type-binding",
+      title: "A type named Readonly still exposes mutable properties",
+      outcome: "match",
+      files: [{ path: "src/constants.ts", source: "type Readonly = { voice: boolean };\nexport const TOOL_SUPPORT: Readonly = { voice: true };" }],
+      focusPath: "src/constants.ts",
+      expectedCount: 1,
+      public: true
+    },
+    {
+      id: "resolved-readonly-alias",
+      scenarioId: "type-binding",
+      title: "A local alias resolves to readonly properties",
+      outcome: "no-match",
+      files: [{ path: "src/constants.ts", source: "type ToolSupport = Readonly<{ voice: boolean }>;\nexport const TOOL_SUPPORT: ToolSupport = { voice: true };" }],
+      focusPath: "src/constants.ts",
+      expectedCount: 0,
+      public: true
     }
   ]
 };
@@ -14797,39 +14930,84 @@ function collectionKind(node, isUnshadowedGlobal3) {
   }
   return null;
 }
-function declaredReadonlyType(node, kind, aliases) {
+function declaredReadonlyType(node, kind, resolveLocalType, isUnshadowedType) {
   const annotation = node.id.type === AST_NODE_TYPES72.Identifier ? node.id.typeAnnotation : void 0;
-  if (annotation !== void 0 && isReadonlyTypeResolved(annotation.typeAnnotation, kind, aliases)) {
+  if (annotation !== void 0 && readonlyTypeState(annotation.typeAnnotation, kind, resolveLocalType, isUnshadowedType) === "readonly") {
     return true;
   }
-  return node.init?.type === AST_NODE_TYPES72.TSAsExpression && isReadonlyTypeResolved(node.init.typeAnnotation, kind, aliases);
+  return node.init?.type === AST_NODE_TYPES72.TSAsExpression && readonlyTypeState(node.init.typeAnnotation, kind, resolveLocalType, isUnshadowedType) === "readonly";
 }
-function isReadonlyTypeResolved(node, kind, aliases, seen = /* @__PURE__ */ new Set()) {
-  if (isReadonlyType(node, kind)) return true;
-  if (node.type !== AST_NODE_TYPES72.TSTypeReference || node.typeName.type !== AST_NODE_TYPES72.Identifier) return false;
-  const name = node.typeName.name;
-  const target = aliases.get(name);
-  if (target === void 0 || seen.has(name)) return false;
-  return isReadonlyTypeResolved(target, kind, aliases, /* @__PURE__ */ new Set([...seen, name]));
+function readonlyTypeState(node, kind, resolveLocalType, isUnshadowedType, arguments_ = /* @__PURE__ */ new Map(), seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(node)) return "unknown";
+  if (node.type !== AST_NODE_TYPES72.TSTypeReference || node.typeName.type !== AST_NODE_TYPES72.Identifier) {
+    return directReadonlyState(node, kind, isUnshadowedType);
+  }
+  const declaration = resolveLocalType(node.typeName);
+  if (declaration === void 0) return directReadonlyState(node, kind, isUnshadowedType);
+  if (declaration.type === AST_NODE_TYPES72.TSTypeParameter) {
+    const argument = arguments_.get(declaration);
+    return argument === void 0 ? "unknown" : readonlyTypeState(
+      argument.node,
+      kind,
+      resolveLocalType,
+      isUnshadowedType,
+      argument.arguments,
+      argument.seen
+    );
+  }
+  const expanded = /* @__PURE__ */ new Set([...seen, node]);
+  return readonlyTypeState(
+    declaration.typeAnnotation,
+    kind,
+    resolveLocalType,
+    isUnshadowedType,
+    bindTypeArguments(declaration, node, arguments_, expanded),
+    expanded
+  );
+}
+function bindTypeArguments(declaration, reference, arguments_, seen) {
+  const bindings = new Map(arguments_);
+  for (const [index, parameter] of (declaration.typeParameters?.params ?? []).entries()) {
+    const argument = reference.typeArguments?.params[index];
+    const node = argument ?? parameter.default;
+    if (node !== void 0) {
+      bindings.set(parameter, { node, arguments: argument === void 0 ? new Map(bindings) : arguments_, seen });
+    }
+  }
+  return bindings;
 }
-function isReadonlyType(node, kind) {
+function directReadonlyState(node, kind, isUnshadowedType) {
   if (node.type === AST_NODE_TYPES72.TSTypeOperator && node.operator === "readonly") {
-    return true;
+    return "readonly";
   }
-  if (node.type !== AST_NODE_TYPES72.TSTypeReference || node.typeName.type !== AST_NODE_TYPES72.Identifier) {
-    return false;
+  if (node.type === AST_NODE_TYPES72.TSTypeLiteral) {
+    if (node.members.length === 0) return "unknown";
+    const readonly2 = kind === "literal" && node.members.length > 0 && node.members.every(
+      (member) => (member.type === AST_NODE_TYPES72.TSPropertySignature || member.type === AST_NODE_TYPES72.TSIndexSignature) && member.readonly
+    );
+    return readonly2 ? "readonly" : "mutable";
+  }
+  if (node.type === AST_NODE_TYPES72.TSArrayType || node.type === AST_NODE_TYPES72.TSTupleType) return "mutable";
+  if (node.type !== AST_NODE_TYPES72.TSTypeReference || node.typeName.type !== AST_NODE_TYPES72.Identifier || !isUnshadowedType(node.typeName)) {
+    return "unknown";
   }
   if (node.typeName.name === "Readonly") {
-    return kind === "literal";
+    return kind === "literal" ? "readonly" : "mutable";
   }
-  return kind === "literal" ? node.typeName.name === "ReadonlyArray" : node.typeName.name === `Readonly${kind}`;
+  if (["Array", "Map", "Set"].includes(node.typeName.name)) return "mutable";
+  if (!["ReadonlyArray", "ReadonlyMap", "ReadonlySet"].includes(node.typeName.name)) return "unknown";
+  const readonly = kind === "literal" ? node.typeName.name === "ReadonlyArray" : node.typeName.name === `Readonly${kind}`;
+  return readonly ? "readonly" : "mutable";
 }
-function hasUnknownExplicitType(node, aliases) {
-  const annotation = node.id.type === AST_NODE_TYPES72.Identifier ? node.id.typeAnnotation?.typeAnnotation : void 0;
+function hasUnknownExplicitType(node, kind, resolveLocalType, isUnshadowedType) {
+  const annotation = (node.id.type === AST_NODE_TYPES72.Identifier ? node.id.typeAnnotation?.typeAnnotation : void 0) ?? (node.init?.type === AST_NODE_TYPES72.TSAsExpression ? node.init.typeAnnotation : void 0);
   if (annotation === void 0) return false;
   if (annotation.type === AST_NODE_TYPES72.TSArrayType || annotation.type === AST_NODE_TYPES72.TSTypeOperator) return false;
   if (annotation.type !== AST_NODE_TYPES72.TSTypeReference || annotation.typeName.type !== AST_NODE_TYPES72.Identifier) return true;
-  return !aliases.has(annotation.typeName.name) && !["Array", "Map", "Readonly", "ReadonlyArray", "ReadonlyMap", "ReadonlySet", "Set"].includes(annotation.typeName.name);
+  if (resolveLocalType(annotation.typeName) !== void 0) {
+    return readonlyTypeState(annotation, kind, resolveLocalType, isUnshadowedType) === "unknown";
+  }
+  return resolveLocalType(annotation.typeName) === void 0 && (!isUnshadowedType(annotation.typeName) || !["Array", "Map", "Readonly", "ReadonlyArray", "ReadonlyMap", "ReadonlySet", "Set"].includes(annotation.typeName.name));
 }
 function referenceMutates(identifier, isUnshadowedGlobal3) {
   let member = identifier.parent;
@@ -14872,11 +15050,20 @@ var prefer_immutable_module_constant_default = createRule({
       const variable = ASTUtils32.findVariable(sourceCode.getScope(identifier), identifier.name);
       return variable === null || variable.defs.length === 0;
     };
+    const isUnshadowedType = (identifier) => {
+      const variable = ASTUtils32.findVariable(sourceCode.getScope(identifier), identifier.name);
+      return variable === null || !variable.defs.some((definition) => definition.isTypeDefinition);
+    };
+    const resolveLocalType = (identifier) => {
+      const variable = ASTUtils32.findVariable(sourceCode.getScope(identifier), identifier.name);
+      const definitions = variable?.defs.filter((definition) => definition.isTypeDefinition) ?? [];
+      const declaration = definitions.length === 1 ? definitions[0]?.node : void 0;
+      return declaration?.type === AST_NODE_TYPES72.TSTypeAliasDeclaration || declaration?.type === AST_NODE_TYPES72.TSTypeParameter ? declaration : void 0;
+    };
     if (JAVASCRIPT_FILE_RE.test(context.filename) || isTestFile(context.filename) || isGeneratedFile(context.filename, sourceCode.getText())) {
       return {};
     }
     const exportedNames2 = /* @__PURE__ */ new Set();
-    const typeAliases2 = /* @__PURE__ */ new Map();
     const mutatesThroughAlias = (root) => {
       const pending = [root];
       const seen = /* @__PURE__ */ new Set();
@@ -14901,10 +15088,6 @@ var prefer_immutable_module_constant_default = createRule({
     return {
       Program(node) {
         function collectModuleBindings(statement) {
-          const declaration = statement.type === AST_NODE_TYPES72.ExportNamedDeclaration ? statement.declaration : statement;
-          if (declaration?.type === AST_NODE_TYPES72.TSTypeAliasDeclaration) {
-            typeAliases2.set(declaration.id.name, declaration.typeAnnotation);
-          }
           if (statement.type === AST_NODE_TYPES72.ExportNamedDeclaration) {
             if (statement.source !== null || statement.exportKind === "type") return;
             for (const specifier of statement.specifiers) {
@@ -14937,7 +15120,7 @@ var prefer_immutable_module_constant_default = createRule({
           return;
         }
         const kind = collectionKind(node.init, isUnshadowedGlobal3);
-        if (kind === null || declaredReadonlyType(node, kind, typeAliases2) || hasUnknownExplicitType(node, typeAliases2)) {
+        if (kind === null || declaredReadonlyType(node, kind, resolveLocalType, isUnshadowedType) || hasUnknownExplicitType(node, kind, resolveLocalType, isUnshadowedType)) {
           return;
         }
         const variable = sourceCode.getDeclaredVariables(node)[0];
@@ -16975,7 +17158,7 @@ var PREFER_NODE_CRYPTO_HASH_DOCUMENTATION = {
     { id: "mutable-one-shot-chain", title: "Avoid mutable state for one value", outcome: "match", files: [{ path: "case.ts", source: "import { createHash } from 'node:crypto'; export const digest = createHash('sha256').update('value').digest('hex');" }], focusPath: "case.ts", expectedCount: 1, public: true }
   ]
 };
-function memberName5(node) {
+function memberName6(node) {
   if (!node.computed && node.property.type === AST_NODE_TYPES82.Identifier) return node.property.name;
   if (node.computed && node.property.type === AST_NODE_TYPES82.Literal && typeof node.property.value === "string") {
     return node.property.value;
@@ -16991,7 +17174,7 @@ function isCryptoLoader(node, resolve2) {
   if (node.callee.type === AST_NODE_TYPES82.Identifier) {
     return node.callee.name === "require" && isUnshadowedBuiltinIdentifier(node.callee, resolve2);
   }
-  return node.callee.type === AST_NODE_TYPES82.MemberExpression && node.callee.object.type === AST_NODE_TYPES82.Identifier && node.callee.object.name === "process" && isUnshadowedBuiltinIdentifier(node.callee.object, resolve2) && memberName5(node.callee) === "getBuiltinModule";
+  return node.callee.type === AST_NODE_TYPES82.MemberExpression && node.callee.object.type === AST_NODE_TYPES82.Identifier && node.callee.object.name === "process" && isUnshadowedBuiltinIdentifier(node.callee.object, resolve2) && memberName6(node.callee) === "getBuiltinModule";
 }
 function isCryptoSpecifier(node) {
   return node.type === AST_NODE_TYPES82.Literal && (node.value === "crypto" || node.value === "node:crypto");
@@ -17073,14 +17256,14 @@ function importedName6(node) {
   return node.type === AST_NODE_TYPES82.Identifier ? node.name : node.value;
 }
 function isMemberCall(node, name) {
-  return node.callee.type === AST_NODE_TYPES82.MemberExpression && memberName5(node.callee) === name;
+  return node.callee.type === AST_NODE_TYPES82.MemberExpression && memberName6(node.callee) === name;
 }
 function isCreateHashCall(node, directBindings, namespaceBindings, resolve2) {
   if (node.callee.type === AST_NODE_TYPES82.Identifier) {
     const variable2 = resolve2(node.callee);
     return variable2 !== null && directBindings.has(variable2);
   }
-  if (node.callee.type !== AST_NODE_TYPES82.MemberExpression || memberName5(node.callee) !== "createHash") {
+  if (node.callee.type !== AST_NODE_TYPES82.MemberExpression || memberName6(node.callee) !== "createHash") {
     return false;
   }
   if (isCryptoLoader(node.callee.object, resolve2)) return true;
@@ -17108,7 +17291,7 @@ var PREFER_NODE_FS_PROMISES_DOCUMENTATION = {
     { id: "sync-read", title: "Do not block on a synchronous read", outcome: "match", files: [{ path: "src/store.ts", source: "import { readFileSync } from 'node:fs'; export function load(path: string) { return readFileSync(path, 'utf8'); }" }], focusPath: "src/store.ts", expectedCount: 1, public: true }
   ]
 };
-function memberName6(node) {
+function memberName7(node) {
   if (!node.computed && node.property.type === AST_NODE_TYPES83.Identifier) return node.property.name;
   if (node.computed && node.property.type === AST_NODE_TYPES83.Literal && typeof node.property.value === "string") {
     return node.property.value;
@@ -17125,7 +17308,7 @@ function isFsLoader(node, isGlobal) {
   const [argument] = expression.arguments;
   if (argument === void 0 || argument.type === AST_NODE_TYPES83.SpreadElement || !isFsSpecifier(argument)) return false;
   if (expression.callee.type === AST_NODE_TYPES83.Identifier) return expression.callee.name === "require" && isGlobal(expression.callee);
-  return expression.callee.type === AST_NODE_TYPES83.MemberExpression && expression.callee.object.type === AST_NODE_TYPES83.Identifier && expression.callee.object.name === "process" && isGlobal(expression.callee.object) && memberName6(expression.callee) === "getBuiltinModule";
+  return expression.callee.type === AST_NODE_TYPES83.MemberExpression && expression.callee.object.type === AST_NODE_TYPES83.Identifier && expression.callee.object.name === "process" && isGlobal(expression.callee.object) && memberName7(expression.callee) === "getBuiltinModule";
 }
 function isFsSpecifier(node) {
   return node.type === AST_NODE_TYPES83.Literal && (node.value === "node:fs" || node.value === "fs");
@@ -17206,7 +17389,7 @@ var prefer_node_fs_promises_default = createRule({
         }
       },
       MemberExpression(node) {
-        const name = memberName6(node);
+        const name = memberName7(node);
         if (name?.endsWith("Sync") !== true) return;
         const object = unwrapAwait2(node.object);
         if (object.type === AST_NODE_TYPES83.Identifier && isNamespace(object) || isFsLoader(object, isGlobal)) {
@@ -21405,7 +21588,7 @@ var REQUIRE_SQL_ACCESS_CLASS_DOCUMENTATION = {
     }
   ]
 };
-function memberName7(node) {
+function memberName8(node) {
   if (!node.computed && node.property.type === AST_NODE_TYPES98.Identifier)
     return node.property.name;
   if (node.computed && node.property.type === AST_NODE_TYPES98.Literal && typeof node.property.value === "string")
@@ -21423,7 +21606,7 @@ function databaseReceiver(node) {
   if (node.type === AST_NODE_TYPES98.Identifier)
     return DATABASE_NAMES.test(node.name);
   if (node.type !== AST_NODE_TYPES98.MemberExpression) return false;
-  const name = memberName7(node);
+  const name = memberName8(node);
   return name === "DB" || name !== null && DATABASE_NAMES.test(name);
 }
 function databaseRootMember(node) {
@@ -21444,7 +21627,7 @@ function databaseRootMember(node) {
     }
     if (current.type === AST_NODE_TYPES98.MemberExpression) {
       if (current.object.type === AST_NODE_TYPES98.ThisExpression)
-        return memberName7(current);
+        return memberName8(current);
       current = current.object;
       continue;
     }
@@ -21468,7 +21651,7 @@ function expressionHasDatabaseMarker(node) {
       continue;
     }
     if (current.type === AST_NODE_TYPES98.MemberExpression) {
-      const name = memberName7(current);
+      const name = memberName8(current);
       if (name === "DB" || name !== null && DATABASE_NAMES.test(name))
         return true;
       current = current.object;
@@ -21490,7 +21673,7 @@ function expressionCallsBuilder(node) {
     }
     if (current.type === AST_NODE_TYPES98.CallExpression) {
       if (current.callee.type !== AST_NODE_TYPES98.MemberExpression) return false;
-      const name = memberName7(current.callee);
+      const name = memberName8(current.callee);
       if (name !== null && BUILDER_METHODS.has(name)) return true;
       current = current.callee.object;
       continue;
@@ -21541,7 +21724,7 @@ function thisRootMember(node) {
   let current = node;
   let root = null;
   while (current.type === AST_NODE_TYPES98.MemberExpression) {
-    const name = memberName7(current);
+    const name = memberName8(current);
     if (name === null) return null;
     root = name;
     current = current.object;
@@ -21595,7 +21778,7 @@ var require_sql_access_class_default = createRule({
       CallExpression(node) {
         if (node.callee.type !== AST_NODE_TYPES98.MemberExpression)
           return;
-        const method = memberName7(node.callee);
+        const method = memberName8(node.callee);
         if (knownNonDatabase(node.callee.object)) return;
         if (method === null || !isDatabaseOperation(method, node.callee.object))
           return;
@@ -23228,10 +23411,11 @@ import { readFileSync as readFileSync3 } from "fs";
 import { dirname as dirname3, join as join3, relative as relative2 } from "path";
 var HTTP_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]);
 var NEXT_COMPONENT = /^(?:src\/)?app\/(?:.*\/)?(?:page|layout|loading|not-found|template|error|global-error|default|forbidden|unauthorized)\.[jt]sx?$/u;
+var NEXT_METADATA = /^(?:src\/)?app\/(?:.*\/)?(?:(?:opengraph-image|twitter-image|icon|apple-icon)\.[jt]sx?|(?:robots|sitemap|manifest)\.[jt]s)$/u;
 var NEXT_ROUTE = /^(?:src\/)?app\/(?:.*\/)?route\.[jt]s$/u;
 function isFrameworkEntrypoint(filename, exportKey) {
   const normalized = filename.replaceAll("\\", "/");
-  if (!/(?:^|\/)(?:app|pages)\/|(?:^|\/)(?:middleware|proxy)\.[jt]s$/u.test(normalized)) return false;
+  if (!/(?:^|\/)(?:app|pages)\/|(?:^|\/)(?:middleware|proxy|instrumentation)\.[jt]s$/u.test(normalized)) return false;
   const owner = packageOwner(normalized);
   if (owner === null) return false;
   const path = relative2(owner.root, normalized).replaceAll("\\", "/");
@@ -23240,9 +23424,12 @@ function isFrameworkEntrypoint(filename, exportKey) {
 }
 function isNextEntrypoint(path, exportKey) {
   const privateAppFolder = /^(?:src\/)?app\/(?:.*\/)?_[^/]+\//u.test(path);
-  if (!privateAppFolder && NEXT_COMPONENT.test(path) && exportKey === "default") return true;
+  if (!privateAppFolder && (NEXT_COMPONENT.test(path) || NEXT_METADATA.test(path)) && exportKey === "default") return true;
   if (!privateAppFolder && NEXT_ROUTE.test(path) && HTTP_METHODS.has(exportKey)) return true;
   if (/^(?:src\/)?pages\/.*\.[jt]sx?$/u.test(path) && exportKey === "default") return true;
+  if (/^(?:src\/)?instrumentation\.[jt]s$/u.test(path)) {
+    return exportKey === "register" || exportKey === "onRequestError";
+  }
   const middleware = /^(?:src\/)?(middleware|proxy)\.[jt]s$/u.exec(path);
   return middleware !== null && (exportKey === "default" || exportKey === middleware[1]);
 }
@@ -23285,7 +23472,7 @@ var SOLE_EXPORT_MATCHES_FILENAME_DOCUMENTATION = {
     "Framework entrypoints, generic stems covered by no-generic-single-export-module, tests, generated files, anonymous defaults, CommonJS, unresolved re-exports, and emission-dependent exports are excluded.",
     "The rule compares the primary filename stem and preserves a single private underscore prefix and conventional suffixes such as .server or .worker. Supporting types do not exempt a sole runtime export; public runtime aliases count as distinct exports.",
     "Exported destructuring patterns are excluded rather than undercounted as public exports.",
-    "Next.js and Astro routing exemptions require the nearest package.json to declare the framework, a conventional entrypoint path, and its expected runtime export. Custom routing roots and pageExtensions are not inferred."
+    "Next.js metadata routes, instrumentation, and other Next.js and Astro entrypoint exemptions require the nearest package.json to declare the framework, a conventional entrypoint path, and its expected runtime export. Custom routing roots and pageExtensions are not inferred."
   ],
   examples: [
     { id: "matching-class", title: "Match a class and module", outcome: "no-match", files: [{ path: "src/artifact-store.ts", source: "export class ArtifactStore {}" }], focusPath: "src/artifact-store.ts", expectedCount: 0, public: true },
@@ -23854,7 +24041,7 @@ var RULES = {
 };
 var meta = {
   name: "@sarj/eslint-plugin",
-  version: "16.2.5"
+  version: "16.3.0"
 };
 var APPLICATION_ONLY_RULES = [];
 var LIBRARY_IMPORT_POLICY = ["error", {