@beignet/cli 0.0.48 → 0.0.50

package/src/inspect.ts

@@ -1,6 +1,16 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { parseProviderPackageMetadata } from "@beignet/core/providers";
+import ts from "typescript";
+import {
+  type ContractFactoryBindings,
+  type ContractFactoryName,
+  contractFactoryBindings,
+  isImportedContractFactoryCall,
+} from "./analysis/contract-factories.js";
+import { canonicalFeatureLayerPath } from "./analysis/layers.js";
+import { analyzePortWiringFiles } from "./analysis/port-wiring.js";
+import { exportedVariableDeclarations } from "./analysis/source-index.js";
 import { createPainter } from "./ansi.js";
 import type { DatabaseSchemaDialect, DatabaseSchemaTable } from "./choices.js";
 import {
@@ -66,7 +76,8 @@ import {
   identifiersFromArrayExpression,
   insertAfterImports,
   matchingDelimiterIndex,
-  outboxRegistryValueInfo,
+  outboxRegistryEntryState,
+  outboxRegistryIdentifiers,
 } from "./registry-edits.js";
 import {
   currentGeneratedPackageScripts,
@@ -221,6 +232,16 @@ type FeatureRouteGroup = {
   }>;
 };
 
+type ReadContractsResult = {
+  contracts: InspectedContract[];
+  queryTransportDiagnostics: InspectDiagnostic[];
+};
+
+type ParsedContract = {
+  contract: InspectedContract;
+  queryTransportMissing: boolean;
+};
+
 export async function inspectApp(
   options: InspectAppOptions = {},
 ): Promise<InspectAppResult> {
@@ -232,7 +253,8 @@ export async function inspectApp(
     ? resolveConfig(options.config)
     : await loadBeignetConfig(targetDir, files);
   const convention = inspectConvention(files, config);
-  const contracts = await readContracts(targetDir, files, config);
+  const inspectedContracts = await readContracts(targetDir, files, config);
+  const { contracts } = inspectedContracts;
   const matchedRoutes = await inspectRouteSurface(
     targetDir,
     files,
@@ -247,6 +269,7 @@ export async function inspectApp(
     contracts,
     matchedRoutes,
     Boolean(options.strict),
+    inspectedContracts.queryTransportDiagnostics,
   );
 
   return {
@@ -330,7 +353,7 @@ async function buildDoctorFixPlan(
     ? resolveConfig(options.config)
     : await loadBeignetConfig(targetDir, files);
   const convention = inspectConvention(files, config);
-  const contracts = await readContracts(targetDir, files, config);
+  const { contracts } = await readContracts(targetDir, files, config);
   const matchedRoutes = await inspectRouteSurface(
     targetDir,
     files,
@@ -711,7 +734,6 @@ export const productionHardeningDiagnosticCodes = new Set([
   "BEIGNET_BILLING_IDEMPOTENCY_PORT_MISSING",
   "BEIGNET_CORS_CREDENTIALS_WILDCARD",
   "BEIGNET_CRON_SECRET_MISSING",
-  "BEIGNET_DEVTOOLS_ROUTE_EXPOSED",
   "BEIGNET_ENTITLEMENTS_PORT_MISSING",
   "BEIGNET_PAYMENTS_STRIPE_MEMORY_PROVIDER",
   "BEIGNET_PAYMENTS_WEBHOOK_ROUTE_MISSING",
@@ -830,16 +852,32 @@ async function readContracts(
   targetDir: string,
   files: string[],
   config: ResolvedBeignetConfig,
-): Promise<InspectedContract[]> {
+): Promise<ReadContractsResult> {
   const contracts: InspectedContract[] = [];
+  const queryTransportDiagnostics: InspectDiagnostic[] = [];
   const contractFiles = contractSourceFiles(files, config);
 
   for (const file of contractFiles) {
     const source = await readFile(path.join(targetDir, file), "utf8");
-    contracts.push(...parseContracts(source, file));
+    for (const parsed of parseContracts(source, file)) {
+      contracts.push(parsed.contract);
+      if (!parsed.queryTransportMissing) continue;
+
+      queryTransportDiagnostics.push({
+        severity: "error",
+        code: "BEIGNET_QUERY_TRANSPORT_MISSING",
+        file,
+        contract: parsed.contract.exportName,
+        subject: { file, exportName: parsed.contract.exportName },
+        message: `${parsed.contract.exportName} declares a query schema without an explicit query transport. Pass defineQueryTransport(...) as the second .query(...) argument so the client, server, and OpenAPI document share one wire format.`,
+      });
+    }
   }
 
-  return contracts.sort(compareContracts);
+  return {
+    contracts: contracts.sort(compareContracts),
+    queryTransportDiagnostics,
+  };
 }
 
 function inspectConvention(
@@ -901,68 +939,126 @@ function hasRequirement(files: string[], requirement: string): boolean {
   return files.includes(requirement);
 }
 
-function parseContracts(source: string, file: string): InspectedContract[] {
-  const contracts: InspectedContract[] = [];
-  const groupPrefixes = parseContractGroupPrefixes(source);
-  const groupErrorRefs = parseContractGroupErrorRefs(source);
-  const exportRegex =
-    /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=([\s\S]*?)(?=\nexport const\s+[A-Za-z_$][\w$]*\s*=|$)/g;
+function parseContracts(source: string, file: string): ParsedContract[] {
+  const contracts: ParsedContract[] = [];
+  const sourceFile = ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const assignments = variableAssignments(sourceFile);
+  const assignmentsByName = new Map(
+    assignments.map((assignment) => [assignment.name, assignment.expression]),
+  );
+  const factoryBindings = contractFactoryBindings(sourceFile);
 
-  for (const exportMatch of source.matchAll(exportRegex)) {
-    const block = exportMatch[2];
-    const methodMatch =
-      /([A-Za-z_$][\w$]*)(?:\s*\.\s*[A-Za-z_$][\w$]*\([^)]*\))*\s*\.\s*(get|post|put|patch|delete|head|options)\(\s*["']([^"']+)["'](?:\s*,\s*["'][^"']+["'])?\s*\)/.exec(
-        block,
-      );
-    if (methodMatch) {
-      const receiver = methodMatch[1];
-      const pathPrefix = groupPrefixes.get(receiver) ?? "";
-      const routePath = joinContractPaths(pathPrefix, methodMatch[3]);
+  for (const { exportName, declaration } of exportedVariableDeclarations(
+    sourceFile,
+  )) {
+    if (!declaration.initializer) continue;
+    const chain = resolveContractCallChain(
+      declaration.initializer,
+      assignmentsByName,
+    );
+    if (!chain) continue;
 
+    const directContract = parseDirectContract(chain, factoryBindings);
+    if (directContract) {
       contracts.push({
-        exportName: exportMatch[1],
-        file,
-        metadata: parseContractMetadata(
-          block,
-          groupErrorRefs.get(receiver) ?? [],
-        ),
-        method: methodMatch[2].toUpperCase() as HttpMethod,
-        path: routePath,
+        contract: {
+          exportName,
+          file,
+          metadata: parseContractMetadata(
+            applyContractMetadataCalls(
+              emptyContractMetadataState(),
+              chain.calls,
+            ),
+          ),
+          method: directContract.method,
+          path: normalizeContractPath(directContract.path),
+        },
+        queryTransportMissing: contractQueryHasTransport(chain) === false,
       });
       continue;
     }
 
-    const directContract = parseDirectContract(block);
-    if (directContract) {
-      contracts.push({
-        exportName: exportMatch[1],
+    const methodIndex = chain.calls.findIndex((call) =>
+      isHttpMethod(call.name.toUpperCase()),
+    );
+    if (methodIndex === -1) continue;
+    const methodCall = chain.calls[methodIndex];
+    const routePath = staticString(methodCall.arguments[0]);
+    if (!routePath) continue;
+
+    const hasGroupFactory = contractFactoryCall(
+      chain,
+      "defineContractGroup",
+      factoryBindings,
+    );
+    if (!hasGroupFactory) continue;
+
+    const pathPrefix = applyStaticPrefixes(
+      "",
+      chain.calls.slice(0, methodIndex),
+    );
+    if (pathPrefix === undefined) continue;
+
+    contracts.push({
+      contract: {
+        exportName,
         file,
-        metadata: parseContractMetadata(block),
-        method: directContract.method,
-        path: normalizeContractPath(directContract.path),
-      });
-    }
+        metadata: parseContractMetadata(
+          applyContractMetadataCalls(emptyContractMetadataState(), chain.calls),
+        ),
+        method: methodCall.name.toUpperCase() as HttpMethod,
+        path: joinContractPaths(pathPrefix, routePath),
+      },
+      queryTransportMissing: contractQueryHasTransport(chain) === false,
+    });
   }
 
   return contracts;
 }
 
+function unwrapContractExpression(expression: ts.Expression): ts.Expression {
+  let current = expression;
+  while (
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isTypeAssertionExpression(current) ||
+    ts.isNonNullExpression(current) ||
+    ts.isSatisfiesExpression(current)
+  ) {
+    current = current.expression;
+  }
+  return current;
+}
+
+type ContractMetadataState = {
+  authRequired?: boolean;
+  authorizationAbility?: string;
+  authorizationAuditRequired?: boolean;
+  audit?: boolean;
+  auditRequired?: boolean;
+  catalogErrors: InspectedCatalogErrorRef[];
+};
+
+function emptyContractMetadataState(): ContractMetadataState {
+  return { catalogErrors: [] };
+}
+
 function parseContractMetadata(
-  block: string,
-  inheritedCatalogErrors: InspectedCatalogErrorRef[] = [],
+  state: ContractMetadataState,
 ): InspectedContractMetadata | undefined {
-  const authRequired = /\bauth\s*:\s*["']required["']/.test(block);
-  const authorizationAbility =
-    /\bauthorization\s*:\s*\{[\s\S]*?\bability\s*:\s*["']([^"']+)["']/.exec(
-      block,
-    )?.[1];
+  const authRequired = state.authRequired === true;
+  const authorizationAbility = state.authorizationAbility;
   const auditRequired =
-    /\baudit\s*:\s*["']required["']/.test(block) ||
-    /\bauditRequired\s*:\s*true\b/.test(block);
-  const catalogErrors = dedupeCatalogErrorRefs([
-    ...inheritedCatalogErrors,
-    ...parseCatalogErrorRefs(block),
-  ]);
+    state.audit === true ||
+    state.auditRequired === true ||
+    state.authorizationAuditRequired === true;
+  const catalogErrors = state.catalogErrors;
 
   if (
     !authRequired &&
@@ -981,21 +1077,129 @@ function parseContractMetadata(
   };
 }
 
-function parseDirectContract(
-  block: string,
-): { method: HttpMethod; path: string } | undefined {
-  const configMatch = /defineContract\s*\(\s*\{([\s\S]*?)\}\s*\)/.exec(block);
-  if (!configMatch) return undefined;
+function applyContractMetadataCalls(
+  initialState: ContractMetadataState,
+  calls: ContractCall[],
+): ContractMetadataState {
+  const state: ContractMetadataState = {
+    ...initialState,
+    catalogErrors: [...initialState.catalogErrors],
+  };
 
-  const configSource = configMatch[1];
-  const methodMatch = /method\s*:\s*["']([^"']+)["']/.exec(configSource);
-  const pathMatch = /path\s*:\s*["']([^"']+)["']/.exec(configSource);
-  if (!methodMatch || !pathMatch) return undefined;
+  for (const call of calls) {
+    if (call.name === "meta") {
+      applyContractMetaObject(state, objectLiteral(call.arguments[0]));
+      continue;
+    }
+    if (call.name === "errors") {
+      state.catalogErrors = applyCatalogErrorCall(
+        state.catalogErrors,
+        call.arguments[0],
+      );
+    }
+  }
 
-  const method = methodMatch[1].toUpperCase();
-  if (!isHttpMethod(method)) return undefined;
+  return state;
+}
+
+function applyContractMetaObject(
+  state: ContractMetadataState,
+  metadata: ts.ObjectLiteralExpression | undefined,
+): void {
+  if (!metadata) {
+    state.authRequired = undefined;
+    state.authorizationAbility = undefined;
+    state.authorizationAuditRequired = undefined;
+    state.audit = undefined;
+    state.auditRequired = undefined;
+    return;
+  }
 
-  return { method, path: pathMatch[1] };
+  const auth = objectPropertyResult(metadata, "auth");
+  if (auth.kind !== "absent") {
+    state.authRequired =
+      auth.kind === "value" ? staticRequiredValue(auth.value) : undefined;
+  }
+
+  const authorization = objectPropertyResult(metadata, "authorization");
+  if (authorization.kind !== "absent") {
+    const value =
+      authorization.kind === "value"
+        ? objectLiteral(authorization.value)
+        : undefined;
+    if (!value) {
+      state.authorizationAbility = undefined;
+      state.authorizationAuditRequired = undefined;
+    } else {
+      const ability = objectPropertyResult(value, "ability");
+      state.authorizationAbility =
+        ability.kind === "value" ? staticString(ability.value) : undefined;
+      state.authorizationAuditRequired = objectRequiresAudit(value);
+    }
+  }
+
+  const audit = objectPropertyResult(metadata, "audit");
+  const auditRequired = objectPropertyResult(metadata, "auditRequired");
+  if (audit.kind !== "absent") {
+    state.audit =
+      audit.kind === "value" ? staticRequiredValue(audit.value) : undefined;
+  }
+  if (auditRequired.kind !== "absent") {
+    state.auditRequired =
+      auditRequired.kind === "value"
+        ? staticBoolean(auditRequired.value)
+        : undefined;
+  }
+}
+
+function objectRequiresAudit(
+  metadata: ts.ObjectLiteralExpression,
+): boolean | undefined {
+  const audit = objectPropertyResult(metadata, "audit");
+  const auditRequired = objectPropertyResult(metadata, "auditRequired");
+  if (audit.kind === "unknown" || auditRequired.kind === "unknown") {
+    return undefined;
+  }
+  const auditValue =
+    audit.kind === "value" ? staticRequiredValue(audit.value) : false;
+  const auditRequiredValue =
+    auditRequired.kind === "value" ? staticBoolean(auditRequired.value) : false;
+  if (auditValue === undefined || auditRequiredValue === undefined) {
+    return undefined;
+  }
+  return auditValue || auditRequiredValue;
+}
+
+function staticRequiredValue(expression: ts.Expression): boolean | undefined {
+  const value = staticString(expression);
+  return value === undefined ? undefined : value === "required";
+}
+
+function staticBoolean(expression: ts.Expression): boolean | undefined {
+  if (expression.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (expression.kind === ts.SyntaxKind.FalseKeyword) return false;
+  return undefined;
+}
+
+function parseDirectContract(
+  chain: ContractCallChain,
+  factoryBindings: ContractFactoryBindings,
+): { method: HttpMethod; path: string } | undefined {
+  const factoryCall = contractFactoryCall(
+    chain,
+    "defineContract",
+    factoryBindings,
+  );
+  if (!factoryCall) return undefined;
+  const options = objectLiteral(factoryCall.arguments[0]);
+  if (!options) return undefined;
+  const methodValue = staticString(objectProperty(options, "method"));
+  const contractPath = staticString(objectProperty(options, "path"));
+  if (!methodValue || !contractPath) return undefined;
+
+  const method = methodValue.toUpperCase();
+  if (!isHttpMethod(method)) return undefined;
+  return { method, path: contractPath };
 }
 
 function isHttpMethod(method: string): method is HttpMethod {
@@ -1004,118 +1208,245 @@ function isHttpMethod(method: string): method is HttpMethod {
   );
 }
 
-function parseContractGroupPrefixes(source: string): Map<string, string> {
-  const assignments = [
-    ...source.matchAll(
-      /(?:^|\n)(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*([\s\S]*?);/g,
-    ),
-  ].map((match) => ({
-    name: match[1],
-    expression: match[2],
-  }));
-  const prefixes = new Map<string, string>();
+type VariableAssignment = {
+  name: string;
+  expression: ts.Expression;
+};
 
-  let changed = true;
-  while (changed) {
-    changed = false;
-    for (const assignment of assignments) {
-      if (prefixes.has(assignment.name)) continue;
+type ContractCall = {
+  name: string;
+  arguments: readonly ts.Expression[];
+  node: ts.CallExpression;
+};
 
-      const basePrefix = baseGroupPrefix(assignment.expression, prefixes);
-      if (basePrefix === undefined) continue;
+type ContractCallChain = {
+  baseIdentifier?: string;
+  rootCall?: ContractCall;
+  calls: ContractCall[];
+};
 
-      const prefix = prefixCalls(assignment.expression).reduce(
-        (current, next) => joinContractPaths(current, next),
-        basePrefix,
-      );
-      prefixes.set(assignment.name, prefix);
-      changed = true;
+function variableAssignments(sourceFile: ts.SourceFile): VariableAssignment[] {
+  return sourceFile.statements
+    .filter(ts.isVariableStatement)
+    .flatMap((statement) =>
+      [...statement.declarationList.declarations]
+        .filter(
+          (
+            declaration,
+          ): declaration is ts.VariableDeclaration & {
+            name: ts.Identifier;
+            initializer: ts.Expression;
+          } =>
+            ts.isIdentifier(declaration.name) &&
+            declaration.initializer !== undefined,
+        )
+        .map((declaration) => ({
+          name: declaration.name.text,
+          expression: declaration.initializer,
+        })),
+    );
+}
+
+function resolveContractCallChain(
+  expression: ts.Expression,
+  assignments: ReadonlyMap<string, ts.Expression>,
+  resolving = new Set<string>(),
+): ContractCallChain | undefined {
+  const chain = contractCallChain(expression);
+  if (!chain || chain.rootCall || !chain.baseIdentifier) return chain;
+
+  const baseExpression = assignments.get(chain.baseIdentifier);
+  if (!baseExpression || resolving.has(chain.baseIdentifier)) return chain;
+
+  const nextResolving = new Set(resolving);
+  nextResolving.add(chain.baseIdentifier);
+  const baseChain = resolveContractCallChain(
+    baseExpression,
+    assignments,
+    nextResolving,
+  );
+  if (!baseChain) return chain;
+
+  return {
+    ...baseChain,
+    calls: [...baseChain.calls, ...chain.calls],
+  };
+}
+
+function contractCallChain(
+  rawExpression: ts.Expression,
+): ContractCallChain | undefined {
+  const calls: ContractCall[] = [];
+  let expression = rawExpression;
+
+  while (true) {
+    expression = unwrapContractExpression(expression);
+    if (ts.isPropertyAccessExpression(expression)) {
+      expression = expression.expression;
+      continue;
     }
+    if (ts.isCallExpression(expression)) {
+      const callee = unwrapContractExpression(expression.expression);
+      if (ts.isPropertyAccessExpression(callee)) {
+        calls.unshift({
+          name: callee.name.text,
+          arguments: [...expression.arguments],
+          node: expression,
+        });
+        expression = callee.expression;
+        continue;
+      }
+      if (ts.isIdentifier(callee)) {
+        return {
+          baseIdentifier: callee.text,
+          rootCall: {
+            name: callee.text,
+            arguments: [...expression.arguments],
+            node: expression,
+          },
+          calls,
+        };
+      }
+      return undefined;
+    }
+    if (ts.isIdentifier(expression)) {
+      return { baseIdentifier: expression.text, calls };
+    }
+    return undefined;
   }
+}
 
-  return prefixes;
+function contractFactoryCall(
+  chain: ContractCallChain,
+  name: ContractFactoryName,
+  factoryBindings: ContractFactoryBindings,
+): ContractCall | undefined {
+  const calls = chain.rootCall ? [chain.rootCall] : chain.calls;
+  return calls.find((call) =>
+    isImportedContractFactoryCall(call.node, name, factoryBindings),
+  );
 }
 
-function parseContractGroupErrorRefs(
-  source: string,
-): Map<string, InspectedCatalogErrorRef[]> {
-  const assignments = [
-    ...source.matchAll(
-      /(?:^|\n)(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*([\s\S]*?);/g,
-    ),
-  ].map((match) => ({
-    name: match[1],
-    expression: match[2],
-  }));
-  const groupErrors = new Map<string, InspectedCatalogErrorRef[]>();
-
-  let changed = true;
-  while (changed) {
-    changed = false;
-    for (const assignment of assignments) {
-      if (groupErrors.has(assignment.name)) continue;
-
-      const baseErrors = baseGroupErrors(assignment.expression, groupErrors);
-      if (baseErrors === undefined) continue;
-
-      groupErrors.set(
-        assignment.name,
-        dedupeCatalogErrorRefs([
-          ...baseErrors,
-          ...parseCatalogErrorRefs(assignment.expression),
-        ]),
-      );
-      changed = true;
-    }
+function applyStaticPrefixes(
+  initialPrefix: string,
+  calls: ContractCall[],
+): string | undefined {
+  let prefix = initialPrefix;
+  for (const call of calls) {
+    if (call.name !== "prefix") continue;
+    const next = staticString(call.arguments[0]);
+    if (next === undefined) return undefined;
+    prefix = joinContractPaths(prefix, next);
   }
+  return prefix;
+}
 
-  return groupErrors;
+function contractQueryHasTransport(
+  chain: ContractCallChain,
+): boolean | undefined {
+  const queryCall = chain.calls.find((call) => call.name === "query");
+  return queryCall ? queryCall.arguments.length >= 2 : undefined;
 }
 
-function baseGroupErrors(
-  expression: string,
-  groupErrors: Map<string, InspectedCatalogErrorRef[]>,
-): InspectedCatalogErrorRef[] | undefined {
-  if (expression.includes("defineContractGroup(")) return [];
+function applyCatalogErrorCall(
+  current: InspectedCatalogErrorRef[],
+  expression: ts.Expression | undefined,
+): InspectedCatalogErrorRef[] {
+  const errors = objectLiteral(expression);
+  if (!errors) return [];
+  let merged = [...current];
 
-  const baseMatch = /^\s*([A-Za-z_$][\w$]*)\b/.exec(expression);
-  if (!baseMatch) return undefined;
+  for (const property of errors.properties) {
+    if (ts.isSpreadAssignment(property)) {
+      merged = [];
+      continue;
+    }
+    const key = staticPropertyName(property.name);
+    if (!key) {
+      merged = [];
+      continue;
+    }
 
-  return groupErrors.get(baseMatch[1]);
-}
+    merged = merged.filter((ref) => ref.key !== key);
+    if (!ts.isPropertyAssignment(property)) continue;
+    const value = unwrapContractExpression(property.initializer);
+    if (
+      !ts.isPropertyAccessExpression(value) ||
+      !ts.isIdentifier(value.expression)
+    ) {
+      continue;
+    }
+    merged.push({
+      key,
+      catalog: value.expression.text,
+      catalogKey: value.name.text,
+    });
+  }
 
-function baseGroupPrefix(
-  expression: string,
-  prefixes: Map<string, string>,
-): string | undefined {
-  if (expression.includes("defineContractGroup(")) return "";
+  return merged;
+}
 
-  const baseMatch = /^\s*([A-Za-z_$][\w$]*)\b/.exec(expression);
-  if (!baseMatch) return undefined;
+function objectLiteral(
+  expression: ts.Expression | undefined,
+): ts.ObjectLiteralExpression | undefined {
+  if (!expression) return undefined;
+  const unwrapped = unwrapContractExpression(expression);
+  return ts.isObjectLiteralExpression(unwrapped) ? unwrapped : undefined;
+}
 
-  return prefixes.get(baseMatch[1]);
+function objectProperty(
+  object: ts.ObjectLiteralExpression,
+  name: string,
+): ts.Expression | undefined {
+  const result = objectPropertyResult(object, name);
+  return result.kind === "value" ? result.value : undefined;
 }
 
-function prefixCalls(expression: string): string[] {
-  return [...expression.matchAll(/\.prefix\(\s*["']([^"']+)["']\s*\)/g)].map(
-    (match) => match[1],
-  );
+type ObjectPropertyResult =
+  | { kind: "absent" }
+  | { kind: "unknown" }
+  | { kind: "value"; value: ts.Expression };
+
+function objectPropertyResult(
+  object: ts.ObjectLiteralExpression,
+  name: string,
+): ObjectPropertyResult {
+  for (const property of [...object.properties].reverse()) {
+    if (ts.isSpreadAssignment(property)) return { kind: "unknown" };
+    const propertyName = staticPropertyName(property.name);
+    if (propertyName === undefined) return { kind: "unknown" };
+    if (propertyName !== name) continue;
+    if (ts.isPropertyAssignment(property)) {
+      return {
+        kind: "value",
+        value: unwrapContractExpression(property.initializer),
+      };
+    }
+    return { kind: "unknown" };
+  }
+  return { kind: "absent" };
 }
 
-function parseCatalogErrorRefs(source: string): InspectedCatalogErrorRef[] {
-  return dedupeCatalogErrorRefs(
-    objectArgumentBodies(source, /\.errors\s*\(/g).flatMap((body) =>
-      [...body.matchAll(errorCatalogRefRegex)].map((match) => ({
-        key: match[1],
-        catalog: match[2],
-        catalogKey: match[3],
-      })),
-    ),
-  );
+function staticPropertyName(name: ts.PropertyName): string | undefined {
+  if (
+    ts.isIdentifier(name) ||
+    ts.isStringLiteral(name) ||
+    ts.isNumericLiteral(name)
+  ) {
+    return name.text;
+  }
+  return undefined;
 }
 
-const errorCatalogRefRegex =
-  /(?:^|[,{])\s*([A-Za-z_$][\w$]*)\s*:\s*([A-Za-z_$][\w$]*)\s*\.\s*([A-Za-z_$][\w$]*)/g;
+function staticString(
+  expression: ts.Expression | undefined,
+): string | undefined {
+  if (!expression) return undefined;
+  const value = unwrapContractExpression(expression);
+  return ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)
+    ? value.text
+    : undefined;
+}
 
 function parseErrorCatalogKeys(source: string): Set<string> {
   const keys = new Set<string>();
@@ -1208,23 +1539,6 @@ function topLevelObjectKeys(body: string): string[] {
   return keys;
 }
 
-function dedupeCatalogErrorRefs(
-  refs: InspectedCatalogErrorRef[],
-): InspectedCatalogErrorRef[] {
-  const seen = new Set<string>();
-  const deduped: InspectedCatalogErrorRef[] = [];
-
-  for (const ref of refs) {
-    const key = `${ref.key}:${ref.catalog}:${ref.catalogKey}`;
-    if (seen.has(key)) continue;
-
-    seen.add(key);
-    deduped.push(ref);
-  }
-
-  return deduped;
-}
-
 function joinContractPaths(prefix: string, routePath: string): string {
   if (!prefix) return normalizeContractPath(routePath);
   const segments = [
@@ -1667,8 +1981,9 @@ async function inspectDiagnostics(
   contracts: InspectedContract[],
   matchedRoutes: MatchedRoutesResult,
   strict: boolean,
+  queryTransportDiagnostics: InspectDiagnostic[],
 ): Promise<InspectDiagnostic[]> {
-  const diagnostics: InspectDiagnostic[] = [];
+  const diagnostics: InspectDiagnostic[] = [...queryTransportDiagnostics];
   const frameworkLayout =
     config.framework === "next" ? convention.nextLayout : convention.webLayout;
   const missingFrameworkLayout =
@@ -1775,6 +2090,7 @@ async function inspectDiagnostics(
       contracts,
     )),
     ...(await inspectServerlessFootguns(targetDir, files, config, convention)),
+    ...(await inspectOutboxJobDispatcherDrift(targetDir, files, config)),
     ...(await inspectProductionReadiness(targetDir, files, config, convention)),
     ...(await inspectFeatureArtifactDrift(
       targetDir,
@@ -2472,14 +2788,14 @@ async function inspectProductionReadiness(
 
     if (
       containsCallExpression(source, "createDevtoolsRoute") &&
-      /\benabled\s*:\s*true\b/.test(source) &&
-      !/\bauthorize\s*:/.test(source)
+      !/\bauthorize\s*(?::|\()/.test(source) &&
+      !/\ballowUnauthenticatedDevelopmentAccess\s*:\s*true\b/.test(source)
     ) {
       diagnostics.push({
         severity: "warning",
-        code: "BEIGNET_DEVTOOLS_ROUTE_EXPOSED",
+        code: "BEIGNET_DEVTOOLS_ROUTE_POLICY_MISSING",
         file,
-        message: `${file} enables devtools with enabled: true and no authorize callback. Keep devtools disabled in production or add app-owned authorization before exposing diagnostic data.`,
+        message: `${file} creates a devtools route without an access policy, so the route remains hidden. Add app-owned authorize(...), or explicitly set allowUnauthenticatedDevelopmentAccess: true only for a development server bound exclusively to loopback.`,
       });
     }
 
@@ -3882,9 +4198,7 @@ async function inspectFeatureArtifactDrift(
   }
 
   for (const file of files) {
-    const match = new RegExp(
-      `^${escapeRegExp(featuresPath)}/([^/]+)/[^/]+\\.test\\.ts$`,
-    ).exec(file);
+    const match = directFeatureTestMatch(file, featuresPath);
     if (!match) continue;
     diagnostics.push({
       severity: "warning",
@@ -3896,23 +4210,27 @@ async function inspectFeatureArtifactDrift(
 
   for (const file of files) {
     if (
-      !file.endsWith(".ts") ||
-      file.endsWith(".test.ts") ||
-      file.endsWith(".d.ts")
+      !/\.(?:ts|tsx|mts|cts)$/.test(file) ||
+      /\.d\.(?:ts|mts|cts)$/.test(file)
     ) {
       continue;
     }
 
-    const misplaced = misplacedFeatureArtifactFolder(file, featuresPath);
+    const misplaced = directFeatureTestMatch(file, featuresPath)
+      ? undefined
+      : misplacedFeatureLayer(file, config);
     if (misplaced) {
       diagnostics.push({
         severity: "warning",
         code: "BEIGNET_FEATURE_ARTIFACT_FOLDER",
         file,
-        message: `${file} uses ${misplaced.actual}, but Beignet expects ${misplaced.expected}. Keep feature-owned workflow artifacts in the canonical feature folders so CLI generators, docs, and architecture lint stay aligned.`,
+        message: `${file} uses ${misplaced.actual}, but Beignet expects ${misplaced.expected}. Keep feature-owned files in the canonical feature folders so CLI generators, docs, and architecture lint stay aligned.`,
       });
     }
 
+    if (isTestSourceFile(file)) continue;
+    if (!file.endsWith(".ts")) continue;
+
     if (
       isNotificationDefinitionFile(file, featuresPath) ||
       isInfraOrServerFile(file, config)
@@ -3933,6 +4251,15 @@ async function inspectFeatureArtifactDrift(
   return diagnostics;
 }
 
+function directFeatureTestMatch(
+  file: string,
+  featuresPath: string,
+): RegExpExecArray | null {
+  return new RegExp(
+    `^${escapeRegExp(featuresPath)}/([^/]+)/[^/]+\\.(?:test|spec)\\.(?:ts|tsx|mts|cts)$`,
+  ).exec(file);
+}
+
 function isFeatureArtifactFile(
   file: string,
   featuresPath: string,
@@ -3965,34 +4292,30 @@ async function appHasUploadRoute(
   return false;
 }
 
-function misplacedFeatureArtifactFolder(
+function misplacedFeatureLayer(
   file: string,
-  featuresPath: string,
+  config: ResolvedBeignetConfig,
 ): { actual: string; expected: string } | undefined {
-  const match = new RegExp(
-    `^${escapeRegExp(featuresPath)}/([^/]+)/([^/]+)/`,
-  ).exec(file);
+  const featuresPath = directoryPath(config.paths.features);
+  const match = new RegExp(`^${escapeRegExp(featuresPath)}/([^/]+)/(.+)$`).exec(
+    file,
+  );
   if (!match) return undefined;
 
-  const folder = match[2];
-  const mappings: Record<string, string> = {
-    command: "tasks/",
-    commands: "tasks/",
-    event: "domain/events/",
-    events: "domain/events/",
-    job: "jobs/",
-    listener: "listeners/",
-    notification: "notifications/",
-    schedule: "schedules/",
-    scheduled: "schedules/",
-    task: "tasks/",
-    upload: "uploads/",
-  };
+  const canonicalPath = canonicalFeatureLayerPath(file, config);
+  if (!canonicalPath) return undefined;
 
-  const expected = mappings[folder];
-  if (!expected) return undefined;
+  const featurePrefix = `${featuresPath}/${match[1]}/`;
+  const actualRelative = file.slice(featurePrefix.length);
+  const expectedRelative = canonicalPath.slice(featurePrefix.length);
+  const actual = actualRelative.includes("/")
+    ? `${actualRelative.split("/")[0]}/`
+    : actualRelative;
+  const expectedDirectory = path.posix.dirname(expectedRelative);
+  const expected =
+    expectedDirectory === "." ? expectedRelative : `${expectedDirectory}/`;
 
-  return { actual: `${folder}/`, expected };
+  return { actual, expected };
 }
 
 function isNotificationDefinitionFile(
@@ -4081,6 +4404,7 @@ type WorkflowRegistrationDrift = {
     unregistered: UnregisteredWorkflowRegistry[];
     wiringFile?: string;
     eventBusFile?: string;
+    unsafeLifecycleFiles: string[];
   };
 };
 
@@ -4159,6 +4483,15 @@ async function inspectWorkflowRegistrationDrift(
   }
 
   const infraDir = directoryPath(path.dirname(config.paths.portWiring));
+  for (const file of drift.listeners.unsafeLifecycleFiles) {
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_LISTENER_LIFECYCLE_UNSAFE",
+      file,
+      message: `${file} calls registerListeners(...) without the complete provider lifecycle, so server startup can resolve before listeners are ready or shutdown can leak subscriptions. Register listeners in start(), return or await registration.ready, and return or await registration.unsubscribe() in stop().`,
+    });
+  }
+
   const listenerTarget = drift.listeners.wiringFile
     ? `${drift.listeners.wiringFile}, which already calls registerListeners(...)`
     : drift.listeners.eventBusFile
@@ -4329,7 +4662,7 @@ async function workflowRegistrationDrift(
       events: [],
       jobs: [],
     },
-    listeners: { unregistered: [] },
+    listeners: { unregistered: [], unsafeLifecycleFiles: [] },
   };
   if (registries.length === 0) return drift;
 
@@ -4371,10 +4704,7 @@ async function workflowRegistrationDrift(
         // Events without listeners have nothing to deliver on drain, so only
         // record-only events stay out of the registry without a warning.
         const listened = await listenedEventNames(targetDir, files, config);
-        const value = outboxRegistryValueInfo(outboxSource, "events");
-        const registered = value
-          ? identifiersFromArrayExpression(value.text)
-          : new Set<string>();
+        const registered = outboxRegistryIdentifiers(outboxSource, "events");
         drift.outbox.events = unregisteredWorkflowRegistries(
           eventRegistries,
           registered,
@@ -4383,10 +4713,7 @@ async function workflowRegistrationDrift(
       }
 
       if (jobRegistries.length > 0) {
-        const value = outboxRegistryValueInfo(outboxSource, "jobs");
-        const registered = value
-          ? identifiersFromArrayExpression(value.text)
-          : new Set<string>();
+        const registered = outboxRegistryIdentifiers(outboxSource, "jobs");
         drift.outbox.jobs = unregisteredWorkflowRegistries(
           jobRegistries,
           registered,
@@ -4397,7 +4724,12 @@ async function workflowRegistrationDrift(
 
   const listenerRegistries = byKind("listeners");
   if (listenerRegistries.length > 0) {
-    const wiring = await listenerWiringReferences(targetDir, files, config);
+    const wiring = await listenerWiringReferences(
+      targetDir,
+      files,
+      config,
+      listenerRegistries,
+    );
     drift.listeners = {
       unregistered: unregisteredWorkflowRegistries(
         listenerRegistries,
@@ -4405,6 +4737,7 @@ async function workflowRegistrationDrift(
       ),
       wiringFile: wiring.wiringFile,
       eventBusFile: wiring.eventBusFile,
+      unsafeLifecycleFiles: wiring.unsafeLifecycleFiles,
     };
   }
 
@@ -4739,12 +5072,15 @@ async function listenerWiringReferences(
   targetDir: string,
   files: string[],
   config: ResolvedBeignetConfig,
+  listenerRegistries: FeatureWorkflowRegistry[],
 ): Promise<{
   identifiers: Set<string>;
   wiringFile?: string;
   eventBusFile?: string;
+  unsafeLifecycleFiles: string[];
 }> {
   const identifiers = new Set<string>();
+  const unsafeLifecycleFiles = new Set<string>();
   let wiringFile: string | undefined;
   let eventBusFile: string | undefined;
   let centralListenerRegistryReferenced = false;
@@ -4756,35 +5092,54 @@ async function listenerWiringReferences(
 
     const source = await readFile(path.join(targetDir, file), "utf8");
     const namedImports = parseNamedImportSources(source);
-    let foundCall = false;
-
-    for (const match of source.matchAll(/\bregisterListeners\s*\(/g)) {
-      const openParen = (match.index ?? 0) + match[0].length - 1;
-      const closeParen = matchingDelimiterIndex(source, openParen, "(", ")");
-      const argsText =
-        closeParen === -1
-          ? source.slice(openParen)
-          : source.slice(openParen + 1, closeParen);
+    const sourceFile = ts.createSourceFile(
+      file,
+      source,
+      ts.ScriptTarget.Latest,
+      true,
+      file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    );
+    const registerListenersBindings = importedRegisterListenersBindings(
+      source,
+      namedImports,
+    );
+    const calls = registerListenersCalls(sourceFile, registerListenersBindings);
+    let foundRelevantCall = false;
 
-      foundCall = true;
+    for (const call of calls) {
+      const argsText = call.arguments
+        .map((argument) => argument.getText(sourceFile))
+        .join(",");
       const callIdentifiers = identifiersFromArrayExpression(argsText);
+      const referencesCentral = callReferencesCentralListenerRegistry({
+        callIdentifiers,
+        namedImports,
+        importerFile: file,
+        listenerRegistryFile,
+        files,
+      });
+      const referencesFeature = callReferencesFeatureListenerRegistry({
+        callIdentifiers,
+        namedImports,
+        importerFile: file,
+        files,
+        listenerRegistries,
+      });
+      if (!referencesCentral && !referencesFeature) continue;
+
+      foundRelevantCall = true;
       for (const identifier of callIdentifiers) {
         identifiers.add(identifier);
       }
-      if (
-        callReferencesCentralListenerRegistry({
-          callIdentifiers,
-          namedImports,
-          importerFile: file,
-          listenerRegistryFile,
-          files,
-        })
-      ) {
+      if (referencesCentral) {
         centralListenerRegistryReferenced = true;
       }
+      if (!hasSafeListenerRegistrationLifecycle(call, sourceFile)) {
+        unsafeLifecycleFiles.add(file);
+      }
     }
 
-    if (foundCall) {
+    if (foundRelevantCall) {
       wiringFile ??= file;
     } else if (!eventBusFile && /\bcreate\w*EventBus\s*\(/.test(source)) {
       eventBusFile = file;
@@ -4807,7 +5162,368 @@ async function listenerWiringReferences(
     }
   }
 
-  return { identifiers, wiringFile, eventBusFile };
+  return {
+    identifiers,
+    wiringFile,
+    eventBusFile,
+    unsafeLifecycleFiles: [...unsafeLifecycleFiles].sort(),
+  };
+}
+
+type ListenerLifecycleHook =
+  | ts.MethodDeclaration
+  | ts.FunctionExpression
+  | ts.ArrowFunction;
+
+interface ListenerLifecycleTarget {
+  text: string;
+  binding?: ts.Node;
+}
+
+function registerListenersCalls(
+  sourceFile: ts.SourceFile,
+  bindings: ReadonlySet<string>,
+): ts.CallExpression[] {
+  const calls: ts.CallExpression[] = [];
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isCallExpression(node) &&
+      ((ts.isIdentifier(node.expression) &&
+        bindings.has(node.expression.text)) ||
+        (ts.isPropertyAccessExpression(node.expression) &&
+          node.expression.name.text === "registerListeners" &&
+          ts.isIdentifier(node.expression.expression) &&
+          bindings.has(`${node.expression.expression.text}.*`)))
+    ) {
+      calls.push(node);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return calls;
+}
+
+function importedRegisterListenersBindings(
+  source: string,
+  namedImports: Map<string, { importedName: string; sourcePath: string }>,
+): Set<string> {
+  const bindings = new Set<string>();
+  for (const [localName, imported] of namedImports) {
+    if (
+      imported.importedName === "registerListeners" &&
+      imported.sourcePath === "@beignet/core/events"
+    ) {
+      bindings.add(localName);
+    }
+  }
+  const namespaceImport =
+    /import\s+\*\s+as\s+([A-Za-z_$][\w$]*)\s+from\s+["']@beignet\/core\/events["']/g;
+  for (const match of source.matchAll(namespaceImport)) {
+    bindings.add(`${match[1]}.*`);
+  }
+  return bindings;
+}
+
+function hasSafeListenerRegistrationLifecycle(
+  call: ts.CallExpression,
+  sourceFile: ts.SourceFile,
+): boolean {
+  const startHook = enclosingListenerLifecycleHook(call, "start");
+  const target = listenerRegistrationTarget(call, sourceFile);
+  if (!startHook || !target) return false;
+  const lifecycleOwner = listenerLifecycleOwner(startHook);
+  if (!lifecycleOwner) return false;
+
+  let observesReadiness = false;
+  let observesCleanup = false;
+  const visit = (node: ts.Node): void => {
+    if (
+      !observesReadiness &&
+      ts.isPropertyAccessExpression(node) &&
+      node.name.text === "ready" &&
+      listenerLifecycleTargetsMatch(
+        listenerLifecycleTarget(node.expression, sourceFile),
+        target,
+      ) &&
+      enclosingListenerLifecycleHook(node, "start") === startHook &&
+      listenerLifecyclePromiseIsObserved(node, startHook)
+    ) {
+      observesReadiness = true;
+    }
+
+    if (
+      !observesCleanup &&
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      node.expression.name.text === "unsubscribe" &&
+      listenerLifecycleTargetsMatch(
+        listenerLifecycleTarget(node.expression.expression, sourceFile),
+        target,
+      )
+    ) {
+      const stopHook = enclosingListenerLifecycleHook(node, "stop");
+      if (
+        stopHook &&
+        listenerLifecycleOwner(stopHook) === lifecycleOwner &&
+        listenerLifecyclePromiseIsObserved(node, stopHook)
+      ) {
+        observesCleanup = true;
+      }
+    }
+
+    if (!observesReadiness || !observesCleanup) {
+      ts.forEachChild(node, visit);
+    }
+  };
+  visit(lifecycleOwner);
+  return observesReadiness && observesCleanup;
+}
+
+function listenerRegistrationTarget(
+  call: ts.CallExpression,
+  sourceFile: ts.SourceFile,
+): ListenerLifecycleTarget | undefined {
+  let expression: ts.Expression = call;
+  while (
+    ts.isParenthesizedExpression(expression.parent) ||
+    ts.isAsExpression(expression.parent) ||
+    ts.isSatisfiesExpression(expression.parent) ||
+    ts.isNonNullExpression(expression.parent)
+  ) {
+    expression = expression.parent;
+  }
+
+  const parent = expression.parent;
+  if (
+    ts.isVariableDeclaration(parent) &&
+    parent.initializer === expression &&
+    ts.isIdentifier(parent.name)
+  ) {
+    return { text: parent.name.text, binding: parent };
+  }
+  if (
+    ts.isBinaryExpression(parent) &&
+    parent.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+    parent.right === expression
+  ) {
+    return listenerLifecycleTarget(parent.left, sourceFile);
+  }
+  return undefined;
+}
+
+function listenerLifecycleTarget(
+  expression: ts.Expression,
+  sourceFile: ts.SourceFile,
+): ListenerLifecycleTarget | undefined {
+  let current = expression;
+  while (
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isSatisfiesExpression(current) ||
+    ts.isNonNullExpression(current)
+  ) {
+    current = current.expression;
+  }
+  if (!ts.isIdentifier(current) && !ts.isPropertyAccessExpression(current)) {
+    return undefined;
+  }
+
+  return {
+    text: current.getText(sourceFile),
+    binding: listenerLifecycleRootIdentifier(current)
+      ? resolveListenerLifecycleBinding(
+          listenerLifecycleRootIdentifier(current) as ts.Identifier,
+        )
+      : undefined,
+  };
+}
+
+function listenerLifecycleRootIdentifier(
+  expression: ts.Identifier | ts.PropertyAccessExpression,
+): ts.Identifier | undefined {
+  let current: ts.Expression = expression;
+  while (ts.isPropertyAccessExpression(current)) {
+    current = current.expression;
+  }
+  return ts.isIdentifier(current) ? current : undefined;
+}
+
+function resolveListenerLifecycleBinding(
+  identifier: ts.Identifier,
+): ts.Node | undefined {
+  let current: ts.Node | undefined = identifier;
+  while (current) {
+    if (ts.isBlock(current) || ts.isSourceFile(current)) {
+      for (const statement of current.statements) {
+        if (!ts.isVariableStatement(statement)) continue;
+        for (const declaration of statement.declarationList.declarations) {
+          if (
+            ts.isIdentifier(declaration.name) &&
+            declaration.name.text === identifier.text
+          ) {
+            return declaration;
+          }
+        }
+      }
+    }
+
+    if (ts.isFunctionLike(current)) {
+      for (const parameter of current.parameters) {
+        if (
+          ts.isIdentifier(parameter.name) &&
+          parameter.name.text === identifier.text
+        ) {
+          return parameter;
+        }
+      }
+    }
+
+    if (
+      ts.isCatchClause(current) &&
+      current.variableDeclaration &&
+      ts.isIdentifier(current.variableDeclaration.name) &&
+      current.variableDeclaration.name.text === identifier.text
+    ) {
+      return current.variableDeclaration;
+    }
+    current = current.parent;
+  }
+  return undefined;
+}
+
+function listenerLifecycleTargetsMatch(
+  left: ListenerLifecycleTarget | undefined,
+  right: ListenerLifecycleTarget,
+): boolean {
+  return (
+    left?.text === right.text &&
+    (left.binding !== undefined || right.binding !== undefined
+      ? left.binding === right.binding
+      : true)
+  );
+}
+
+function enclosingListenerLifecycleHook(
+  node: ts.Node,
+  hookName: "start" | "stop",
+): ListenerLifecycleHook | undefined {
+  let current: ts.Node | undefined = node.parent;
+  while (current) {
+    if (ts.isMethodDeclaration(current)) {
+      return staticPropertyName(current.name) === hookName
+        ? current
+        : undefined;
+    }
+    if (ts.isFunctionExpression(current) || ts.isArrowFunction(current)) {
+      const parent = current.parent;
+      return ts.isPropertyAssignment(parent) &&
+        staticPropertyName(parent.name) === hookName
+        ? current
+        : undefined;
+    }
+    if (ts.isFunctionDeclaration(current)) return undefined;
+    current = current.parent;
+  }
+  return undefined;
+}
+
+function listenerLifecycleOwner(
+  hook: ListenerLifecycleHook,
+): ts.ObjectLiteralExpression | undefined {
+  if (ts.isMethodDeclaration(hook)) {
+    return ts.isObjectLiteralExpression(hook.parent) ? hook.parent : undefined;
+  }
+  const property = hook.parent;
+  return ts.isPropertyAssignment(property) &&
+    ts.isObjectLiteralExpression(property.parent)
+    ? property.parent
+    : undefined;
+}
+
+function listenerLifecyclePromiseIsObserved(
+  node: ts.Node,
+  hook: ListenerLifecycleHook,
+): boolean {
+  let current: ts.Node | undefined = node;
+  while (current && current !== hook) {
+    const parent: ts.Node = current.parent;
+    if (
+      (ts.isAwaitExpression(parent) && parent.expression === current) ||
+      (ts.isReturnStatement(parent) && parent.expression === current)
+    ) {
+      return true;
+    }
+    if (
+      ts.isParenthesizedExpression(parent) ||
+      ts.isAsExpression(parent) ||
+      ts.isSatisfiesExpression(parent) ||
+      ts.isNonNullExpression(parent)
+    ) {
+      current = parent;
+      continue;
+    }
+    if (
+      ts.isPropertyAccessExpression(parent) &&
+      parent.expression === current
+    ) {
+      const method = parent.name.text;
+      const invocation = parent.parent;
+      if (
+        !["then", "catch", "finally"].includes(method) ||
+        !ts.isCallExpression(invocation) ||
+        invocation.expression !== parent ||
+        method === "catch" ||
+        (method === "then" && invocation.arguments.length > 1)
+      ) {
+        return false;
+      }
+      current = invocation;
+      continue;
+    }
+    return false;
+  }
+  return false;
+}
+
+function callReferencesFeatureListenerRegistry(args: {
+  callIdentifiers: Set<string>;
+  namedImports: Map<string, { importedName: string; sourcePath: string }>;
+  importerFile: string;
+  files: string[];
+  listenerRegistries: FeatureWorkflowRegistry[];
+}): boolean {
+  for (const identifier of args.callIdentifiers) {
+    for (const registry of args.listenerRegistries) {
+      if (
+        identifier === registry.registryName ||
+        registry.members.includes(identifier)
+      ) {
+        return true;
+      }
+    }
+
+    const imported = args.namedImports.get(identifier);
+    if (!imported) continue;
+    const importedFile = sourceFileFromImport(
+      imported.sourcePath,
+      args.importerFile,
+      args.files,
+    );
+    if (!importedFile) continue;
+
+    for (const registry of args.listenerRegistries) {
+      if (
+        (imported.importedName === registry.registryName &&
+          importedFile === registry.indexFile) ||
+        (registry.members.includes(imported.importedName) &&
+          (importedFile === registry.indexFile ||
+            registry.memberFiles.get(imported.importedName) === importedFile))
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
 }
 
 function callReferencesCentralListenerRegistry(args: {
@@ -5086,6 +5802,56 @@ async function appHasOutboxDrainEntrypoint(
   return false;
 }
 
+async function inspectOutboxJobDispatcherDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+): Promise<InspectDiagnostic[]> {
+  if (!hasOutboxRegistry(files, config)) return [];
+
+  const source = await readFile(
+    path.join(targetDir, config.paths.outbox),
+    "utf8",
+  );
+  const jobsState = outboxRegistryEntryState(source, "jobs");
+  if (jobsState === "absent" || jobsState === "empty") return [];
+
+  const analysis = await analyzePortWiringFiles({ targetDir, files, config });
+  const declaresJobs = analysis.declared.has("jobs");
+  const wiresJobs = analysis.bound.has("jobs") || analysis.deferred.has("jobs");
+  if (declaresJobs && wiresJobs) return [];
+
+  const file =
+    jobsState === "indeterminate"
+      ? config.paths.outbox
+      : !declaresJobs
+        ? config.paths.ports
+        : config.paths.portWiring;
+  const reason = !analysis.portsFileExists
+    ? `${config.paths.ports} does not exist at the configured path`
+    : !declaresJobs
+      ? analysis.declarationIndeterminate
+        ? `${config.paths.ports} does not expose a statically verifiable jobs declaration`
+        : `${config.paths.ports} does not declare a jobs port`
+      : !analysis.portWiringFileExists
+        ? `${config.paths.portWiring} does not exist at the configured path`
+        : analysis.indeterminate
+          ? `${config.paths.portWiring} does not expose statically verifiable jobs wiring`
+          : `${config.paths.portWiring} does not bind or defer the jobs port`;
+
+  return [
+    {
+      severity: "warning",
+      code: "BEIGNET_OUTBOX_JOB_DISPATCHER_MISSING",
+      file,
+      message:
+        jobsState === "indeterminate"
+          ? `The jobs entries in the outbox registry at ${config.paths.outbox} could not be statically resolved, and ${reason}. Keep the jobs property explicit so doctor can verify it, or add jobs: JobDispatcherPort to AppPorts and bind it directly or list "jobs" as deferred with an inline or provider-backed dispatcher. If the app uses custom paths, configure paths.ports and paths.portWiring in beignet.config.ts.`
+          : `The outbox registry in ${config.paths.outbox} contains jobs, but ${reason}. Add jobs: JobDispatcherPort to AppPorts and bind it directly or list "jobs" as deferred with an inline or provider-backed dispatcher. If the app uses custom paths, configure paths.ports and paths.portWiring in beignet.config.ts.`,
+    },
+  ];
+}
+
 async function inspectPortProviderDrift(
   targetDir: string,
   files: string[],
@@ -8384,8 +9150,9 @@ async function contractsFromRoutesSource(
     source,
     routeIdentifier,
   );
+  const { contracts } = await readContracts(targetDir, files, config);
   const registeredContracts = contractsForRegisteredRouteGroups(
-    await readContracts(targetDir, files, config),
+    contracts,
     routeGroups,
     registeredGroups,
   );