@specverse/engines 6.42.3 → 6.60.1

package/dist/libs/instance-factories/controllers/templates/fastify/routes-generator.js

@@ -9,7 +9,7 @@ function generateFastifyRoutes(context) {
   const routeName = controllerName || `${modelName}Controller`;
   const isModelController = !!modelName;
   const handlerName = isModelController ? `${modelName}Controller` : controllerName;
-  const imports = generateImports(controller, modelName, handlerName, isModelController, implType);
+  let imports;
   let endpoints = controller.endpoints;
   if (!endpoints || endpoints.length === 0) {
     if (controller.cured) {
@@ -41,13 +41,26 @@ function generateFastifyRoutes(context) {
   const externalEndpoints = endpoints?.filter((e) => e.external) || [];
   const internalHandlers = internalEndpoints.map((endpoint) => generateRouteHandler(endpoint, modelName, handlerName, isModelController, implType, controllerName)).join("\n\n");
   const externalHandlers = externalEndpoints.map((endpoint) => generateRouteHandler(endpoint, modelName, handlerName, isModelController, implType, controllerName)).join("\n\n");
-  const externalRoutesExport = externalEndpoints.length > 0 ? `
+  const hasInternalHandlers = internalEndpoints.length > 0;
+  const hasExternalHandlers = externalEndpoints.length > 0;
+  const handlersText = internalHandlers + "\n" + externalHandlers;
+  const usesFastifyRequest = /\bFastifyRequest\b/.test(handlersText);
+  const usesFastifyReply = /\bFastifyReply\b/.test(handlersText);
+  imports = generateImports(
+    controller,
+    modelName,
+    handlerName,
+    isModelController,
+    implType,
+    { usesFastifyRequest, usesFastifyReply }
+  );
+  const externalRoutesExport = hasExternalHandlers ? `
 /**
  * Mount the external (root-prefix) routes for this controller.
  *
  * Called by the generated main.ts at root scope (no prefix) so action.path
  * declarations like '/api/v2/auth/register' land at exactly that URL,
- * bypassing the controller's '/api/<plural>' prefix.
+ * bypassing the controller's '/api/<prefix>' prefix.
  */
 export async function registerExternalRoutes(
   fastify: FastifyInstance,
@@ -58,6 +71,11 @@ export async function registerExternalRoutes(
 ${externalHandlers.split("\n").map((line) => "  " + line).join("\n")}
 }
 ` : "";
+  const mainBody = hasInternalHandlers ? `  const handler = ${isModelController ? "options.controllers" : "options.services"}.${handlerName};
+
+${internalHandlers.split("\n").map((line) => "  " + line).join("\n")}` : "  // No endpoints declared on this controller \u2014 empty routes plugin.";
+  const mainFastifyParam = hasInternalHandlers ? "fastify" : "_fastify";
+  const mainOptionsParam = hasInternalHandlers ? "options" : "_options";
   return `${imports}
 
 /**
@@ -68,18 +86,19 @@ ${externalHandlers.split("\n").map((line) => "  " + line).join("\n")}
  * Operations: ${controller.endpoints?.map((e) => e.operation).join(", ") || "CURED"}
  */
 export default async function ${routeName.replace("Controller", "")}Routes(
-  fastify: FastifyInstance,
-  options: any
+  ${mainFastifyParam}: FastifyInstance,
+  ${mainOptionsParam}: any
 ) {
-  const handler = ${isModelController ? "options.controllers" : "options.services"}.${handlerName};
-
-${internalHandlers.split("\n").map((line) => "  " + line).join("\n")}
+${mainBody}
 }
 ${externalRoutesExport}`;
 }
-function generateImports(controller, modelName, handlerName, isModelController, implType) {
+function generateImports(_controller, modelName, _handlerName, _isModelController, implType, usage = { usesFastifyRequest: true, usesFastifyReply: true }) {
+  const fastifyTypes = ["FastifyInstance"];
+  if (usage.usesFastifyRequest) fastifyTypes.push("FastifyRequest");
+  if (usage.usesFastifyReply) fastifyTypes.push("FastifyReply");
   const imports = [
-    `import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';`
+    `import { ${fastifyTypes.join(", ")} } from 'fastify';`
   ];
   if (implType?.technology?.validation === "zod" && modelName) {
     imports.push(`import { ${modelName}Schema } from '../validation/${modelName}.schema.js';`);

package/dist/libs/instance-factories/services/templates/prisma/ai-behaviors-generator.js

@@ -246,13 +246,18 @@ async function generateAiBehaviorsFile(opts) {
       const fields = Object.entries(returns).map(([k, v]) => `${k}: ${v}`).join("; ");
       returnType = `{ ${fields} }`;
     }
+    const buildTestCode = (rawBody) => {
+      const { signature, destructure } = buildSignatureAndDestructure(rawBody);
+      const destructureLine = destructure ? destructure + "\n" : "";
+      return `export async function ${functionName}(${signature}): Promise<${returnType}> {
+${destructureLine}${rawBody}
+}`;
+    };
     const key = cacheKey(step, modelName, operationName, functionName, inputs);
     let body = cacheRead(key);
     let source = body ? "AI-CACHED" : "STUB";
     if (body) {
-      const testCode = `export async function ${functionName}(input: any): Promise<any> {
-${body}
-}`;
+      const testCode = buildTestCode(body);
       const syntaxError = await validateTypeScript(testCode);
       const typeError = syntaxError ? null : await validateTypeScriptTypes(testCode);
       const importError = syntaxError || typeError ? null : validateImports(testCode);
@@ -280,9 +285,7 @@ ${body}
           // Pass declared return type to Claude
         });
         if (body) {
-          const testCode = `export async function ${functionName}(input: any): Promise<any> {
-${body}
-}`;
+          const testCode = buildTestCode(body);
           const syntaxError = await validateTypeScript(testCode);
           if (syntaxError) {
             console.warn(`      [ai-validate] ${functionName} has syntax error: ${syntaxError}`);
@@ -324,9 +327,7 @@ ${retryHint}`,
                   returnType
                 });
                 if (retried) {
-                  const retryCode = `export async function ${functionName}(input: any): Promise<any> {
-${retried}
-}`;
+                  const retryCode = buildTestCode(retried);
                   const retrySyntaxError = await validateTypeScript(retryCode);
                   const retryTypeError = retrySyntaxError ? null : await validateTypeScriptTypes(retryCode);
                   const retryImportError = retrySyntaxError || retryTypeError ? null : validateImports(retryCode);

package/dist/libs/instance-factories/services/templates/prisma/behavior-generator.js

@@ -31,11 +31,31 @@ function generateBehaviorWithHelpers(behavior, opMeta, context) {
   );
   if (events) parts.push(events);
   let body = parts.join("\n\n");
+  body = renameUnusedFindUniqueBindings(body);
   if (behavior.transactional) {
     body = generateTransactionWrapper(body, context);
   }
   return { body, helperMethods, unmatchedSteps };
 }
+function renameUnusedFindUniqueBindings(body) {
+  const declRe = /\bconst\s+([a-zA-Z_][\w$]*)\s*=\s*await\s+prisma\.[\w.$]+\.findUniqueOrThrow\b/g;
+  const declared = [];
+  let m;
+  while ((m = declRe.exec(body)) !== null) declared.push(m[1]);
+  if (declared.length === 0) return body;
+  let out = body;
+  for (const name of declared) {
+    const refRe = new RegExp(`\\b${name}\\b`, "g");
+    const count = (out.match(refRe) ?? []).length;
+    if (count <= 2) {
+      out = out.replace(
+        new RegExp(`\\bconst\\s+${name}\\s*=\\s*(await\\s+prisma\\.)`),
+        `$1`
+      );
+    }
+  }
+  return out;
+}
 function generatePreconditionChecks(preconditions, context, declared) {
   if (preconditions.length === 0) return "";
   if (!declared) declared = /* @__PURE__ */ new Set();
@@ -155,13 +175,15 @@ function inferLogicFromOperationName(context) {
   const modelVar = prismaModel.charAt(0).toLowerCase() + prismaModel.slice(1);
   if (op.startsWith("handle")) {
     const event = op.replace("handle", "");
+    const eventParam = context.parameterNames?.[0] ?? "_event";
     return `    // Event handler: ${op}
-    console.log('[${context.serviceName}] Processing ${event}', params);
+    console.log('[${context.serviceName}] Processing ${event}', ${eventParam});
     return { handled: true, event: '${event}' };`;
   }
   if (op.startsWith("validate")) {
+    const idParam = context.parameterNames?.[0] ?? "id";
     return `    // Validation: ${op}
-    const records = await prisma.${modelVar}.findMany({ where: { id: params.id } });
+    const records = await prisma.${modelVar}.findMany({ where: { id: ${idParam} } });
     return { valid: records.length > 0, checked: records.length };`;
   }
   if (op.startsWith("get") || op.startsWith("list") || op.startsWith("find")) {

package/dist/libs/instance-factories/services/templates/prisma/controller-generator.js

@@ -19,34 +19,42 @@ function generatePrismaController(context) {
   const idType = idAttr?.type || "UUID";
   const needsIntParse = idType === "Integer" || idType === "Int" || idType === "Number";
   const customActions = generateCustomActions(controller, modelName, modelVar);
+  const classBody = [
+    generateValidateMethod(model, modelName),
+    curedOps.create ? generateCreateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels) : "",
+    curedOps.retrieve ? generateRetrieveMethod(model, modelName, modelVar, prismaDelegate) : "",
+    curedOps.update ? generateUpdateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels) : "",
+    curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, prismaDelegate, controller) : "",
+    curedOps.delete ? generateDeleteMethod(model, modelName, modelVar, prismaDelegate, controller) : "",
+    customActions.code
+  ].filter(Boolean).join("\n  ");
+  const usesPrisma = /\bprisma\b/.test(classBody);
+  const usesParseId = /\bparseId\(/.test(classBody);
+  const usesEventBus = /\beventBus\./.test(classBody);
+  const usesAiBehaviors = customActions.needsAiBehaviors;
+  const imports = [
+    usesPrisma ? `import { PrismaClient } from '@prisma/client';` : "",
+    usesEventBus ? `import { eventBus } from '../events/eventBus.js';` : "",
+    usesAiBehaviors ? `import * as aiBehaviors from '../behaviors/${modelName}Controller.ai.js';` : ""
+  ].filter(Boolean).join("\n");
+  const declarations = [
+    usesPrisma ? `const prisma = new PrismaClient();` : "",
+    usesParseId ? `/** Parse ID from string to the correct type for this model */
+function parseId(id: string): ${needsIntParse ? "number" : "string"} {
+  ${needsIntParse ? "return parseInt(id, 10);" : "return id;"}
+}` : ""
+  ].filter(Boolean).join("\n\n");
   return `/**
  * ${controllerName}
  * Model-specific business logic for ${modelName}
  * ${controller.description || ""}
  */
-
-import { PrismaClient } from '@prisma/client';
-${hasEventPublishing(curedOps, controller) ? `import { eventBus } from '../events/eventBus.js';` : ""}
-${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${modelName}Controller.ai.js';` : ""}
-
-const prisma = new PrismaClient();
-
-/** Parse ID from string to the correct type for this model */
-function parseId(id: string): ${needsIntParse ? "number" : "string"} {
-  ${needsIntParse ? "return parseInt(id, 10);" : "return id;"}
-}
-
-/**
+${imports ? "\n" + imports + "\n" : ""}
+${declarations ? declarations + "\n\n" : ""}/**
  * ${controllerName} class
  */
 export class ${controllerName} {
-  ${generateValidateMethod(model, modelName)}
-  ${curedOps.create ? generateCreateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels) : ""}
-  ${curedOps.retrieve ? generateRetrieveMethod(model, modelName, modelVar, prismaDelegate) : ""}
-  ${curedOps.update ? generateUpdateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels) : ""}
-  ${curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, prismaDelegate, controller) : ""}
-  ${curedOps.delete ? generateDeleteMethod(model, modelName, modelVar, prismaDelegate, controller) : ""}
-  ${customActions.code}
+  ${classBody}
 }
 
 // Export singleton instance

package/dist/normalise/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @specverse/engines/normalise — rule-based spec normalisation pass.
+ *
+ * Reshapes a faithful-extract spec (output of `analyse`) into a
+ * canonical SpecVerse-idiomatic form before inference/realize.
+ * Deterministic, manifest-driven, mirrors the realize-rules pattern.
+ *
+ * See `specverse-self/docs/proposals/2026-05-13-NORMALISE-PHASE.md`
+ * for the design + phasing.
+ */
+export { type NormaliseRule, type NormaliseRuleMatch, type NormaliseRuleResult, type NormaliseContext, type NormaliseSpec, RULES, rulesApplicableTo, getRule, } from './normalise-rules.js';
+export { runNormalise, type NormaliseRunResult, type NormaliseRunOptions, } from './runner.js';
+export { loadNormaliseOverrides, type NormaliseOverrides, } from './load-overrides.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/normalise/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/normalise/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,EACL,iBAAiB,EACjB,OAAO,GACR,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC"}

package/dist/normalise/index.js

@@ -0,0 +1,14 @@
+/**
+ * @specverse/engines/normalise — rule-based spec normalisation pass.
+ *
+ * Reshapes a faithful-extract spec (output of `analyse`) into a
+ * canonical SpecVerse-idiomatic form before inference/realize.
+ * Deterministic, manifest-driven, mirrors the realize-rules pattern.
+ *
+ * See `specverse-self/docs/proposals/2026-05-13-NORMALISE-PHASE.md`
+ * for the design + phasing.
+ */
+export { RULES, rulesApplicableTo, getRule, } from './normalise-rules.js';
+export { runNormalise, } from './runner.js';
+export { loadNormaliseOverrides, } from './load-overrides.js';
+//# sourceMappingURL=index.js.map

package/dist/normalise/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/normalise/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAML,KAAK,EACL,iBAAiB,EACjB,OAAO,GACR,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,GAGb,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,sBAAsB,GAEvB,MAAM,qBAAqB,CAAC"}

package/dist/normalise/load-overrides.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Load project-level normalise overrides from a `.normalise.json` file.
+ *
+ * Phase 5 of `2026-05-13-NORMALISE-PHASE.md`. Allows users to disable
+ * default-on rules or enable opt-in-only rules without editing engine
+ * code. The override file lives at the project root (the directory
+ * passed to `spv ai analyse <source>`).
+ *
+ * File shape:
+ *
+ *   {
+ *     "$schema": "https://specverse.dev/normalise.schema.json",
+ *     "disabled": ["cluster-module-functions", "drop-trivial-passthrough"],
+ *     "enabled":  ["some-opt-in-rule"]
+ *   }
+ *
+ * `disabled` lists rule IDs to skip even though they're enabled by
+ * default. `enabled` lists rule IDs to run even though they're opt-in.
+ * Both arrays are optional and default to empty.
+ *
+ * Unknown rule IDs produce a warning (returned via `warnings`) but
+ * don't fail the load — engine versions evolve and the user may have
+ * a config from a newer version. The runner skips unknown IDs silently.
+ */
+export interface NormaliseOverrides {
+    disabledRules: Set<string>;
+    enabledRules: Set<string>;
+    /** Path that was loaded (absolute), or null if no file existed. */
+    source: string | null;
+    /** Non-fatal issues — unknown rule IDs, malformed entries. Caller
+     *  surfaces these to the audit log so the user sees them. */
+    warnings: string[];
+}
+/**
+ * Load `.normalise.json` from `projectDir`. Returns empty sets when:
+ *   - the file doesn't exist (no overrides configured)
+ *   - the file is unreadable / not valid JSON / not the expected shape
+ *
+ * The function NEVER throws — analyse should proceed even when the
+ * config is broken. Errors land in `warnings`.
+ */
+export declare function loadNormaliseOverrides(projectDir: string): NormaliseOverrides;
+//# sourceMappingURL=load-overrides.d.ts.map

package/dist/normalise/load-overrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-overrides.d.ts","sourceRoot":"","sources":["../../src/normalise/load-overrides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,mEAAmE;IACnE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;iEAC6D;IAC7D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAID;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAuF7E"}

package/dist/normalise/load-overrides.js

@@ -0,0 +1,121 @@
+/**
+ * Load project-level normalise overrides from a `.normalise.json` file.
+ *
+ * Phase 5 of `2026-05-13-NORMALISE-PHASE.md`. Allows users to disable
+ * default-on rules or enable opt-in-only rules without editing engine
+ * code. The override file lives at the project root (the directory
+ * passed to `spv ai analyse <source>`).
+ *
+ * File shape:
+ *
+ *   {
+ *     "$schema": "https://specverse.dev/normalise.schema.json",
+ *     "disabled": ["cluster-module-functions", "drop-trivial-passthrough"],
+ *     "enabled":  ["some-opt-in-rule"]
+ *   }
+ *
+ * `disabled` lists rule IDs to skip even though they're enabled by
+ * default. `enabled` lists rule IDs to run even though they're opt-in.
+ * Both arrays are optional and default to empty.
+ *
+ * Unknown rule IDs produce a warning (returned via `warnings`) but
+ * don't fail the load — engine versions evolve and the user may have
+ * a config from a newer version. The runner skips unknown IDs silently.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { RULES } from './normalise-rules.js';
+const CONFIG_FILENAME = '.normalise.json';
+/**
+ * Load `.normalise.json` from `projectDir`. Returns empty sets when:
+ *   - the file doesn't exist (no overrides configured)
+ *   - the file is unreadable / not valid JSON / not the expected shape
+ *
+ * The function NEVER throws — analyse should proceed even when the
+ * config is broken. Errors land in `warnings`.
+ */
+export function loadNormaliseOverrides(projectDir) {
+    const empty = {
+        disabledRules: new Set(),
+        enabledRules: new Set(),
+        source: null,
+        warnings: [],
+    };
+    const configPath = join(projectDir, CONFIG_FILENAME);
+    if (!existsSync(configPath))
+        return empty;
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf8');
+    }
+    catch (err) {
+        return {
+            ...empty,
+            source: configPath,
+            warnings: [`Could not read ${CONFIG_FILENAME}: ${err?.message ?? String(err)}`],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            ...empty,
+            source: configPath,
+            warnings: [`${CONFIG_FILENAME} is not valid JSON: ${err?.message ?? String(err)}`],
+        };
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return {
+            ...empty,
+            source: configPath,
+            warnings: [`${CONFIG_FILENAME} must contain a JSON object at the top level`],
+        };
+    }
+    const config = parsed;
+    const warnings = [];
+    const knownIds = new Set(RULES.map((r) => r.id));
+    const disabledRules = new Set();
+    const enabledRules = new Set();
+    if ('disabled' in config) {
+        const disabled = config.disabled;
+        if (!Array.isArray(disabled)) {
+            warnings.push(`${CONFIG_FILENAME}: "disabled" must be an array of rule IDs (got ${typeof disabled})`);
+        }
+        else {
+            for (const id of disabled) {
+                if (typeof id !== 'string') {
+                    warnings.push(`${CONFIG_FILENAME}: entry in "disabled" is not a string (got ${typeof id})`);
+                    continue;
+                }
+                if (!knownIds.has(id)) {
+                    warnings.push(`${CONFIG_FILENAME}: unknown rule ID "${id}" in "disabled" (known: ${[...knownIds].join(', ')})`);
+                }
+                // We still add unknown IDs to the set — they're harmless (no
+                // rule with that ID will match) and the warning is enough.
+                disabledRules.add(id);
+            }
+        }
+    }
+    if ('enabled' in config) {
+        const enabled = config.enabled;
+        if (!Array.isArray(enabled)) {
+            warnings.push(`${CONFIG_FILENAME}: "enabled" must be an array of rule IDs (got ${typeof enabled})`);
+        }
+        else {
+            for (const id of enabled) {
+                if (typeof id !== 'string') {
+                    warnings.push(`${CONFIG_FILENAME}: entry in "enabled" is not a string (got ${typeof id})`);
+                    continue;
+                }
+                if (!knownIds.has(id)) {
+                    warnings.push(`${CONFIG_FILENAME}: unknown rule ID "${id}" in "enabled"`);
+                }
+                enabledRules.add(id);
+            }
+        }
+    }
+    return { disabledRules, enabledRules, source: configPath, warnings };
+}
+//# sourceMappingURL=load-overrides.js.map

package/dist/normalise/load-overrides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-overrides.js","sourceRoot":"","sources":["../../src/normalise/load-overrides.ts"],"names":[],"mappings":"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"}

package/dist/normalise/normalise-rules.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Normalise rule manifest.
+ *
+ * Single source of truth for every deterministic spec-reshape rule
+ * applied between analyse (faithful extraction) and inference. Mirrors
+ * the realize-rules manifest pattern (see `engines/src/realize/realize-rules.ts`):
+ * one declaration per rule, three consumers (runner, per-rule corpus,
+ * project-override loader).
+ *
+ * Phase 1a (engines 6.49.x) of the 2026-05-13-NORMALISE-PHASE proposal —
+ * INFRASTRUCTURE only. The RULES array is empty in this phase; the
+ * runner, manifest interface, and tests land first. Real rules
+ * (`cluster-module-functions`, `crud-into-curved`,
+ * `drop-trivial-passthrough`) land in Phase 2+.
+ *
+ * Why in engines/src/normalise/ (a new subsystem):
+ *   Normalise is its own phase between analyse and inference, with its
+ *   own pluggable rule set. Putting it under realize/ would conflate
+ *   two different rule-classes (one for post-LLM-emit validation, one
+ *   for pre-realize spec reshape). Following the entity-module
+ *   colocation principle (R12), normalise gets its own home.
+ */
+/**
+ * Normalise operates on the YAML-object representation of a spec
+ * (the output of `yaml.load(content)`), NOT the parsed NormaliseSpec.
+ * Reasons:
+ *
+ *   1. The YAML object mirrors the .specly file structure 1:1 (services
+ *      as object-keyed maps, not arrays with name fields). Renaming a
+ *      service key is one delete + one set; the AST form would need
+ *      an additional `name` field update.
+ *   2. There is no AST → .specly serialiser for the full NormaliseSpec
+ *      shape (only LogicalComponentSpec via SpeclyConverter, which is
+ *      a different inference-internal shape). YAML round-trip via
+ *      `yaml.load` + `yaml.dump` is the existing canonical path.
+ *   3. Normalise is structurally simple — rename / drop / rewrap. The
+ *      strong typing the AST provides isn't needed for these
+ *      transforms; each rule narrows the loose YAML object as needed.
+ *
+ * The shape is `{ components: { [name]: { services?: { [name]: { operations?: { [name]: any } } } } }, ... }`.
+ * `Record<string, unknown>` is intentional — Normalise rules MAY operate
+ * on top-level fields beyond `components` (e.g. `deployments`,
+ * `manifests`), and the YAML may carry extension fields the typed AST
+ * doesn't model.
+ */
+export type NormaliseSpec = Record<string, unknown>;
+/**
+ * Context passed to every rule. Drives applicability gates +
+ * provenance signals (e.g. "is this a hand-authored spec we should
+ * leave alone?").
+ */
+export interface NormaliseContext {
+    /**
+     * Where the spec originated. Normalise rules are NOT applied to
+     * hand-authored specs by default — those are already in the form the
+     * author intended. `'analyse'` indicates output from the analyse
+     * pipeline; `'create'` from the create flow; `'hand-authored'` is
+     * any user-edited spec.
+     *
+     * Loading default: orchestrator passes `'analyse'` when invoked
+     * from the analyse pipeline; CLI invocations default to
+     * `'hand-authored'` (which makes default-on rules no-op unless the
+     * user passes `--force`).
+     */
+    source: 'analyse' | 'create' | 'hand-authored' | 'normalised';
+    /**
+     * Project-level rule overrides loaded from `.normalise.json` (if
+     * present). When a rule's ID appears here, the runner skips it.
+     * Rule overrides are append-only — a user explicitly opting OUT.
+     */
+    disabledRules?: Set<string>;
+    /**
+     * Project-level rule overrides — explicit opt-IN for rules whose
+     * `enabledByDefault: false`.
+     */
+    enabledRules?: Set<string>;
+}
+/**
+ * A single match produced by a rule's `detect` phase. Carries enough
+ * detail for the transform step + audit-trail emission.
+ */
+export interface NormaliseRuleMatch {
+    /** Short human-language description for the audit log. */
+    description: string;
+    /**
+     * Free-form rule-private data — populated by `detect` and consumed
+     * by `transform`. The runner doesn't inspect this field. Used to
+     * carry e.g. "service-name candidates", "function-list to cluster",
+     * "entity to attach action to".
+     */
+    data?: unknown;
+}
+/**
+ * Result of running a rule's full pipeline (detect + transform) on
+ * one spec.
+ */
+export interface NormaliseRuleResult {
+    ruleId: string;
+    /** Number of matches detect() returned. */
+    matchCount: number;
+    /**
+     * Brief descriptions of what was transformed. One entry per match.
+     * Used by the audit-trail emission.
+     */
+    matches: Array<{
+        description: string;
+    }>;
+    /**
+     * Whether this rule was SKIPPED (e.g. disabled in overrides, or
+     * `appliesWhen` returned false). Skipped rules report `skipped: true`
+     * with `matchCount: 0`.
+     */
+    skipped: boolean;
+    /** Reason for skip when `skipped: true`. */
+    skipReason?: string;
+}
+/**
+ * One normalise rule. Each field has a single purpose:
+ *
+ *   - `id`: stable identifier for tests, audit, override config. Kebab-case.
+ *   - `summary`: one-line human description.
+ *   - `ordering`: pipeline position. Rules apply in ascending order.
+ *     Conventions:
+ *       0-9    foundational shape (clustering, container synthesis)
+ *       10-19  shape normalisation (CRUD → CURVED, etc.)
+ *       20-29  cleanup (passthrough drop, trivial-action drop)
+ *       30+    reserved for future categories
+ *   - `enabledByDefault`: whether the rule applies without explicit opt-in.
+ *     Default-on rules can be disabled in `.normalise.json`. Default-off
+ *     rules require explicit opt-in.
+ *   - `appliesWhen` (optional): predicate gating execution. Most rules
+ *     should skip hand-authored specs — check `ctx.source !== 'hand-authored'`.
+ *   - `detect`: scan spec, return zero+ matches. PURE — must not mutate
+ *     the input spec.
+ *   - `transform`: apply ONE match to the spec, returning the
+ *     transformed spec. The runner calls this once per match in the order
+ *     `detect` returned them. The implementation may mutate the input
+ *     spec in-place (the runner doesn't deep-clone between transforms);
+ *     downstream rules see the updated state.
+ */
+export interface NormaliseRule {
+    id: string;
+    summary: string;
+    ordering: number;
+    enabledByDefault: boolean;
+    appliesWhen?: (ctx: NormaliseContext) => boolean;
+    detect: (spec: NormaliseSpec, ctx: NormaliseContext) => NormaliseRuleMatch[];
+    transform: (spec: NormaliseSpec, match: NormaliseRuleMatch, ctx: NormaliseContext) => NormaliseSpec;
+}
+/**
+ * The canonical rule manifest. Append rules as they land. Order in
+ * the array is informational only — the runner sorts by `ordering`.
+ *
+ * Phase 2 of `2026-05-13-NORMALISE-PHASE.md` §5:
+ *   - `cluster-module-functions` (ordering 0): strip project-prefix
+ *     from services synthesised by the module-functions adapter.
+ *
+ * Remaining rules (Phase 3-4 in §5):
+ *   - `crud-into-curved`: collapse Service ops 1:1 with CURVED to entity
+ *   - `drop-trivial-passthrough`: drop single-delegate-call ops
+ */
+export declare const RULES: NormaliseRule[];
+/**
+ * Filter the manifest to rules applicable in `ctx`. Applies the
+ * standard inclusion logic in one place:
+ *
+ *   1. `disabledRules` in ctx wins — always skip.
+ *   2. `enabledByDefault: true` AND not in disabledRules → include.
+ *   3. `enabledByDefault: false` AND id is in enabledRules → include.
+ *   4. `appliesWhen` (when present) must return true.
+ *
+ * Returned rules are sorted by `ordering` ascending.
+ */
+export declare function rulesApplicableTo(ctx: NormaliseContext): NormaliseRule[];
+/**
+ * Find a rule by id. Returns undefined when no rule with that id is
+ * registered. Used by tests, project-override loaders, audit-trail
+ * emission.
+ */
+export declare function getRule(id: string): NormaliseRule | undefined;
+//# sourceMappingURL=normalise-rules.d.ts.map

package/dist/normalise/normalise-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalise-rules.d.ts","sourceRoot":"","sources":["../../src/normalise/normalise-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,eAAe,GAAG,YAAY,CAAC;IAC9D;;;;OAIG;IACH,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxC;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACjD,MAAM,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,gBAAgB,KAAK,kBAAkB,EAAE,CAAC;IAC7E,SAAS,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,kBAAkB,EAAE,GAAG,EAAE,gBAAgB,KAAK,aAAa,CAAC;CACrG;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,EAAE,aAAa,EAIhC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,GAAG,aAAa,EAAE,CAaxE;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE7D"}