@wairon/cli 5.1.1-dev.63 → 5.1.1-dev.65

package/dist/cli/index.js

@@ -65,7 +65,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.1.1-dev.63";
+    WAIRON_VERSION = "5.1.1-dev.65";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     SUPPORTED_ALIASES = ["wai"];
     SCAN_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
@@ -2376,6 +2376,23 @@ var init_specs = __esm({
        * name — e.g. a store's `put` realized by `saveSnapshot`.
        */
       symbol: import_zod8.z.string().optional(),
+      /**
+       * The exported binding a consumer imports to REACH this method, when the
+       * realization is published as a value that COMPOSES it rather than exported
+       * in its own right — a rule module publishes `callConformanceRule`, and the
+       * method is the `check` inside it.
+       *
+       * `symbol` cannot say this: it names the code-level name REALIZING the
+       * contract method — the function itself — so a file whose whole published
+       * surface is the composing value publishes a name no contract mentions, and
+       * the surface check reads an unpromised export where the design has a
+       * promised one. Naming the handle here is what closes that gap.
+       *
+       * A declaration, never a waiver: a handle the method's own source file
+       * does not actually export is reported (UNREALIZED_EXPORT_HANDLE) and
+       * allows nothing, so the field can never become a free-text suppression.
+       */
+      exportedVia: import_zod8.z.string().optional(),
       /** Opaque pack/tool extension data (see ExtDataSchema) — preserved verbatim. */
       ext: ExtDataSchema.optional()
     });
@@ -2406,6 +2423,24 @@ var init_specs = __esm({
        * stereotypes should bind tech directly (TECH_ON_LOGIC_COMPONENT).
        */
       technologies: import_zod8.z.array(import_zod8.z.string()).optional(),
+      /**
+       * The parameter names THIS realization takes BEFORE the ones its contract
+       * declares — a config object, a data root, the transport handles a portal is
+       * handed. Supplied by whatever wires the component up, never by the caller
+       * the contract describes, which is why they belong to the realization and
+       * not to the contract: another realization of the same contract may hold
+       * them as fields instead.
+       *
+       * Declared rather than guessed, because a leading parameter the contract
+       * does not name is otherwise indistinguishable from one it named under a
+       * different name — `seed(config)` realized as `bootstrapInstance(cfg)` reads
+       * as a dropped parameter to anything that infers. A leading parameter this
+       * list does not name is a finding (UNDECLARED_PARAM), and only a LEADING run
+       * is dropped: one of these names appearing after the contract's own
+       * parameters is not wiring, it is an argument in the middle of the caller's
+       * list.
+       */
+      injectedParams: import_zod8.z.array(import_zod8.z.string()).optional(),
       methods: import_zod8.z.array(MethodImplementationSchema).default([]).superRefine((methods, ctx) => {
         methods.forEach((m, i) => {
           if (!m.calls?.length || m.narrative.length === 0) return;
@@ -8861,7 +8896,7 @@ function buildCodeIndex(model) {
     const f = facts.get(path71);
     return f?.status === "analyzed" && f.analysisGrade === "exact" ? { path: path71, facts: f } : void 0;
   };
-  const originOf = (site, from) => {
+  const originOf2 = (site, from) => {
     const resolved = scopeOf2(site, from);
     if (!resolved) return NO_ORIGIN;
     const { path: scope, facts: f } = resolved;
@@ -8882,7 +8917,7 @@ function buildCodeIndex(model) {
     return NO_ORIGIN;
   };
   const possibleOriginsOf = (site, from) => {
-    const proven = originOf(site, from);
+    const proven = originOf2(site, from);
     if (!site.field && !site.constructed && !site.via) return proven;
     const resolved = scopeOf2(site, from);
     if (!resolved) return proven;
@@ -8906,7 +8941,7 @@ function buildCodeIndex(model) {
     declarationsAt,
     anchorsAt: (path71) => namesAt(anchors, pathKey(path71), (f) => /* @__PURE__ */ new Set([...f.declaredNames, ...f.exportedNames, ...f.anchoredNames])),
     findingAnchorsAt: (path71) => namesAt(findingAnchors, pathKey(path71), (f) => new Set(f.anchoredNames)),
-    originOf,
+    originOf: originOf2,
     possibleOriginsOf
   };
 }
@@ -13962,6 +13997,274 @@ var init_type_realization = __esm({
   }
 });
 
+// src/core/rules/conformance/type-shape.ts
+function originOf(shape) {
+  if (shape.origin === "derived") return "derived shape";
+  return shape.inherited ? "declared shape (which extends another)" : "declared shape";
+}
+function absence(optional) {
+  return optional ? "may be absent" : "is always there";
+}
+var typeShapeRule;
+var init_type_shape = __esm({
+  "src/core/rules/conformance/type-shape.ts"() {
+    "use strict";
+    init_models();
+    typeShapeRule = {
+      name: "type-shape",
+      description: "Code-to-contract for the DATA: a type spec's `fields` are compared, name by name, against the shape its `sourcePath` actually declares. `typeRealization` asks whether a type EXISTS in code; nothing asked whether it is the shape the spec claims, so a type spec could describe two fields of a six-field record \u2014 and call the two that are optional required \u2014 straight through a lock and a CI gate, while the ERD, the agent briefs and every implementer read it as truth. That is the worst of the code-to-spec gaps, because a wrong signature eventually breaks at a call site and a type spec that lies is only ever read by humans and agents. Two origins answer at exact grade: a DECLARED shape, whose members the file lists, and a DERIVED one, an alias followed one hop to the object literal its schema is built from, where the keys are the members. A shape that extends another is judged on what it shows and never on what it omits, since its inherited members are not in this file to count.",
+      codes: [
+        {
+          code: "UNREALIZED_TYPE_FIELD",
+          defaultSeverity: "warning",
+          summary: "A type spec declares a field the shape at its sourcePath does not carry \u2014 the spec describes data the code does not have, and every reader of the ERD and the briefs has been told it exists",
+          // Measured code↔spec drift, field by field, at a site the finding names
+          // — which is why every one of them hands over `parts`.
+          carryable: true
+        },
+        {
+          code: "UNDECLARED_TYPE_FIELD",
+          defaultSeverity: "warning",
+          summary: "The shape at a type's sourcePath carries a field the type spec does not declare \u2014 data the design never described, so no diagram draws it and no brief hands it to an implementer",
+          carryable: true
+        },
+        {
+          code: "TYPE_FIELD_OPTIONALITY",
+          defaultSeverity: "warning",
+          summary: "A type spec and the shape at its sourcePath disagree about whether a field may be absent \u2014 one of them is telling a reader the data is guaranteed when it is not, or the reverse",
+          carryable: true
+        }
+      ],
+      check(ctx) {
+        const code = ctx.codeIndex();
+        for (const type of ctx.types) {
+          if (!type.sourcePath) continue;
+          if (type.subsystem && ctx.isInChainedSubproject(type.subsystem)) continue;
+          const file = pathKey(type.sourcePath);
+          const facts = code.factsAt(file);
+          if (!facts || facts.status !== "analyzed" || facts.analysisGrade !== "exact") continue;
+          const symbol = type.symbol ?? type.name;
+          const shapes = facts.typeShapes;
+          if (!shapes || !Object.prototype.hasOwnProperty.call(shapes, symbol)) continue;
+          const shape = shapes[symbol];
+          const specFields = type.fields ?? [];
+          const specFieldNames = new Set(specFields.map((field) => field.name));
+          const specMethodNames = new Set((type.methods ?? []).map((method2) => method2.name));
+          const codeFields = new Map(shape.fields.map((field) => [field.name, field.optional]));
+          const codeMethodNames = new Set(shape.methods);
+          const unrealized = shape.inherited ? [] : specFields.filter((field) => !codeFields.has(field.name) && !codeMethodNames.has(field.name)).map((field) => field.name);
+          if (unrealized.length > 0) {
+            ctx.addIssue(
+              "warning",
+              "UNREALIZED_TYPE_FIELD",
+              `Type "${type.id}" declares ${unrealized.length} field(s) the ${originOf(shape)} "${symbol}" in "${file}" does not carry \u2014 ${unrealized.map((name) => `"${name}"`).join(", ")}. The spec is describing data the code does not have, and nothing breaks at a call site to correct it: the ERD draws those fields and every brief hands them to an implementer as if they were there. Add them to the code, or drop them from the type.`,
+              type.id,
+              void 0,
+              void 0,
+              { at: symbol, covers: unrealized }
+            );
+          }
+          const undeclared = shape.inherited ? [] : shape.fields.filter((field) => !specFieldNames.has(field.name) && !specMethodNames.has(field.name)).map((field) => field.name);
+          if (undeclared.length > 0) {
+            ctx.addIssue(
+              "warning",
+              "UNDECLARED_TYPE_FIELD",
+              `The ${originOf(shape)} "${symbol}" in "${file}" carries ${undeclared.length} field(s) type "${type.id}" does not declare \u2014 ${undeclared.map((name) => `"${name}"`).join(", ")}. Data the design never described is data no diagram draws and no brief hands to an implementer, which is how a record grows past the model of it without anyone deciding to. Model the field, or take it out of the shape.`,
+              type.id,
+              void 0,
+              void 0,
+              { at: symbol, covers: undeclared }
+            );
+          }
+          const disagreed = specFields.filter((field) => {
+            const absentable = codeFields.get(field.name);
+            return absentable !== void 0 && absentable !== !!field.optional;
+          });
+          if (disagreed.length > 0) {
+            const told = disagreed.map((field) => `"${field.name}" (the spec says it ${absence(!!field.optional)}, the code says it ${absence(!!codeFields.get(field.name))})`).join("; ");
+            ctx.addIssue(
+              "warning",
+              "TYPE_FIELD_OPTIONALITY",
+              `Type "${type.id}" and the ${originOf(shape)} "${symbol}" in "${file}" disagree about whether ${disagreed.length} field(s) may be absent \u2014 ${told}. One of them is telling a reader the data is guaranteed when it is not, or the reverse. Absent-able is the code's word for it \u2014 a wrapper that lets the key be missing \u2014 and a wrapper that FILLS a missing key leaves the field required in the value the type finally holds, which is the shape the spec describes.`,
+              type.id,
+              void 0,
+              void 0,
+              { at: symbol, covers: disagreed.map((field) => field.name) }
+            );
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/core/rules/conformance/param-conformance.ts
+function omittable(optional) {
+  return optional ? "may be left out" : "is required";
+}
+function unitOf2(parameter, position) {
+  return parameter.name ?? `#${position + 1}`;
+}
+function judge(declared, realized, injected, typeAgrees) {
+  let wiring = 0;
+  while (wiring < realized.length && realized[wiring].name !== void 0 && injected.has(realized[wiring].name)) wiring++;
+  const taken = realized.slice(wiring);
+  const matched = Math.min(declared.length, taken.length);
+  const found = {
+    unrealized: /* @__PURE__ */ new Map(),
+    undeclared: /* @__PURE__ */ new Map(),
+    renamed: /* @__PURE__ */ new Map(),
+    optionality: /* @__PURE__ */ new Map()
+  };
+  for (const param of declared.slice(matched)) {
+    found.unrealized.set(param.name, { unit: param.name, told: `"${param.name}"` });
+  }
+  taken.slice(matched).forEach((param, index) => {
+    const unit = unitOf2(param, wiring + matched + index);
+    found.undeclared.set(unit, { unit, told: `"${unit}"` });
+  });
+  for (let position = 0; position < matched; position++) {
+    const param = declared[position];
+    const at = taken[position];
+    if (at.name !== void 0 && at.name !== param.name && typeAgrees(param, at)) {
+      found.renamed.set(`${param.name}\u2192${at.name}`, {
+        unit: param.name,
+        told: `"${param.name}" (the code calls it "${at.name}")`
+      });
+    }
+    if (!!param.optional !== at.optional) {
+      found.optionality.set(`${param.name}:${at.optional}`, {
+        unit: param.name,
+        told: `"${param.name}" (the contract says it ${omittable(!!param.optional)}, the code says it ${omittable(at.optional)})`
+      });
+    }
+  }
+  return found;
+}
+function agreed(judgements, reading) {
+  const [first, ...rest] = judgements;
+  return [...first[reading]].filter(([fact]) => rest.every((other) => other[reading].has(fact))).map(([, finding]) => finding);
+}
+var paramConformanceRule;
+var init_param_conformance = __esm({
+  "src/core/rules/conformance/param-conformance.ts"() {
+    "use strict";
+    init_models();
+    paramConformanceRule = {
+      name: "param-conformance",
+      description: "Code-to-contract for the SIGNATURE, the last of the three readings a spec-driven gate never made: a contract declares `params`, and nothing ever compared them to the parameters of the function that realizes the method. A contract could promise an argument the code does not take, take one the contract never mentions \u2014 including a secret \u2014 or name the same argument two different things, and the brief handed to an implementer would carry the contract's version. Parameters are matched by POSITION against the tail of the realization's list, and the declared type is what tells a rename from a dropped argument: `seed(config: HostConfig)` realized as `bootstrapInstance(cfg: HostConfig)` is one parameter under two names, which anything matching on names alone reads as a parameter the code lost. What a realization takes BEFORE the contract's own parameters is wiring, and it is declared on the implementation as `injectedParams` rather than inferred, because an inferred prefix cannot be told from a renamed first argument. A method the named file only CALLS is left to `methodRealization`, which already reports that the body is not here.",
+      codes: [
+        {
+          code: "UNREALIZED_PARAM",
+          defaultSeverity: "warning",
+          summary: "A contract declares a parameter the function realizing the method does not take \u2014 the contract promises an argument that would go nowhere, and every brief and caller built from it passes one",
+          // Measured code↔spec drift, parameter by parameter, at a site the
+          // finding names — which is why every one of them hands over `parts`.
+          carryable: true
+        },
+        {
+          code: "UNDECLARED_PARAM",
+          defaultSeverity: "warning",
+          summary: "The realizing function takes a parameter no contract parameter names and no declared injection accounts for \u2014 an argument a caller must supply that the design never mentions",
+          carryable: true
+        },
+        {
+          code: "PARAM_NAME_MISMATCH",
+          defaultSeverity: "warning",
+          summary: "A contract parameter and the one realizing it agree on position and type but not on name \u2014 the contract, the ERD and every brief say one word while the code says another",
+          carryable: true
+        },
+        {
+          code: "PARAM_OPTIONALITY",
+          defaultSeverity: "warning",
+          summary: "A contract and its realization disagree about whether a parameter may be left out \u2014 one of them is telling a caller an argument is required when it is not, or the reverse",
+          carryable: true
+        }
+      ],
+      check(ctx) {
+        const code = ctx.codeIndex();
+        const codeNameOf = /* @__PURE__ */ new Map();
+        for (const type of ctx.types) {
+          const named = type.symbol ?? type.name;
+          codeNameOf.set(type.id, named);
+          if (type.subsystem) codeNameOf.set(`${type.subsystem}.${type.id}`, named);
+        }
+        const normalize3 = (text2) => text2.replace(/\s+/g, " ").trim();
+        const typeAgrees = (declared, realized) => {
+          if (!realized.type) return false;
+          const stated = normalize3(declared.type);
+          return stated === realized.type || codeNameOf.get(stated) === realized.type;
+        };
+        for (const { implementation, method: method2, sourceFile, draftContext } of ctx.implementationMethods()) {
+          const contract = ctx.interfaceMap.get(implementation.contract);
+          const declared = contract?.methods.find((m) => m.name === method2.name)?.params ?? [];
+          if (declared.length === 0 || !sourceFile) continue;
+          const file = pathKey(sourceFile);
+          const facts = code.factsAt(file);
+          if (!facts || facts.status !== "analyzed" || facts.analysisGrade !== "exact") continue;
+          const symbol = method2.symbol ?? method2.name;
+          const signatures = facts.functionParams;
+          if (!signatures || !Object.prototype.hasOwnProperty.call(signatures, symbol)) continue;
+          const candidates = signatures[symbol];
+          if (candidates.length === 0) continue;
+          const injected = new Set(implementation.injectedParams ?? []);
+          const judgements = candidates.map((realized) => judge(declared, realized, injected, typeAgrees));
+          const subject = candidates.length > 1 ? `every function called "${symbol}" in "${file}"` : `the function "${symbol}" in "${file}"`;
+          const opening = subject.charAt(0).toUpperCase() + subject.slice(1);
+          const unrealized = agreed(judgements, "unrealized");
+          if (unrealized.length > 0) {
+            ctx.addIssue(
+              "warning",
+              "UNREALIZED_PARAM",
+              `Method "${method2.name}" of contract "${implementation.contract}" declares ${unrealized.length} parameter(s) ${subject} does not take \u2014 ${unrealized.map((found) => found.told).join(", ")}. The contract is promising an argument that would go nowhere, and nothing breaks at a call site to correct it: every brief and every caller built from the contract passes one. Take the parameter in the code, or drop it from the contract.`,
+              implementation.id,
+              draftContext,
+              void 0,
+              { at: method2.name, covers: unrealized.map((found) => found.unit) }
+            );
+          }
+          const undeclared = agreed(judgements, "undeclared");
+          if (undeclared.length > 0) {
+            ctx.addIssue(
+              "warning",
+              "UNDECLARED_PARAM",
+              `${opening} realizing method "${method2.name}" of contract "${implementation.contract}" takes ${undeclared.length} parameter(s) the contract does not declare and no declared injection accounts for \u2014 ${undeclared.map((found) => found.told).join(", ")}. An argument a caller must supply that the design never mentions is how a credential ends up in a signature nobody has read against its contract. Declare it on the contract, name it in the implementation's \`injectedParams\` when whatever wires this component up supplies it (a LEADING run only), or take it out of the signature.`,
+              implementation.id,
+              draftContext,
+              void 0,
+              { at: method2.name, covers: undeclared.map((found) => found.unit) }
+            );
+          }
+          const renamed = agreed(judgements, "renamed");
+          if (renamed.length > 0) {
+            ctx.addIssue(
+              "warning",
+              "PARAM_NAME_MISMATCH",
+              `Method "${method2.name}" of contract "${implementation.contract}" and ${subject} agree on position and type but not on name for ${renamed.length} parameter(s) \u2014 ${renamed.map((f) => f.told).join("; ")}. The contract, the ERD and every brief carry one word and the code answers to another, which is a rename nobody recorded rather than a different argument \u2014 the declared type agreeing is what says so. Rename one side to the other.`,
+              implementation.id,
+              draftContext,
+              void 0,
+              { at: method2.name, covers: renamed.map((found) => found.unit) }
+            );
+          }
+          const disagreed = agreed(judgements, "optionality");
+          if (disagreed.length > 0) {
+            ctx.addIssue(
+              "warning",
+              "PARAM_OPTIONALITY",
+              `Method "${method2.name}" of contract "${implementation.contract}" and ${subject} disagree about whether ${disagreed.length} parameter(s) may be left out \u2014 ${disagreed.map((f) => f.told).join("; ")}. One of them is telling a caller an argument is required when it is not, or the reverse. Omittable is the code's word for it: a default value and a rest parameter make an argument omittable exactly as a question mark does.`,
+              implementation.id,
+              draftContext,
+              void 0,
+              { at: method2.name, covers: disagreed.map((found) => found.unit) }
+            );
+          }
+        }
+      }
+    };
+  }
+});
+
 // src/core/rules/conformance/unclaimed-source.ts
 var unclaimedSourceRule;
 var init_unclaimed_source = __esm({
@@ -14015,6 +14318,133 @@ var init_unclaimed_source = __esm({
   }
 });
 
+// src/core/rules/conformance/export-conformance.ts
+var NOTHING_PROMISED, exportConformanceRule;
+var init_export_conformance = __esm({
+  "src/core/rules/conformance/export-conformance.ts"() {
+    "use strict";
+    init_models();
+    NOTHING_PROMISED = /* @__PURE__ */ new Set();
+    exportConformanceRule = {
+      name: "export-conformance",
+      description: "Code-to-contract for the SURFACE: does this file publish anything the components it realizes never promised, that another component then takes? The rest of the conformance set reads contract-to-code \u2014 it asks whether the code holds what a spec claims \u2014 so a file could export whatever it liked under a component's name and nothing looked. That is one half of the same hole as a contract promising a parameter it never passes. A method's `exportedVia` names the export a consumer imports to REACH it \u2014 the value that composes it, which `symbol` cannot name because `symbol` names the function inside \u2014 and a declared handle the file does not actually export is itself a finding, so naming one can never become a free-text suppression. Both questions are asked only of a file read at exact grade, and a taker counts only when its own import specifier resolves to the file it is accused of taking from: below that nothing separates an export from a mention, or a shared word from a shared module.",
+      codes: [
+        {
+          code: "UNDECLARED_EXPORT",
+          defaultSeverity: "warning",
+          summary: "A file realizing a component exports a name no contract of that component declares, and a file realizing a DIFFERENT component imports it \u2014 a surface reached across a boundary that the design never promised",
+          // Measured code-to-spec drift at a site the finding names, so the
+          // debt register may carry it — which is why it hands over `parts`.
+          carryable: true
+        },
+        {
+          code: "UNREALIZED_EXPORT_HANDLE",
+          defaultSeverity: "warning",
+          summary: "An implementation method declares an `exportedVia` handle its own source file does not export \u2014 the spec names a published route to the method that nobody can import"
+          // Deliberately NOT carryable, and so it hands over no `parts`: a wrong
+          // handle is one string to correct, and a parking space for it could
+          // only ever be a parking space for a lie.
+        }
+      ],
+      check(ctx) {
+        const code = ctx.codeIndex();
+        const realization = ctx.realizationIndex();
+        const promised = /* @__PURE__ */ new Map();
+        const promise = (file, name) => {
+          if (!name) return;
+          const key = pathKey(file);
+          let names = promised.get(key);
+          if (!names) promised.set(key, names = /* @__PURE__ */ new Set());
+          names.add(name);
+        };
+        for (const file of realization.paths) {
+          for (const component of realization.componentsAt(file)) {
+            for (const method2 of ctx.interfaceMethodsOf(component.id)) promise(file, method2.name);
+            for (const impl of realization.implementationsOf(component.id)) {
+              for (const method2 of impl.methods ?? []) {
+                promise(file, method2.name);
+                promise(file, method2.symbol);
+              }
+            }
+          }
+        }
+        for (const { implementation, method: method2, sourceFile, draftContext } of ctx.implementationMethods()) {
+          const handle = method2.exportedVia;
+          if (!handle || !sourceFile) continue;
+          const file = pathKey(sourceFile);
+          const facts = code.factsAt(file);
+          if (!facts || facts.status !== "analyzed" || facts.analysisGrade !== "exact") continue;
+          if (facts.exportedNames.includes(handle)) {
+            promise(file, handle);
+            continue;
+          }
+          ctx.addIssue(
+            "warning",
+            "UNREALIZED_EXPORT_HANDLE",
+            `Method "${method2.name}" in implementation "${implementation.id}" declares exportedVia "${handle}", but "${file}" exports no such name. A handle names the export a consumer imports to REACH the method \u2014 the value that composes it, which \`symbol\` cannot name because \`symbol\` names the function inside \u2014 so one the file does not publish promises a route nobody can import. It allows nothing either: every export of this file is still read against the contracts. Name the binding the file actually exports, export it, or drop the handle.`,
+            implementation.id,
+            draftContext
+          );
+        }
+        for (const type of ctx.types) {
+          if (!type.sourcePath) continue;
+          promise(type.sourcePath, type.symbol ?? type.name);
+          for (const method2 of type.methods ?? []) {
+            promise(method2.sourcePath ?? type.sourcePath, method2.symbol ?? method2.name);
+          }
+        }
+        const takenFrom = /* @__PURE__ */ new Map();
+        for (const consumer of realization.paths) {
+          if (!code.exactPaths.has(consumer)) continue;
+          for (const [local, binding] of Object.entries(code.factsAt(consumer)?.importBindings ?? {})) {
+            if (binding.namespace) continue;
+            const target = resolveImport(consumer, binding.from, code.paths);
+            if (!target) continue;
+            let names = takenFrom.get(target);
+            if (!names) takenFrom.set(target, names = /* @__PURE__ */ new Map());
+            for (const name of [local, binding.imported]) {
+              if (!name) continue;
+              let takers = names.get(name);
+              if (!takers) names.set(name, takers = /* @__PURE__ */ new Set());
+              takers.add(consumer);
+            }
+          }
+        }
+        for (const file of realization.paths) {
+          const facts = code.factsAt(file);
+          if (!facts || facts.status !== "analyzed" || facts.analysisGrade !== "exact") continue;
+          const declared = promised.get(file) ?? NOTHING_PROMISED;
+          const taken = takenFrom.get(file);
+          const owners = new Set(realization.componentsAt(file).map((c) => c.id));
+          const crossed = [];
+          for (const name of [...new Set(facts.exportedNames)].sort()) {
+            if (declared.has(name)) continue;
+            const takers = taken?.get(name);
+            if (!takers) continue;
+            const crossing = [...takers].some(
+              (taker) => taker !== file && !realization.componentsAt(taker).some((c) => owners.has(c.id))
+            );
+            if (crossing) crossed.push(name);
+          }
+          if (crossed.length === 0) continue;
+          const [owner] = realization.implementationsAt(file).map((impl) => impl.id).sort();
+          ctx.addIssue(
+            "warning",
+            "UNDECLARED_EXPORT",
+            `Source file "${file}" publishes ${crossed.length} name(s) that no contract of the component(s) it realizes (${[...owners].sort().map((id) => `"${id}"`).join(", ")}) declares, and a file realizing NONE of those components imports each one FROM HERE \u2014 ${crossed.map((n) => `"${n}"`).join(", ")}. An export only this file's own components use is the module's private factoring and no concern of the design; one another component reaches for is a surface the design never promised. Declare it as a contract method, stop exporting it, or move it to the component that owns the name.`,
+            owner,
+            void 0,
+            void 0,
+            // The crossings themselves, named the way the message names them, so
+            // a register entry written for today's set cannot carry tomorrow's.
+            { at: file, covers: crossed }
+          );
+        }
+      }
+    };
+  }
+});
+
 // src/core/rules/conformance/carried-debt.ts
 var carriedDebtRule;
 var init_carried_debt = __esm({
@@ -15338,7 +15768,10 @@ var init_repository = __esm({
     init_integration_sim_wiring();
     init_integration_sim_coverage();
     init_type_realization();
+    init_type_shape();
+    init_param_conformance();
     init_unclaimed_source();
+    init_export_conformance();
     init_carried_debt();
     init_coupling_health();
     init_signature_language_builtins();
@@ -15504,11 +15937,17 @@ var init_repository = __esm({
       integrationSimFileRule,
       integrationSimWiringRule,
       integrationSimCoverageRule,
-      // The data model's own claim on code, and the question no spec can ask
-      // from the spec side: which files are named by nothing at all. Last in
-      // the family because the second one reads what all the others named.
+      // The data model's own claim on code — does the file hold the type, and is
+      // it the SHAPE the spec claims — then the SIGNATURE, the third reading:
+      // does the code take the arguments the contract promises. And then the
+      // question no spec can ask from the spec side: which files are named by
+      // nothing at all. Last in the family because that one reads what all the
+      // others named.
       typeRealizationRule,
+      typeShapeRule,
+      paramConformanceRule,
       unclaimedSourceRule,
+      exportConformanceRule,
       couplingRule,
       // Target-language fit in two questions: what a CONTRACT may name, and what
       // a NARRATIVE may describe.
@@ -15674,7 +16113,11 @@ function walkExact(ts, sourceText, fileName) {
   const typeOnlyBindings = /* @__PURE__ */ new Map();
   const fieldTypes = /* @__PURE__ */ new Map();
   const localTypes = /* @__PURE__ */ new Map();
+  const typeShapes = /* @__PURE__ */ new Map();
+  const functionParams = /* @__PURE__ */ new Map();
   const mutableBindings = /* @__PURE__ */ new Set();
+  const schemaConstants = /* @__PURE__ */ new Map();
+  const derivedAliases = [];
   const receiverKey = (site) => site.via ?? (site.field ? `this.${site.field}` : site.constructed ? `new ${site.constructed}` : "");
   const siteKey = (site) => `${site.member ? "m" : "b"}:${receiverKey(site)}:${site.name}`;
   const addBindingNames = (name) => {
@@ -15708,6 +16151,79 @@ function walkExact(ts, sourceText, fileName) {
     named.add(typeName);
     localTypes.set(name.text, named);
   };
+  const recordDeclaredShape = (name, members, inherited) => {
+    const fields = [];
+    const methods = [];
+    for (const member of members) {
+      const memberName = member.name ? propertyNameText(member.name) : void 0;
+      if (!memberName) continue;
+      if (ts.isMethodSignature(member) || ts.isMethodDeclaration(member) || ts.isGetAccessorDeclaration(member)) {
+        methods.push(memberName);
+      } else if (ts.isPropertySignature(member) || ts.isPropertyDeclaration(member)) {
+        fields.push({ name: memberName, optional: !!member.questionToken });
+      }
+    }
+    const shape = { origin: "declared", fields, methods };
+    if (inherited) shape.inherited = true;
+    typeShapes.set(name, shape);
+  };
+  const inferredSchemaConstant = (type) => {
+    if (!ts.isTypeReferenceNode(type)) return void 0;
+    const reference = ts.isIdentifier(type.typeName) ? type.typeName.text : ts.isQualifiedName(type.typeName) ? type.typeName.right.text : void 0;
+    if (reference !== "infer") return void 0;
+    const [argument] = type.typeArguments ?? [];
+    if (!argument || !ts.isTypeQueryNode(argument) || !ts.isIdentifier(argument.exprName)) return void 0;
+    return argument.exprName.text;
+  };
+  const baseObjectLiteral = (expression) => {
+    let node = expression;
+    const walked = /* @__PURE__ */ new Set();
+    while (node && !walked.has(node)) {
+      walked.add(node);
+      if (ts.isCallExpression(node)) {
+        const callee = node.expression;
+        if (ts.isPropertyAccessExpression(callee) && callee.name.text === "object") {
+          const literal = node.arguments.find((argument) => ts.isObjectLiteralExpression(argument));
+          if (literal) return literal;
+        }
+        node = callee;
+      } else if (ts.isPropertyAccessExpression(node)) {
+        node = node.expression;
+      } else break;
+    }
+    return void 0;
+  };
+  const chainedCombinators = (expression) => {
+    const applied = /* @__PURE__ */ new Set();
+    let node = expression;
+    const walked = /* @__PURE__ */ new Set();
+    while (node && !walked.has(node)) {
+      walked.add(node);
+      if (ts.isCallExpression(node)) {
+        const callee = node.expression;
+        if (ts.isPropertyAccessExpression(callee)) applied.add(callee.name.text);
+        node = callee;
+      } else if (ts.isPropertyAccessExpression(node)) {
+        node = node.expression;
+      } else break;
+    }
+    return applied;
+  };
+  const schemaMembers = (literal) => {
+    const fields = [];
+    for (const property of literal.properties) {
+      const memberName = property.name ? propertyNameText(property.name) : void 0;
+      if (!memberName) continue;
+      if (ts.isShorthandPropertyAssignment(property)) {
+        fields.push({ name: memberName, optional: false });
+      } else if (ts.isPropertyAssignment(property)) {
+        const applied = chainedCombinators(property.initializer);
+        const optional = (applied.has("optional") || applied.has("nullish")) && !applied.has("default");
+        fields.push({ name: memberName, optional });
+      }
+    }
+    return fields;
+  };
   const hasExportModifier = (node) => {
     const mods = node.modifiers;
     return !!mods?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
@@ -15728,6 +16244,14 @@ function walkExact(ts, sourceText, fileName) {
     }
     return void 0;
   };
+  const declaredParameters = (fn) => (fn.parameters ?? []).map((parameter) => {
+    const fact = {
+      optional: !!parameter.questionToken || !!parameter.initializer || !!parameter.dotDotDotToken
+    };
+    if (ts.isIdentifier(parameter.name)) fact.name = parameter.name.text;
+    if (parameter.type) fact.type = parameter.type.getText(sf).replace(/\s+/g, " ").trim();
+    return fact;
+  });
   const collectFunctionFacts = (fn) => {
     let score = 1;
     const callees = /* @__PURE__ */ new Map();
@@ -15770,12 +16294,32 @@ function walkExact(ts, sourceText, fileName) {
       const sites = calls.get(fnName) ?? /* @__PURE__ */ new Map();
       for (const [key, site] of facts.callees) sites.set(key, site);
       calls.set(fnName, sites);
+      const signatures = functionParams.get(fnName) ?? [];
+      signatures.push(declaredParameters(node));
+      functionParams.set(fnName, signatures);
     }
     if (ts.isPropertyDeclaration(node)) recordFieldType(node.name, node.type);
     else if (ts.isParameter(node) && node.parent && ts.isConstructorDeclaration(node.parent) && isParameterProperty(node)) {
       recordFieldType(node.name, node.type);
     }
     if (ts.isParameter(node) || ts.isVariableDeclaration(node)) recordLocalType(node.name, node.type);
+    if (ts.isInterfaceDeclaration(node)) {
+      recordDeclaredShape(node.name.text, node.members, (node.heritageClauses?.length ?? 0) > 0);
+    } else if (ts.isClassDeclaration(node) && node.name) {
+      const extendsOther = (node.heritageClauses ?? []).some(
+        (clause) => clause.token === ts.SyntaxKind.ExtendsKeyword
+      );
+      recordDeclaredShape(node.name.text, node.members, extendsOther);
+    } else if (ts.isTypeAliasDeclaration(node)) {
+      if (ts.isTypeLiteralNode(node.type)) recordDeclaredShape(node.name.text, node.type.members, false);
+      else {
+        const constant = inferredSchemaConstant(node.type);
+        if (constant) derivedAliases.push({ name: node.name.text, constant });
+      }
+    }
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && !schemaConstants.has(node.name.text)) {
+      schemaConstants.set(node.name.text, node.initializer);
+    }
     if (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) || ts.isEnumDeclaration(node) || ts.isModuleDeclaration(node)) {
       const name = node.name && ts.isIdentifier(node.name) ? node.name.text : void 0;
       if (name) {
@@ -15851,8 +16395,16 @@ function walkExact(ts, sourceText, fileName) {
     ts.forEachChild(node, visit);
   };
   visit(sf);
+  for (const alias of derivedAliases) {
+    if (typeShapes.has(alias.name)) continue;
+    const initializer = schemaConstants.get(alias.constant);
+    if (!initializer) continue;
+    const literal = baseObjectLiteral(initializer);
+    if (!literal) continue;
+    typeShapes.set(alias.name, { origin: "derived", fields: schemaMembers(literal), methods: [] });
+  }
   const reexportOnly = sf.statements.length > 0 && sf.statements.every((st) => ts.isExportDeclaration(st) && !!st.moduleSpecifier);
-  return { declared, anchors, exported, imports, reexports, starExports, namedReexports, complexity, calls, importBindings, typeOnlyBindings, fieldTypes, localTypes, mutableBindings, reexportOnly };
+  return { declared, anchors, exported, imports, reexports, starExports, namedReexports, complexity, calls, importBindings, typeOnlyBindings, fieldTypes, localTypes, typeShapes, functionParams, mutableBindings, reexportOnly };
 }
 function resolveRelativeModule(fromFile, specifier) {
   if (!specifier.startsWith(".")) return null;
@@ -16034,6 +16586,8 @@ function buildCodeModel(implementations, types, projectRoot2, sourceRoots = [],
             typeOnlyBindings: Object.fromEntries(facts.typeOnlyBindings),
             fieldTypes: Object.fromEntries([...facts.fieldTypes].map(([k, v]) => [k, [...v]])),
             localTypes: Object.fromEntries([...facts.localTypes].map(([k, v]) => [k, [...v]])),
+            typeShapes: Object.fromEntries(facts.typeShapes),
+            functionParams: Object.fromEntries(facts.functionParams),
             topLevelMutableBindings: [...facts.mutableBindings],
             reexportOnly: facts.reexportOnly
           };
@@ -29639,6 +30193,7 @@ function createMcpServer(options = {}) {
     intent: import_zod11.z.string().optional().describe("detail: intent \u2014 behavioral prose (what it does and how it fails); substitute for a narrative"),
     conformance: conformanceEnum.optional().describe("Conformance tier for this method (overrides the spec default)"),
     symbol: import_zod11.z.string().optional().describe("Code-level name realizing this contract method in the sourcePath file, when it legitimately differs from the intent-language contract name (e.g. put realized by saveSnapshot)"),
+    exportedVia: import_zod11.z.string().optional().describe("The exported binding a consumer imports to REACH this method, when the realization is published as a value that composes it rather than exported in its own right (a rule module publishes callConformanceRule, and the method is the check inside it). Not symbol, which names the function itself: this names the route to it, so the surface check reads that export as promised. A handle the method's own source file does not actually export is reported (UNREALIZED_EXPORT_HANDLE) and allows nothing"),
     ext: import_zod11.z.record(import_zod11.z.unknown()).optional().describe("Opaque pack/tool extension data for this method (namespaced keys) \u2014 preserved verbatim"),
     narrative: import_zod11.z.array(narrativeStepInput).optional(),
     calls: import_zod11.z.array(import_zod11.z.string().min(1)).optional().describe('The calls this method makes, when its narrative does not show them (detail: intent, or calls-only with no steps authored) \u2014 each as "<component>.<method>", the spelling the debt register and lint allows name a unit with. The narrative walk takes exactly these edges and no others, so an undeclared collaborator is NOT reached: this is what keeps unused-detection honest at a lower detail dial. Each entry is validated like a call step (the component resolves, this component declares it, the method is on its contract). Refused beside a non-empty narrative \u2014 add the call step there instead')
@@ -29652,6 +30207,7 @@ function createMcpServer(options = {}) {
     sourcePath: import_zod11.z.string().optional().describe("Optional: target source code file path relative to project root \u2014 for a chained subproject's implementation (qualified id), relative to that subproject's root; a path given relative to this root that lands inside the subproject is re-expressed for you"),
     simPath: import_zod11.z.string().optional().describe("Optional: the committed integration-sim harness file (project-relative; N:1 sharing allowed). The validator proves it exists and its import graph wires the REAL modules (this component + each direct dependency; technology adapters may stay faked) \u2014 running it is CI's job. Declaring the first simPath in a subsystem activates MISSING_INTEGRATION_SIM for its other complete non-leaf implementations"),
     technologies: import_zod11.z.array(import_zod11.z.string()).optional().describe(`External technologies this implementation binds to (e.g. ["mysql"]) \u2014 declares this component's ownership tree as the technology's home; references outside it are flagged (TECH_LEAKAGE) and contract identifiers must stay intent-language. Only for Adapter/Store/Registry/Index components.`),
+    injectedParams: import_zod11.z.array(import_zod11.z.string()).optional().describe("The parameter names this realization takes BEFORE the ones its contract declares \u2014 a config object, a data root, the transport handles a portal is handed. Supplied by whatever wires the component up, never by the caller the contract describes, which is why they belong here and not to the contract: another realization may hold them as fields instead. Declared rather than guessed, because a leading parameter the contract does not name cannot be told from one it named under a different name (`seed(config)` realized as `bootstrapInstance(cfg)`); a leading parameter this list does not name is reported (UNDECLARED_PARAM). Only a LEADING run is dropped \u2014 one of these names appearing after the contract's own parameters is an argument in the middle of the caller's list, not wiring"),
     detail: detailEnum.optional().describe("Spec-level narrative detail default for all methods"),
     conformance: conformanceEnum.optional().describe("Spec-level conformance tier default: declared | anchored | off (omitted = stereotype default: Portal \u2192 anchored, else declared)"),
     methods: import_zod11.z.array(import_zod11.z.object(implMethodShape).strict()).optional().describe("Method implementations containing L5 narratives"),
@@ -29662,11 +30218,11 @@ function createMcpServer(options = {}) {
     server,
     "sdd_write_narrative",
     {
-      description: "Write L4 Concrete Implementation spec containing L5 method narratives. Narratives are a FLAT ordered step list; flow steps (branch/switch/loop/try/parallel/jump/return/throw) jump by step number \u2014 blocks are just skipped regions. Steps may declare a `label` anchor, and every jump field has a *Label twin (toLabel, onTrueLabel, endLabel, \u2026) resolved to step numbers at write time \u2014 prefer labels over hand-counted numbers; an unresolvable label rejects the write. Detail dial per method: full (narrative required) | calls-only (call choreography suffices) | intent (prose instead of steps); omitted = stereotype default (Portal/Observer/Adapter: calls-only, Store/Index/Registry: intent, else full). A method whose narrative shows no steps declares the calls it makes in `calls` (one \"<component>.<method>\" each): the reachability walk takes exactly those edges and no others, so an intent-level method that reaches a collaborator must name it or that collaborator is reported unused. Conformance dial per method or spec: declared | anchored | off \u2014 how strictly structural conformance requires contract methods to be realized in their source file (omitted = Portal: anchored, else declared). A method whose body lives in its own file names it in the method's sourcePath; the implementation's sourcePath is the default for every method that names none. Re-authoring an existing id REPLACES the method list: a method left out of the input is REMOVED together with its narrative (and reported); spec-level lint/ext are carried forward, and the stored status is kept unless this input states a higher one. The answer carries a write receipt as structured content beside the sentence \u2014 the status written, whether a spec already held the id, and the notices a restatement raised, each as its own entry.",
+      description: "Write L4 Concrete Implementation spec containing L5 method narratives. Narratives are a FLAT ordered step list; flow steps (branch/switch/loop/try/parallel/jump/return/throw) jump by step number \u2014 blocks are just skipped regions. Steps may declare a `label` anchor, and every jump field has a *Label twin (toLabel, onTrueLabel, endLabel, \u2026) resolved to step numbers at write time \u2014 prefer labels over hand-counted numbers; an unresolvable label rejects the write. Detail dial per method: full (narrative required) | calls-only (call choreography suffices) | intent (prose instead of steps); omitted = stereotype default (Portal/Observer/Adapter: calls-only, Store/Index/Registry: intent, else full). A method whose narrative shows no steps declares the calls it makes in `calls` (one \"<component>.<method>\" each): the reachability walk takes exactly those edges and no others, so an intent-level method that reaches a collaborator must name it or that collaborator is reported unused. Conformance dial per method or spec: declared | anchored | off \u2014 how strictly structural conformance requires contract methods to be realized in their source file (omitted = Portal: anchored, else declared). A method whose body lives in its own file names it in the method's sourcePath; the implementation's sourcePath is the default for every method that names none. Parameters the realization takes BEFORE its contract's own \u2014 a config object, a data root, a portal's transport handles \u2014 are wiring, and are declared once for the spec in injectedParams; a leading parameter it does not name is reported against the contract (UNDECLARED_PARAM). Re-authoring an existing id REPLACES the method list: a method left out of the input is REMOVED together with its narrative (and reported); spec-level lint/ext are carried forward, and the stored status is kept unless this input states a higher one. The answer carries a write receipt as structured content beside the sentence \u2014 the status written, whether a spec already held the id, and the notices a restatement raised, each as its own entry.",
       inputSchema: implInput,
       outputSchema: specWriteReceiptOutput
     },
-    ({ id, name, description, contract, sourcePath, simPath, technologies, detail, conformance, methods, status: status2 }) => {
+    ({ id, name, description, contract, sourcePath, simPath, technologies, injectedParams, detail, conformance, methods, status: status2 }) => {
       try {
         const { loadInterfaceSpec: loadInterfaceSpec2, loadImplementationSpec: loadImplementationSpec2, saveImplementationSpec: saveImplementationSpec2 } = requireSpecs();
         const intf = loadInterfaceSpec2(contract);
@@ -29698,6 +30254,7 @@ function createMcpServer(options = {}) {
           sourcePath,
           simPath,
           technologies,
+          injectedParams,
           detail,
           conformance,
           // Post-resolution every cases/catches entry has its numeric step —