@wairon/cli 5.1.1-dev.37 → 5.1.1-dev.39

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.37";
+    WAIRON_VERSION = "5.1.1-dev.39";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     SUPPORTED_ALIASES = ["wai"];
     SCAN_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
@@ -770,7 +770,7 @@ function activeTargetTypes(config) {
   const targets = config.targets;
   return targets.filter((t) => typeof t === "string" || t.enabled !== false).map((t) => typeof t === "string" ? t : t.type);
 }
-var import_zod4, BuiltinTargetConfigSchema, CustomTargetConfigSchema, TargetConfigSchema, NamingRuleConfigSchema, DocumentationRuleConfigSchema, ComplexityRuleConfigSchema, DesignDepthSchema, RulesConfigSchema, PathsConfigSchema, PackSelectionSchema, ProfileSelectionSubjectSchema, ProjectProfileSelectionSchema, ProjectConfigSchema;
+var import_zod4, BuiltinTargetConfigSchema, CustomTargetConfigSchema, TargetConfigSchema, NamingRuleConfigSchema, DocumentationRuleConfigSchema, ComplexityRuleConfigSchema, ConformanceRuleConfigSchema, DesignDepthSchema, RulesConfigSchema, PathsConfigSchema, PackSelectionSchema, ProfileSelectionSubjectSchema, ProjectProfileSelectionSchema, ProjectConfigSchema;
 var init_project = __esm({
   "src/models/project.ts"() {
     "use strict";
@@ -867,6 +867,30 @@ var init_project = __esm({
        */
       maxCognitiveLevel: import_zod4.z.string().optional()
     });
+    ConformanceRuleConfigSchema = import_zod4.z.object({
+      /**
+       * Project-relative paths holding this project's own source code; a
+       * directory is walked recursively, a file names itself. Absolute or
+       * parent-escaping entries are refused by containment, exactly as a
+       * sourcePath is.
+       */
+      sourceRoots: import_zod4.z.array(import_zod4.z.string()).optional(),
+      /**
+       * Paths inside a source root that are not this project's code to claim —
+       * vendored libraries, generated output, a chained subproject's own
+       * directory (the child claims its files in its own run). A file at, or
+       * under, one of these is never walked, so it is neither reported nor
+       * carried as debt.
+       */
+      exclude: import_zod4.z.array(import_zod4.z.string()).optional(),
+      /**
+       * The files under the source roots that no spec names yet, frozen. A listed
+       * file is not reported; an unlisted one is UNCLAIMED_SOURCE_FILE; an entry
+       * that is now claimed, proven a barrel, or no longer found is
+       * STALE_UNCLAIMED_ENTRY.
+       */
+      unclaimed: import_zod4.z.array(import_zod4.z.string()).optional()
+    });
     DesignDepthSchema = import_zod4.z.enum(["components", "interfaces", "implementations", "narratives"]);
     RulesConfigSchema = import_zod4.z.object({
       /**
@@ -917,6 +941,8 @@ var init_project = __esm({
       documentation: DocumentationRuleConfigSchema.optional(),
       /** Dynamic structural complexity caps (method limit, step limit, dependency limit) */
       complexity: ComplexityRuleConfigSchema.optional(),
+      /** Where this project's own source lives and what of it no spec claims yet (see ConformanceRuleConfigSchema) */
+      conformance: ConformanceRuleConfigSchema.optional(),
       /** Project-default design depth (see DesignDepthSchema); subsystems may override. */
       designDepth: DesignDepthSchema.optional()
     });
@@ -1228,6 +1254,15 @@ function implementationSourceFiles(impl) {
   for (const method2 of impl.methods ?? []) add(method2.sourcePath);
   return files;
 }
+function typeSourceFiles(type) {
+  const files = [];
+  const add = (file) => {
+    if (file && !files.includes(file)) files.push(file);
+  };
+  add(type.sourcePath);
+  for (const method2 of type.methods ?? []) add(method2.sourcePath);
+  return files;
+}
 var import_zod7, SpecIdSchema, SpecStatusSchema, BoundaryItemSchema, RequirementItemSchema, DatabaseSpecSchema, DiagramConfigSchema, SURFACE_AUDIENCES, SurfaceAudienceSchema, SystemPublicInterfaceSchema, SystemSpecSchema, PublicInterfaceTypeSchema, PublicInterfaceSchema, TrustedLinkSchema, LintAllowSchema, LintConfigSchema, ExtDataSchema, LifecycleEntrypointSchema, SubsystemSpecSchema, ComponentTypeSchema, PATTERN_TYPES, RETIRED_STEREOTYPES, PortalTypeSchema, DispatchBindingSchema, DurabilitySchema, DependencyClassSchema, PatternRefSchema, EventBindingSchema, ExternalLinkTypeSchema, ExternalLinkSchema, PortalAuthSchemeSchema, PortalAuthSchema, ComponentSpecSchema, BLOCK_NOUNS, HttpMethodSchema, TransportSchema, EndpointSchema, SEMANTIC_GUARANTEES, GuaranteeSchema, MethodParamSchema, FindingDeclarationSchema, MethodSignatureSchema, INTENT_FLOOR_MIN_CHARS, InterfaceSpecSchema, NarrativeStepTypeSchema, LoopKindSchema, SwitchCaseSchema, CatchClauseSchema, ParallelBranchSchema, NarrativeStepSchema, NarrativeDetailSchema, ConformanceTierSchema, MethodImplementationSchema, ImplementationSpecSchema, TypeKindSchema, TypeFieldSchema, TypeMethodSchema, InvariantSchema, TypeSpecSchema, SurfaceOriginSchema, SurfaceTypeDefSchema, SurfaceContractEntrySchema, SurfaceSnapshotSchema, NamedOpenApiSpecSchema, GroupSpecSchema;
 var init_specs = __esm({
   "src/models/specs.ts"() {
@@ -1536,7 +1571,13 @@ var init_specs = __esm({
     GuaranteeSchema = import_zod7.z.string().min(1);
     MethodParamSchema = import_zod7.z.object({
       name: import_zod7.z.string(),
-      /** A primitive/builtin or a defined type id (qualified across subsystems, e.g. "billing.Invoice"). */
+      /**
+       * A primitive/builtin or a defined type id (qualified across subsystems, e.g.
+       * "billing.Invoice"), on its own or inside a generic, an array or a UNION:
+       * `Invoice | null`, `Promise<Invoice | null>`, `Invoice[] | null`. Every
+       * identifier the string names has to resolve — see the grammar on
+       * src/models/type-references.ts.
+       */
       type: import_zod7.z.string(),
       description: import_zod7.z.string().optional(),
       optional: import_zod7.z.boolean().optional()
@@ -1554,8 +1595,9 @@ var init_specs = __esm({
       description: import_zod7.z.string(),
       signature: import_zod7.z.string(),
       // e.g. "save(key: string, data: Buffer): Promise<void>"
+      // e.g. "Promise<void>", or a union: "Invoice | null" — the commonest shape in
+      // any real tree. See the grammar on src/models/type-references.ts.
       returns: import_zod7.z.string(),
-      // e.g. "Promise<void>"
       /** Structured parameters (authoritative for type checking when present). */
       params: import_zod7.z.array(MethodParamSchema).optional(),
       /** Concrete wire binding for this method when its component is a Portal (set via sdd_set_endpoints). */
@@ -1824,8 +1866,10 @@ var init_specs = __esm({
     TypeKindSchema = import_zod7.z.enum(["entity", "value-object"]);
     TypeFieldSchema = import_zod7.z.object({
       name: import_zod7.z.string(),
+      // A primitive, or another type id (qualified across subsystems, e.g.
+      // "billing.Invoice") — on its own or inside a generic, an array or a union
+      // ("Invoice[] | null"). See the grammar on src/models/type-references.ts.
       type: import_zod7.z.string(),
-      // a primitive, or another type id (qualified across subsystems, e.g. "billing.Invoice")
       description: import_zod7.z.string().optional(),
       optional: import_zod7.z.boolean().default(false),
       /**
@@ -1845,7 +1889,22 @@ var init_specs = __esm({
       name: import_zod7.z.string(),
       signature: import_zod7.z.string(),
       returns: import_zod7.z.string(),
-      description: import_zod7.z.string().optional()
+      description: import_zod7.z.string().optional(),
+      /**
+       * Source file realizing this method when it is not the type's own
+       * sourcePath. A type's pure methods routinely live apart from its
+       * declaration: the declaration is a struct or an interface, the methods are
+       * free functions, and a language without methods-on-data has nowhere else
+       * to put them.
+       */
+      sourcePath: import_zod7.z.string().optional(),
+      /**
+       * The code-level name realizing this method, when it legitimately differs
+       * from the method name — e.g. `narrative_step.foreignFields` realized by
+       * `narrativeStepForeignFields`, the free-function form a pure type method
+       * takes in a language whose data carries no methods.
+       */
+      symbol: import_zod7.z.string().optional()
     });
     InvariantSchema = import_zod7.z.object({
       /** Stable invariant id, unique within the entity (referenced as "<type-id>.<invariant-id>"). */
@@ -1890,6 +1949,23 @@ var init_specs = __esm({
        * logical system entity type it maps to.
        */
       linkedEntity: import_zod7.z.string().optional(),
+      /**
+       * The source file holding this type's declaration, and the default for
+       * every method that names no sourcePath of its own. Relative to the root of
+       * the project that holds the spec.
+       *
+       * Naming one turns the type into a CLAIM on code, judged exactly as an
+       * implementation's sourcePath is: the file must resolve, and the
+       * declaration must be anchored in it (UNREALIZED_TYPE). A type that names
+       * none claims nothing and is never reported.
+       */
+      sourcePath: import_zod7.z.string().optional(),
+      /**
+       * The code-level name realizing this type's declaration, when it
+       * legitimately differs from `name` — a type named "Invoice Line" declared
+       * as `InvoiceLine`.
+       */
+      symbol: import_zod7.z.string().optional(),
       /** Per-spec lint suppressions (see LintConfigSchema). */
       lint: LintConfigSchema.optional(),
       /** Opaque pack/tool extension data (see ExtDataSchema) — preserved verbatim. */
@@ -3683,11 +3759,11 @@ function buildCanvasModel(issues = []) {
     if (pi.component && pi.id) apiTagOf.set(pi.component, pi.id);
   }
   const patternTypes = /* @__PURE__ */ new Set(["Repository", "FeatureComponent", "RouterComponent"]);
-  const ownerOf = /* @__PURE__ */ new Map();
+  const ownerOf2 = /* @__PURE__ */ new Map();
   for (const comp of components) {
     if (!patternTypes.has(comp.componentType)) continue;
     for (const memberId of comp.owns) {
-      if (componentIds.has(memberId)) ownerOf.set(memberId, comp.id);
+      if (componentIds.has(memberId)) ownerOf2.set(memberId, comp.id);
     }
   }
   const modelComponents = components.map((comp) => {
@@ -3743,7 +3819,7 @@ function buildCanvasModel(issues = []) {
       ...comp.status ? { status: comp.status } : {},
       public: publicComponents.has(comp.id),
       ...apiTagOf.has(comp.id) ? { apiTag: apiTagOf.get(comp.id) } : {},
-      ...ownerOf.has(comp.id) ? { owner: ownerOf.get(comp.id) } : {},
+      ...ownerOf2.has(comp.id) ? { owner: ownerOf2.get(comp.id) } : {},
       owns: comp.owns.filter((o) => componentIds.has(o)),
       dependsOn: comp.dependsOn,
       ...comp.externalLinks && comp.externalLinks.length ? { externalLinks: comp.externalLinks } : {},
@@ -13333,9 +13409,9 @@ var init_dependency_conformance = __esm({
         };
         const mappedImplsOf = (compId) => realization.implementationsOf(compId).filter((impl) => implementationSourceFiles(impl).some((f) => isExact(pathKey(f))));
         const dependsOrOwns = (from, toId) => from.dependsOn.includes(toId) || (from.owns ?? []).includes(toId);
-        const ownerOf = /* @__PURE__ */ new Map();
+        const ownerOf2 = /* @__PURE__ */ new Map();
         for (const c of ctx.components) {
-          for (const member of c.owns ?? []) ownerOf.set(member, c);
+          for (const member of c.owns ?? []) ownerOf2.set(member, c);
         }
         const declaresSurfaceEdge = (from, subsystemId) => {
           const published = ctx.publicSet.get(subsystemId);
@@ -13348,9 +13424,9 @@ var init_dependency_conformance = __esm({
               if (cf.id === cg.id) return true;
               if (dependsOrOwns(cf, cg.id)) return true;
               if (cf.subsystem === cg.subsystem && dependsOrOwns(cg, cf.id) && (cg.componentType === "Portal" || cg.componentType === "Observer")) return true;
-              const ownerG = ownerOf.get(cg.id);
+              const ownerG = ownerOf2.get(cg.id);
               if (ownerG && (dependsOrOwns(cf, ownerG.id) || cf.id === ownerG.id)) return true;
-              const ownerF = ownerOf.get(cf.id);
+              const ownerF = ownerOf2.get(cf.id);
               if (ownerF && (dependsOrOwns(ownerF, cg.id) || ownerF.id === cg.id)) return true;
               if (ownerF && ownerG && ownerF.id === ownerG.id) return true;
               if (cf.subsystem !== cg.subsystem && declaresSurfaceEdge(cf, cg.subsystem)) return true;
@@ -13604,6 +13680,150 @@ var init_integration_sim_coverage = __esm({
   }
 });
 
+// src/core/rules/conformance/type-realization.ts
+function ownerOf(type, file) {
+  if (type.sourcePath && pathKey(type.sourcePath) === pathKey(file)) return `Type "${type.id}"`;
+  const users = (type.methods ?? []).filter((m) => m.sourcePath && pathKey(m.sourcePath) === pathKey(file)).map((m) => m.name);
+  if (users.length === 0) return `Type "${type.id}"`;
+  return `Type "${type.id}" method${users.length === 1 ? "" : "s"} ${users.map((n) => `"${n}"`).join(", ")}`;
+}
+var FILE_PROBLEMS, typeRealizationRule;
+var init_type_realization = __esm({
+  "src/core/rules/conformance/type-realization.ts"() {
+    "use strict";
+    init_models();
+    FILE_PROBLEMS = {
+      escaped: {
+        code: "SOURCE_PATH_ESCAPES_ROOT",
+        severity: "error",
+        detail: "is absolute or escapes the project root \u2014 sourcePaths must stay inside the project."
+      },
+      missing: {
+        code: "MISSING_SOURCE_FILE",
+        severity: "error",
+        detail: "does not resolve to a file \u2014 the spec names code that does not exist."
+      },
+      unreadable: {
+        code: "CONFORMANCE_ANALYSIS_SKIPPED",
+        severity: "warning",
+        detail: "could not be analyzed (binary or unreadable) \u2014 what it would have realized was not checked."
+      }
+    };
+    typeRealizationRule = {
+      name: "type-realization",
+      description: "Code\u2194spec Level 1 for the data model: a type that names a sourcePath is claiming code, so every file it names \u2014 its own and each method's \u2014 must resolve to a real, readable file inside the project root, its file must PUBLISH its declaration (an exported name at exact grade, the declaration tier below it, under its `symbol` when the code-level name differs from the type's name \u2014 and a pure re-export barrel publishes nothing of its own, so a claim on one is never realized), and each of its pure methods must appear in its own file (the method's sourcePath, else the type's) at the declaration tier, under the method's `symbol`, else the method's name. A type that names no sourcePath claims nothing and is never reported. Findings carry the analysis grade (exact AST | pattern table | generic scan) so weaker analysis is visible, a file that escapes the root, is missing or could not be analyzed is reported once and blocks only what it would have realized, and types under chained subsystems (projectPath) validate standalone in their own project run.",
+      codes: [
+        { code: "UNREALIZED_TYPE", defaultSeverity: "warning", summary: "A type names a sourcePath but its declaration is nowhere in that file \u2014 the claim points at code that does not hold it" },
+        { code: "UNREALIZED_TYPE_METHOD", defaultSeverity: "warning", summary: "A pure method of a claimed type is nowhere in its own source file (the method's sourcePath, else the type's)" },
+        { code: "MISSING_SOURCE_FILE", defaultSeverity: "error", summary: "A source file a type or one of its methods names does not resolve to a file on disk" },
+        { code: "SOURCE_PATH_ESCAPES_ROOT", defaultSeverity: "error", summary: "A source file a type or one of its methods names is absolute or escapes the project root (containment refusal)" },
+        { code: "CONFORMANCE_ANALYSIS_SKIPPED", defaultSeverity: "warning", summary: "A source file a type or one of its methods names could not be analyzed (binary/unreadable) \u2014 what it would have realized was not checked" }
+      ],
+      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 blocked = /* @__PURE__ */ new Set();
+          for (const file of typeSourceFiles(type)) {
+            const key = pathKey(file);
+            const facts = code.factsAt(key);
+            if (!facts || facts.status === "analyzed") continue;
+            blocked.add(key);
+            const problem = FILE_PROBLEMS[facts.status];
+            if (!problem) continue;
+            ctx.addIssue(problem.severity, problem.code, `${ownerOf(type, file)} sourcePath "${file}" ${problem.detail}`, type.id);
+          }
+          const typeKey = pathKey(type.sourcePath);
+          const typeFacts = code.factsAt(typeKey);
+          if (typeFacts && !blocked.has(typeKey)) {
+            const symbol = type.symbol ?? type.name;
+            const published = typeFacts.analysisGrade === "exact" ? new Set(typeFacts.reexportOnly ? [] : typeFacts.exportedNames) : code.declarationsAt(typeKey);
+            if (!published.has(symbol)) {
+              const label = type.symbol ? `"${type.name}" (symbol "${symbol}")` : `"${type.name}"`;
+              ctx.addIssue(
+                "warning",
+                "UNREALIZED_TYPE",
+                `Type ${label} is not published by "${type.sourcePath}" (analysis grade: ${typeFacts.analysisGrade})${typeFacts.reexportOnly ? ", which is a pure re-export barrel and declares nothing of its own" : ""} \u2014 name the file the declaration lives in, or bind the code-level name with \`symbol\`.`,
+                type.id
+              );
+            }
+          }
+          for (const method2 of type.methods ?? []) {
+            const file = method2.sourcePath ?? type.sourcePath;
+            const key = pathKey(file);
+            if (blocked.has(key)) continue;
+            const facts = code.factsAt(key);
+            if (!facts || facts.status !== "analyzed") continue;
+            const symbol = method2.symbol ?? method2.name;
+            if (code.declarationsAt(key).has(symbol)) continue;
+            const label = method2.symbol ? `"${method2.name}" (symbol "${symbol}")` : `"${method2.name}"`;
+            ctx.addIssue(
+              "warning",
+              "UNREALIZED_TYPE_METHOD",
+              `Method ${label} of type "${type.id}" is not declared in "${file}" (analysis grade: ${facts.analysisGrade}) \u2014 a pure type method is often a free function named after its type; bind that name with \`symbol\`, or name the file it lives in with the method's own \`sourcePath\`.`,
+              type.id
+            );
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/core/rules/conformance/unclaimed-source.ts
+var unclaimedSourceRule;
+var init_unclaimed_source = __esm({
+  "src/core/rules/conformance/unclaimed-source.ts"() {
+    "use strict";
+    init_models();
+    unclaimedSourceRule = {
+      name: "unclaimed-source",
+      description: "Code\u2194spec Level 1, asked the other way round: every source file under the project's declared source roots must be named by some spec \u2014 an implementation's sourcePath, a method's, a simPath, or a type's \u2014 or be carried in the frozen `rules.conformance.unclaimed` list. A pure re-export barrel declares nothing of its own and only republishes other modules, so it has no code to claim and is exempt (exact grade only: a weaker grade cannot tell a barrel from a file it failed to parse). Declaring no source roots leaves the check silent, which is what makes it opt-in; the unclaimed list is a one-way debt register, so an entry the walk no longer finds unclaimed must be deleted and the list can only shrink.",
+      codes: [
+        { code: "UNCLAIMED_SOURCE_FILE", defaultSeverity: "warning", summary: "A source file under a declared source root that no spec names and the frozen unclaimed list does not carry \u2014 code nobody designed" },
+        { code: "STALE_UNCLAIMED_ENTRY", defaultSeverity: "warning", summary: "An entry of the frozen unclaimed list names a file that is now claimed, or that the source-root walk no longer finds \u2014 delete it, the list only shrinks" }
+      ],
+      check(ctx) {
+        const walked = ctx.codeModel.rootFiles;
+        const listed = (ctx.rules?.conformance?.unclaimed ?? []).map(pathKey);
+        if (walked.length === 0) return;
+        const claimed = /* @__PURE__ */ new Set();
+        for (const impl of ctx.implementations) {
+          for (const file of implementationSourceFiles(impl)) claimed.add(pathKey(file));
+          if (impl.simPath) claimed.add(pathKey(impl.simPath));
+        }
+        for (const type of ctx.types) {
+          for (const file of typeSourceFiles(type)) claimed.add(pathKey(file));
+        }
+        const code = ctx.codeIndex();
+        const isBarrel = (file) => code.factsAt(file)?.reexportOnly === true;
+        const isLiveDebt = (file) => !claimed.has(file) && !isBarrel(file);
+        const listedSet = new Set(listed);
+        for (const file of walked) {
+          if (!isLiveDebt(file)) continue;
+          if (listedSet.has(file)) continue;
+          ctx.addIssue(
+            "warning",
+            "UNCLAIMED_SOURCE_FILE",
+            `Source file "${file}" is under a declared source root but no spec names it \u2014 give it to a spec as a sourcePath (an implementation's, a method's, or a type's), or carry it in \`rules.conformance.unclaimed\` until it is designed.`
+          );
+        }
+        const walkedSet = new Set(walked);
+        for (const entry of listed) {
+          if (walkedSet.has(entry) && isLiveDebt(entry)) continue;
+          const why = !walkedSet.has(entry) ? "the source-root walk no longer finds it (deleted, renamed, excluded, or outside the declared roots)" : isBarrel(entry) ? "it is a pure re-export barrel, which has nothing to claim" : "a spec now names it";
+          ctx.addIssue(
+            "warning",
+            "STALE_UNCLAIMED_ENTRY",
+            `"${entry}" is carried in \`rules.conformance.unclaimed\` but ${why} \u2014 delete the entry; the list only shrinks.`
+          );
+        }
+      }
+    };
+  }
+});
+
 // src/core/rules/heuristic/coupling-health.ts
 var DEFAULT_GOD_COMPONENT_THRESHOLD, couplingRule;
 var init_coupling_health = __esm({
@@ -13947,14 +14167,14 @@ var init_technology_boundaries = __esm({
         { code: "VENDOR_NAME_IN_CONTRACT", defaultSeverity: "warning", summary: "Technology name in L3 contract identifiers" }
       ],
       check(ctx) {
-        const ownerOf = /* @__PURE__ */ new Map();
-        for (const c of ctx.components) for (const m of c.owns) ownerOf.set(m, c.id);
+        const ownerOf2 = /* @__PURE__ */ new Map();
+        for (const c of ctx.components) for (const m of c.owns) ownerOf2.set(m, c.id);
         const ownershipRoot = (id) => {
           const seen = /* @__PURE__ */ new Set();
           let cur = id;
-          while (ownerOf.has(cur) && !seen.has(cur)) {
+          while (ownerOf2.has(cur) && !seen.has(cur)) {
             seen.add(cur);
-            cur = ownerOf.get(cur);
+            cur = ownerOf2.get(cur);
           }
           return cur;
         };
@@ -14847,6 +15067,8 @@ var init_repository = __esm({
     init_integration_sim_file();
     init_integration_sim_wiring();
     init_integration_sim_coverage();
+    init_type_realization();
+    init_unclaimed_source();
     init_coupling_health();
     init_signature_language_builtins();
     init_narrative_language_constructs();
@@ -15011,6 +15233,11 @@ 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.
+      typeRealizationRule,
+      unclaimedSourceRule,
       couplingRule,
       // Target-language fit in two questions: what a CONTRACT may name, and what
       // a NARRATIVE may describe.
@@ -15043,7 +15270,7 @@ var init_repository = __esm({
 
 // src/core/source-analysis.ts
 function emptyCodeModel() {
-  return { files: [], projectRoot: "" };
+  return { files: [], projectRoot: "", rootFiles: [] };
 }
 function stripComments(text2, patterns) {
   let out = text2;
@@ -15283,7 +15510,8 @@ function walkExact(ts, sourceText, fileName) {
     ts.forEachChild(node, visit);
   };
   visit(sf);
-  return { declared, anchors, exported, imports, reexports, starExports, complexity, calls, mutableBindings };
+  const reexportOnly = sf.statements.length > 0 && sf.statements.every((st) => ts.isExportDeclaration(st) && !!st.moduleSpecifier);
+  return { declared, anchors, exported, imports, reexports, starExports, complexity, calls, mutableBindings, reexportOnly };
 }
 function resolveRelativeModule(fromFile, specifier) {
   if (!specifier.startsWith(".")) return null;
@@ -15341,15 +15569,65 @@ function looksBinary(buffer) {
   const probe2 = buffer.subarray(0, Math.min(buffer.length, 4096));
   return probe2.includes(0);
 }
-function buildCodeModel(implementations, projectRoot2) {
+function walkSourceRoots(sourceRoots, exclude, projectRoot2) {
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  const excluded = exclude.map(pathKey);
+  const isExcluded = (key) => excluded.some((e) => key === e || key.startsWith(`${e}/`));
+  const record2 = (absolute) => {
+    const key = pathKey(path13.relative(projectRoot2, absolute));
+    if (seen.has(key) || isExcluded(key)) return;
+    if (!EXTENSION_LANGUAGE[path13.extname(key).toLowerCase()]) return;
+    seen.add(key);
+    found.push(key);
+  };
+  const descend = (dir) => {
+    let entries;
+    try {
+      entries = fs10.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries.slice().sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+      const child = path13.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+        if (isExcluded(pathKey(path13.relative(projectRoot2, child)))) continue;
+        descend(child);
+      } else if (entry.isFile()) {
+        record2(child);
+      }
+    }
+  };
+  for (const root of sourceRoots) {
+    const key = pathKey(root);
+    if (path13.isAbsolute(key) || path13.normalize(key).split(path13.sep)[0] === "..") continue;
+    const absolute = path13.resolve(projectRoot2, key);
+    if (path13.relative(projectRoot2, absolute).startsWith("..")) continue;
+    if (isExcluded(key)) continue;
+    let stat;
+    try {
+      stat = fs10.statSync(absolute);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) descend(absolute);
+    else if (stat.isFile()) record2(absolute);
+  }
+  return found;
+}
+function buildCodeModel(implementations, types, projectRoot2, sourceRoots = [], exclude = []) {
   const files = [];
   const seen = /* @__PURE__ */ new Set();
   const exactCache = /* @__PURE__ */ new Map();
+  const rootFiles = walkSourceRoots(sourceRoots, exclude, projectRoot2);
   const declaredPaths = [];
   for (const impl of implementations) {
     declaredPaths.push(...implementationSourceFiles(impl));
     if (impl.simPath) declaredPaths.push(impl.simPath);
   }
+  for (const type of types) declaredPaths.push(...typeSourceFiles(type));
+  declaredPaths.push(...rootFiles);
   for (const declared of declaredPaths) {
     const sourcePath = pathKey(declared);
     if (seen.has(sourcePath)) continue;
@@ -15398,7 +15676,8 @@ function buildCodeModel(implementations, projectRoot2) {
             reexports: [...facts.reexports],
             functionComplexity: Object.fromEntries(facts.complexity),
             functionCalls: Object.fromEntries([...facts.calls].map(([k, v]) => [k, [...v]])),
-            topLevelMutableBindings: [...facts.mutableBindings]
+            topLevelMutableBindings: [...facts.mutableBindings],
+            reexportOnly: facts.reexportOnly
           };
         } catch {
           analyzed = analyzeGeneric(text2);
@@ -15413,7 +15692,7 @@ function buildCodeModel(implementations, projectRoot2) {
     }
     files.push({ path: sourcePath, status: "analyzed", language, ...analyzed });
   }
-  return { files, projectRoot: projectRoot2 };
+  return { files, projectRoot: projectRoot2, rootFiles };
 }
 var fs10, path13, import_module2, EXTENSION_LANGUAGE, C_FAMILY_COMMENTS, JS_PATTERNS, LANGUAGE_PATTERNS, PATTERN_ANALYSIS_MAX_BYTES, IDENTIFIER_RE, STRING_RE, tsResolutionCache, TS_RESOLUTION_RETRY_MS;
 var init_source_analysis = __esm({
@@ -22396,7 +22675,14 @@ function validateSddTree(rulesOrOptions, projectType = "backend") {
   const implementations = loadImplementationSpecs();
   const types = loadTypeSpecs();
   const surfaceSnapshots = loadSurfaceSnapshots();
-  const codeModel = buildCodeModel(implementations, getProjectRoot());
+  const conformance = rules?.conformance;
+  const codeModel = buildCodeModel(
+    implementations,
+    types,
+    getProjectRoot(),
+    conformance?.sourceRoots ?? [],
+    conformance?.exclude ?? []
+  );
   const statusBearing = treatAllAsComplete ? [...subsystems, ...components, ...interfaces, ...implementations] : settledStatusBearing({ subsystems, components, interfaces, implementations });
   const statusSnapshot = statusBearing.map((s) => s.status);
   for (const s of statusBearing) s.status = "complete";
@@ -26827,6 +27113,7 @@ __export(server_exports, {
   captureBuildStamp: () => captureBuildStamp,
   createMcpServer: () => createMcpServer,
   isBuildStale: () => isBuildStale,
+  markStale: () => markStale,
   startMcpServer: () => startMcpServer,
   statusFamilyContext: () => statusFamilyContext
 });
@@ -26907,6 +27194,12 @@ function json(value) {
 function errText(message) {
   return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
 }
+function structured(content, data) {
+  return { content: [{ type: "text", text: content }], structuredContent: data };
+}
+function jsonStructured(value) {
+  return structured(JSON.stringify(value, null, 2), value);
+}
 function renderChangeReport(report2) {
   const lines = [report2.dryRun ? `DRY RUN \u2014 nothing was written. ${report2.summary}` : report2.summary];
   for (const change of report2.changes) {
@@ -26920,6 +27213,13 @@ function renderChangeReport(report2) {
   if (report2.notices.length) lines.push("", "NOTICE:", ...report2.notices.map((n) => `- ${n}`));
   return lines.join("\n");
 }
+function writeReceipt(sentence, receipt) {
+  const noticeBlock = receipt.notices.length ? `
+
+NOTICE:
+- ${receipt.notices.join("\n- ")}` : "";
+  return structured(`${sentence}${noticeBlock}`, receipt);
+}
 function captureBuildStamp(entryPath) {
   try {
     const s = fs20.statSync(entryPath);
@@ -26937,16 +27237,19 @@ function isBuildStale(stamp) {
     return false;
   }
 }
-function withStaleWarning(result) {
-  if (!isBuildStale(SERVER_BUILD_STAMP)) return result;
-  const first = result.content?.[0];
+function markStale(result) {
+  const marked = result.structuredContent ? { ...result, structuredContent: { ...result.structuredContent, staleServer: true } } : result;
+  const first = marked.content?.[0];
   if (first && first.type === "text") {
     return {
-      ...result,
-      content: [{ ...first, text: `${first.text}${STALE_SERVER_WARNING}` }, ...result.content.slice(1)]
+      ...marked,
+      content: [{ ...first, text: `${first.text}${STALE_SERVER_WARNING}` }, ...marked.content.slice(1)]
     };
   }
-  return result;
+  return marked;
+}
+function withStaleWarning(result) {
+  return isBuildStale(SERVER_BUILD_STAMP) ? markStale(result) : result;
 }
 function reg(server, name, config, cb) {
   const guarded = (args) => {
@@ -26958,8 +27261,9 @@ function reg(server, name, config, cb) {
   server.registerTool(name, strictConfig, guarded);
 }
 function statusForCreate(label, stated, existing) {
-  if (stated === void 0) return { status: "draft" };
-  const held = existing?.status ?? void 0;
+  const stored = existing?.status;
+  const held = stored !== void 0 && STATUS_ORDER.includes(stored) ? stored : void 0;
+  if (stated === void 0) return { status: held ?? "draft" };
   if (held === void 0) return { status: stated };
   const rank = (s) => STATUS_ORDER.indexOf(s);
   if (rank(stated) < rank(held)) {
@@ -27275,8 +27579,9 @@ function createMcpServer(options = {}) {
     server,
     "sdd_initialize_system",
     {
-      description: "Initialize the L0 System Specification (system.yaml). Re-running it on an existing system RE-AUTHORS it: the fields above are replaced, and everything this tool cannot express (databases, the project gateway publicInterfaces, diagram defaults) is carried forward.",
-      inputSchema: systemInput
+      description: "Initialize the L0 System Specification (system.yaml). Re-running it on an existing system RE-AUTHORS it: the fields above are replaced, and everything this tool cannot express (databases, the project gateway publicInterfaces, diagram defaults) is carried forward. The answer carries a write receipt as structured content beside the sentence \u2014 what was written, and whether a system spec already existed \u2014 so a caller never has to read English to find out.",
+      inputSchema: systemInput,
+      outputSchema: specWriteReceiptOutput
     },
     ({ name, vision, boundaries, globalRequirements, targetLanguage }) => {
       try {
@@ -27298,11 +27603,10 @@ function createMcpServer(options = {}) {
         next.updatedAt = now;
         saveSystemSpec2(next);
         const notices = existing ? rewriteNotices({ label: `System spec "${existing.name}"`, carried, cleared, removed: [] }) : [];
-        const noticeBlock = notices.length ? `
-
-NOTICE:
-- ${notices.join("\n- ")}` : "";
-        return text(`Successfully ${existing ? "re-authored" : "initialized"} L0 System Spec for "${name}".${noticeBlock}`);
+        return writeReceipt(
+          `Successfully ${existing ? "re-authored" : "initialized"} L0 System Spec for "${name}".`,
+          { kind: "system", id: "system", name, replacedExisting: Boolean(existing), notices }
+        );
       } catch (e) {
         return errText(String(e));
       }
@@ -27339,8 +27643,9 @@ NOTICE:
     server,
     "sdd_add_subsystem",
     {
-      description: "Add an L1 Subsystem / Service under the system boundary. publicInterfaces should bind each entry to the component that realizes it (the subsystem's published surface); if components do not exist yet, add them later with sdd_set_public_interfaces. Re-running it on an existing id RE-AUTHORS it: the fields above are replaced, lint/ext are carried forward, and the stored status is kept unless this input states a higher one.",
-      inputSchema: subsystemInput
+      description: "Add an L1 Subsystem / Service under the system boundary. publicInterfaces should bind each entry to the component that realizes it (the subsystem's published surface); if components do not exist yet, add them later with sdd_set_public_interfaces. Re-running it on an existing id RE-AUTHORS it: the fields above are replaced, 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 child project directory a chained subsystem scaffolded.",
+      inputSchema: subsystemInput,
+      outputSchema: specWriteReceiptOutput
     },
     ({ id, name, description, publicInterfaces, projectPath, targetLanguage, profile, designDepth, trustedLinks, lifecycle, status: status2 }) => {
       try {
@@ -27371,17 +27676,24 @@ NOTICE:
         const cleared = clearedByOmission(existing, spec, subsystemInputFields);
         if (existing) spec.createdAt = existing.createdAt;
         const notices = existing ? rewriteNotices({ label: `Subsystem "${id}"`, carried: ["createdAt", ...carried], cleared, removed: [] }) : [];
-        const noticeBlock = notices.length ? `
-
-NOTICE:
-- ${notices.join("\n- ")}` : "";
+        const receipt = {
+          kind: "subsystem",
+          id,
+          name,
+          replacedExisting: Boolean(existing),
+          status: resolved.status,
+          notices
+        };
         if (projectPath && projectPath.trim() !== "") {
           const { createChainedSubsystem: createChainedSubsystem3 } = requireProvision();
           createChainedSubsystem3(spec, name);
-          return text(`Successfully added external subsystem "${name}" (${id}) and scaffolded its child project at ${projectPath}.${noticeBlock}`);
+          return writeReceipt(
+            `Successfully added external subsystem "${name}" (${id}) and scaffolded its child project at ${projectPath}.`,
+            { ...receipt, scaffoldedProjectPath: projectPath }
+          );
         }
         saveSubsystemSpec2(spec);
-        return text(`Successfully added L1 Subsystem Spec "${name}" (${id}).${noticeBlock}`);
+        return writeReceipt(`Successfully added L1 Subsystem Spec "${name}" (${id}).`, receipt);
       } catch (e) {
         return errText(String(e));
       }
@@ -27577,8 +27889,9 @@ NOTICE:
     server,
     "sdd_add_component",
     {
-      description: `Add an L2 Component under a subsystem. componentType is a building block (Portal, Orchestrator, Supervisor, Actor, Store, Index, Query, Registry, Adapter, Observer) or the pattern Repository. Specialist and Gateway are retired (STEREOTYPE_RETIRED) and cannot be authored: logic is an Orchestrator with a dependencyClass (pure | read; unset = a workflow), and a gateway is a Portal with the gateway variant (set variant with sdd_update_spec). Patterns set "owns" (their private member blocks); all components set "dependsOn" (collaborators \u2014 facades or standalone blocks). Held/persisted state (configs, permissions, sessions, caches): model the Repository recipe \u2014 a Store + Registry (write) + Index (read), plus a Query for computed reads over the Store, owned by a Repository facade consumers depend on; a deliberately standalone Store is the sanctioned lightweight form (workflow-layer consumers + lint.allow on UNOWNED_STORE). Never hold state as fields inside an Orchestrator because a Store link was refused. Re-running it on an existing id RE-AUTHORS it: the fields above are replaced (an omitted array is CLEARED), while lint.allow, a Portal's auth, variant, patterns and externalLinks are carried forward \u2014 edit those with sdd_update_spec. The stored status is kept unless this input states a higher one.`,
-      inputSchema: componentInput
+      description: `Add an L2 Component under a subsystem. componentType is a building block (Portal, Orchestrator, Supervisor, Actor, Store, Index, Query, Registry, Adapter, Observer) or the pattern Repository. Specialist and Gateway are retired (STEREOTYPE_RETIRED) and cannot be authored: logic is an Orchestrator with a dependencyClass (pure | read; unset = a workflow), and a gateway is a Portal with the gateway variant (set variant with sdd_update_spec). Patterns set "owns" (their private member blocks); all components set "dependsOn" (collaborators \u2014 facades or standalone blocks). Held/persisted state (configs, permissions, sessions, caches): model the Repository recipe \u2014 a Store + Registry (write) + Index (read), plus a Query for computed reads over the Store, owned by a Repository facade consumers depend on; a deliberately standalone Store is the sanctioned lightweight form (workflow-layer consumers + lint.allow on UNOWNED_STORE). Never hold state as fields inside an Orchestrator because a Store link was refused. Re-running it on an existing id RE-AUTHORS it: the fields above are replaced (an omitted array is CLEARED), while lint.allow, a Portal's auth, variant, patterns and externalLinks are carried forward \u2014 edit those with sdd_update_spec. 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 every gate notice the write raised, each as its own entry.`,
+      inputSchema: componentInput,
+      outputSchema: specWriteReceiptOutput
     },
     ({ id, name, description, subsystem, componentType, owns, dependsOn, portalType, basePath, dispatch, durability, dependencyClass, emits, subscribesTo, ext, status: status2 }) => {
       try {
@@ -27621,11 +27934,10 @@ NOTICE:
             removed: []
           }));
         }
-        const noticeBlock = notices.length ? `
-
-NOTICE:
-- ${notices.join("\n- ")}` : "";
-        return text(`Successfully ${existing ? "re-authored" : "added"} L2 Component Spec "${name}" (${id}, ${componentType}).${noticeBlock}`);
+        return writeReceipt(
+          `Successfully ${existing ? "re-authored" : "added"} L2 Component Spec "${name}" (${id}, ${componentType}).`,
+          { kind: "component", id, name, replacedExisting: Boolean(existing), status: resolved.status, notices }
+        );
       } catch (e) {
         return errText(String(e));
       }
@@ -27635,12 +27947,14 @@ NOTICE:
     name: import_zod11.z.string(),
     description: import_zod11.z.string(),
     signature: import_zod11.z.string(),
-    returns: import_zod11.z.string(),
+    returns: import_zod11.z.string().describe(TYPE_REF_GRAMMAR("The type the method answers with")),
     params: import_zod11.z.array(import_zod11.z.object({
       name: import_zod11.z.string(),
-      type: import_zod11.z.string().describe('A primitive/builtin or a defined type id (e.g. "billing.Invoice")'),
+      type: import_zod11.z.string().describe(TYPE_REF_GRAMMAR("The parameter's type")),
       description: import_zod11.z.string().optional(),
-      optional: import_zod11.z.boolean().optional()
+      optional: import_zod11.z.boolean().optional().describe(
+        'Whether the parameter may be OMITTED by a caller. It is not nullability: a parameter that must be passed but may be passed as nothing is a required parameter whose type is a union \u2014 "ProjectConfig | null". Say whichever is true; they are different contracts.'
+      )
     }).strict()).optional().describe("Structured parameters \u2014 authoritative for type checking (the prose signature becomes display-only). Strongly preferred."),
     guarantees: import_zod11.z.array(import_zod11.z.string().min(1)).optional().describe("Semantic guarantees the method promises (combinable); any guarantee a narrative step asserts must be declared here. Builtin tokens: idempotent | atomic | transactional | exactly-once; extension packs may declare more (any other token is UNKNOWN_GUARANTEE)"),
     effect: import_zod11.z.enum(["read", "write"]).optional().describe("State-effect direction on the component's held state \u2014 required on a durable Store's contract methods so the durability round-trip rule can pair writes with hydration read-backs"),
@@ -27669,8 +27983,9 @@ NOTICE:
     server,
     "sdd_define_interface",
     {
-      description: "Define an L3 Contract / Interface with method signatures for a component. Prefer supplying structured `params` per method \u2014 they are the authoritative source for type checking (the free-form signature string then becomes display-only and is never heuristically parsed). A method declares the finding codes it reports in `findings` ({code, severity, summary}); each code must be anchored in the method's source file, as a string literal or a property-access name (UNREALIZED_FINDING). Re-defining an existing id REPLACES the method list: a method left out of the input is REMOVED (and reported); spec-level lint/ext and each method's endpoint binding are carried forward, and the stored status is kept unless this input states a higher one.",
-      inputSchema: interfaceInput
+      description: "Define an L3 Contract / Interface with method signatures for a component. Prefer supplying structured `params` per method \u2014 they are the authoritative source for type checking (the free-form signature string then becomes display-only and is never heuristically parsed). A method declares the finding codes it reports in `findings` ({code, severity, summary}); each code must be anchored in the method's source file, as a string literal or a property-access name (UNREALIZED_FINDING). Re-defining an existing id REPLACES the method list: a method left out of the input is REMOVED (and reported); spec-level lint/ext and each method's endpoint binding 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: interfaceInput,
+      outputSchema: specWriteReceiptOutput
     },
     ({ id, name, description, component, methods, status: status2 }) => {
       try {
@@ -27713,11 +28028,10 @@ NOTICE:
             removedSuffix: " (endpoint bindings included)"
           }));
         }
-        const noticeBlock = notices.length ? `
-
-NOTICE:
-- ${notices.join("\n- ")}` : "";
-        return text(`Successfully ${existing ? "re-authored" : "defined"} L3 Interface Contract "${name}" (${id}).${noticeBlock}`);
+        return writeReceipt(
+          `Successfully ${existing ? "re-authored" : "defined"} L3 Interface Contract "${name}" (${id}).`,
+          { kind: "interface", id, name, replacedExisting: Boolean(existing), status: resolved.status, notices }
+        );
       } catch (e) {
         return errText(String(e));
       }
@@ -27862,8 +28176,9 @@ NOTICE:
     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). 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.",
-      inputSchema: implInput
+      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). 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.",
+      inputSchema: implInput,
+      outputSchema: specWriteReceiptOutput
     },
     ({ id, name, description, contract, sourcePath, simPath, technologies, detail, conformance, methods, status: status2 }) => {
       try {
@@ -27919,11 +28234,10 @@ NOTICE:
             removedSuffix: " (L5 narratives included)"
           }));
         }
-        const noticeBlock = notices.length ? `
-
-NOTICE:
-- ${notices.join("\n- ")}` : "";
-        return text(`Successfully saved L4 Implementation Spec "${name}" (${id}) with method narratives.${noticeBlock}`);
+        return writeReceipt(
+          `Successfully saved L4 Implementation Spec "${name}" (${id}) with method narratives.`,
+          { kind: "implementation", id, name, replacedExisting: Boolean(existing), status: resolved.status, notices }
+        );
       } catch (e) {
         return errText(String(e));
       }
@@ -27938,13 +28252,20 @@ NOTICE:
     group: import_zod11.z.string().optional().describe("Optional logical group ID to organize this type in subfolders"),
     fields: import_zod11.z.array(import_zod11.z.object({
       name: import_zod11.z.string(),
-      type: import_zod11.z.string(),
+      type: import_zod11.z.string().describe(TYPE_REF_GRAMMAR("The field's type")),
       description: import_zod11.z.string().optional(),
       optional: import_zod11.z.boolean().optional(),
       key: import_zod11.z.enum(["primary", "unique", "foreign"]).optional().describe("Identity marker (PK/unique/FK) for ERD and database schema derivation"),
       references: import_zod11.z.string().optional().describe('For foreign keys, the referenced type/table id and optional field, e.g. "invoice.id"')
     }).strict()).optional().describe('Data fields (type is a primitive or a qualified type id, e.g. "billing.Invoice")'),
-    methods: import_zod11.z.array(import_zod11.z.object({ name: import_zod11.z.string(), signature: import_zod11.z.string(), returns: import_zod11.z.string(), description: import_zod11.z.string().optional() }).strict()).optional().describe("Pure intrinsic methods only"),
+    methods: import_zod11.z.array(import_zod11.z.object({
+      name: import_zod11.z.string(),
+      signature: import_zod11.z.string(),
+      returns: import_zod11.z.string().describe(TYPE_REF_GRAMMAR("The type the method answers with")),
+      description: import_zod11.z.string().optional(),
+      sourcePath: import_zod11.z.string().optional().describe("Source file realizing this method when the type's own sourcePath does not hold it \u2014 a pure type method often lives apart from the declaration"),
+      symbol: import_zod11.z.string().optional().describe("Code-level name realizing this method when it differs from the method name, e.g. narrative_step.foreignFields realized by narrativeStepForeignFields")
+    }).strict()).optional().describe("Pure intrinsic methods only"),
     componentClass: import_zod11.z.string().optional().describe("Optional component id that implements or owns this logical entity"),
     invariants: import_zod11.z.array(import_zod11.z.object({
       id: import_zod11.z.string().describe("Stable invariant id, unique within the entity"),
@@ -27952,17 +28273,20 @@ NOTICE:
     }).strict()).optional().describe("Declared domain invariants (entities): every write-effect method of the componentClass must carry a narrative step asserting each (assertsInvariants) \u2014 declarations checked, enforcement never proven"),
     database: import_zod11.z.string().optional().describe("Optional database id for table-schema types"),
     table: import_zod11.z.string().optional().describe("Optional database table name for table-schema types"),
-    linkedEntity: import_zod11.z.string().optional().describe("Optional logical entity id represented by this table-schema type")
+    linkedEntity: import_zod11.z.string().optional().describe("Optional logical entity id represented by this table-schema type"),
+    sourcePath: import_zod11.z.string().optional().describe("Source file holding the declaration of this type (project-relative). Naming one turns the type into a claim on code: the file must resolve and the declaration must be anchored in it (UNREALIZED_TYPE)"),
+    symbol: import_zod11.z.string().optional().describe('Code-level name realizing the declaration when it differs from name, e.g. a type named "Invoice Line" declared as InvoiceLine')
   };
   const typeInputFields = Object.keys(typeInput);
   reg(
     server,
     "sdd_add_type",
     {
-      description: "Define an entity or value-object type (the data components operate on). Entities are owned by a subsystem; shared value objects omit subsystem (system-level). Fields are data; methods are PURE intrinsic behaviour only \u2014 anything needing a collaborator belongs on a component, taking the entity as an argument. Re-defining an existing id REPLACES fields/methods/invariants (an omitted list is CLEARED, and a dropped member is reported); lint/ext are carried forward.",
-      inputSchema: typeInput
+      description: "Define an entity or value-object type (the data components operate on). Entities are owned by a subsystem; shared value objects omit subsystem (system-level). Fields are data; methods are PURE intrinsic behaviour only \u2014 anything needing a collaborator belongs on a component, taking the entity as an argument. A type may also CLAIM code: sourcePath names the file holding its declaration (and each method may name its own), symbol binds the code-level name when it differs \u2014 the file must then resolve and the declaration must be anchored in it. Re-defining an existing id REPLACES fields/methods/invariants and restates sourcePath/symbol (an omitted list or path is CLEARED, and a dropped member is reported); lint/ext are carried forward. The answer carries a write receipt as structured content beside the sentence \u2014 whether a spec already held the id, and the notices a restatement raised, each as its own entry. A type carries no lifecycle status, so the receipt states none.",
+      inputSchema: typeInput,
+      outputSchema: specWriteReceiptOutput
     },
-    ({ kind, id, name, description, subsystem, group, fields, methods, componentClass, invariants, database, table, linkedEntity }) => {
+    ({ kind, id, name, description, subsystem, group, fields, methods, componentClass, invariants, database, table, linkedEntity, sourcePath, symbol }) => {
       try {
         const { loadTypeSpec: loadTypeSpec2, saveTypeSpec: saveTypeSpec2 } = requireSpecs();
         const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -27988,6 +28312,8 @@ NOTICE:
           ...database ? { database } : {},
           ...table ? { table } : {},
           ...linkedEntity ? { linkedEntity } : {},
+          ...sourcePath ? { sourcePath } : {},
+          ...symbol ? { symbol } : {},
           createdAt: now,
           updatedAt: now
         };
@@ -28007,11 +28333,10 @@ NOTICE:
             removedNoun: "member"
           }));
         }
-        const noticeBlock = notices.length ? `
-
-NOTICE:
-- ${notices.join("\n- ")}` : "";
-        return text(`Successfully ${existing ? "re-authored" : "defined"} ${kind} type "${name}" (${id}).${noticeBlock}`);
+        return writeReceipt(
+          `Successfully ${existing ? "re-authored" : "defined"} ${kind} type "${name}" (${id}).`,
+          { kind: "type", id, name, replacedExisting: Boolean(existing), notices }
+        );
       } catch (e) {
         return errText(String(e));
       }
@@ -28021,11 +28346,12 @@ NOTICE:
     server,
     "sdd_validate_tree",
     {
-      description: "Validate the SDD spec tree, checking parent references, contract compatibility, narratives, and component type boundaries. Supports scoping and recursion controls.",
+      description: "Validate the SDD spec tree, checking parent references, contract compatibility, narratives, and component type boundaries. Supports scoping and recursion controls. Findings come back as structured content too, under the schema this tool declares \u2014 errors and warnings already split, each with its code, severity, message and the spec it concerns \u2014 so a caller filters them as objects instead of parsing the JSON text block and hoping its shape holds.",
       inputSchema: {
         subsystem: import_zod11.z.string().optional().describe("Only validate the specified subsystem (granular)"),
         recursive: import_zod11.z.boolean().optional().describe("Whether to recursively validate subprojects (default: true)")
-      }
+      },
+      outputSchema: validateTreeOutput
     },
     ({ subsystem, recursive }) => {
       try {
@@ -28038,7 +28364,7 @@ NOTICE:
           scopeSubsystem: subsystem,
           recursive: recursive ?? true
         });
-        return json({
+        return jsonStructured({
           valid: result.valid,
           errors: result.issues.filter((i) => i.severity === "error"),
           warnings: result.issues.filter((i) => i.severity === "warning"),
@@ -28053,17 +28379,19 @@ NOTICE:
     server,
     "sdd_get_spec",
     {
-      description: `Get/read the parsed JSON contents of a specific spec from the spec tree. Returns structural contents without file system path searching. Pass "methods" to read only the named methods of a contract, an implementation or a type \u2014 a 45-method spec fetched whole to look at one of them is the read side of the same waste a restatement is on the write side; the answer then carries a "partialResult" marker naming what was left out, and must never be re-authored from. For a variant-tagged COMPONENT the result also carries a derived, read-only "variantGuidance" (the variant's base, its implementation guidance, and the same-variant sibling components to implement alike) \u2014 it is resolved from the variant registry, not part of the spec, so never write it back.`,
+      description: `Get/read the parsed JSON contents of a specific spec from the spec tree. Returns structural contents without file system path searching. Pass "methods" to read only the named methods of a contract, an implementation or a type \u2014 a 45-method spec fetched whole to look at one of them is the read side of the same waste a restatement is on the write side; the answer then carries a "partialResult" marker naming what was left out, and must never be re-authored from. For a variant-tagged COMPONENT the result also carries a derived, read-only "variantGuidance" (the variant's base, its implementation guidance, and the same-variant sibling components to implement alike) \u2014 it is resolved from the variant registry, not part of the spec, so never write it back. The structured content carries the same answer with the two derived markers KEPT SEPARATE from the stored spec ({kind, id, spec, partialResult?, variantGuidance?}), so nothing derived can be mistaken for something stored; the text block folds them in as it always has.`,
       inputSchema: {
         kind: import_zod11.z.enum(["system", "subsystem", "component", "interface", "implementation", "type"]).describe("The kind of specification"),
         id: import_zod11.z.string().describe('The identifier of the spec to fetch (the L0 system spec is a singleton \u2014 pass the system name or "system")'),
         methods: import_zod11.z.array(import_zod11.z.string().min(1)).optional().describe("Return only these methods by name; every other field of the spec comes back unchanged. Only an interface, an implementation or a type declares methods \u2014 asking for one elsewhere is refused, as is a name the spec does not declare (the answer names the ones it does). Omit it for the whole spec.")
-      }
+      },
+      outputSchema: getSpecOutput
     },
     ({ kind, id, methods }) => {
       try {
         const specs = requireSpecs();
         let result = null;
+        let partial = null;
         switch (kind) {
           case "system":
             result = specs.loadSystemSpec();
@@ -28100,21 +28428,26 @@ NOTICE:
             );
           }
           const kept = declared.filter((m) => methods.includes(String(m?.name)));
-          result = {
-            ...result,
-            methods: kept,
-            partialResult: {
-              shown: kept.map((m) => String(m?.name)),
-              omitted: names.length - kept.length,
-              warning: `PARTIAL: ${names.length - kept.length} of this spec's ${names.length} methods are not in this answer. Never re-author from it \u2014 sdd_define_interface and sdd_write_narrative REPLACE the method list, so every method missing here would be removed from the spec.`
-            }
+          partial = {
+            shown: kept.map((m) => String(m?.name)),
+            omitted: names.length - kept.length,
+            warning: `PARTIAL: ${names.length - kept.length} of this spec's ${names.length} methods are not in this answer. Never re-author from it \u2014 sdd_define_interface and sdd_write_narrative REPLACE the method list, so every method missing here would be removed from the spec.`
           };
+          result = { ...result, methods: kept };
         }
-        if (kind === "component") {
-          const guidance = resolveComponentVariantGuidance(result);
-          if (guidance) return json({ ...result, variantGuidance: guidance });
-        }
-        return json(result);
+        const guidance = kind === "component" ? resolveComponentVariantGuidance(result) : null;
+        const folded = {
+          ...result,
+          ...partial ? { partialResult: partial } : {},
+          ...guidance ? { variantGuidance: guidance } : {}
+        };
+        return structured(JSON.stringify(folded, null, 2), {
+          kind,
+          id,
+          spec: result,
+          ...partial ? { partialResult: partial } : {},
+          ...guidance ? { variantGuidance: guidance } : {}
+        });
       } catch (e) {
         return errText(String(e));
       }
@@ -28168,11 +28501,13 @@ NOTICE:
         id: import_zod11.z.string().describe("The ID of the spec to update (namespaced if needed)"),
         delta: import_zod11.z.record(import_zod11.z.any()).describe(`The partial fields to merge into the spec. ARRAYS UPSERT, they do not replace: an array whose elements carry an identity is merged element-by-element, so a delta naming ONE element leaves the others intact. Identity is "name" or "id" by default, and per field: dispatch by "capability", lifecycle by phase+component+method, emits/subscribesTo by topic+event, trustedLinks by "subsystem", invariants and patterns by "id", lint.allow by "code", an interface method's findings by "code", boundaries by "name", globalRequirements by "description", switch cases by "value", try catches by "error". Identity merging applies at EVERY depth, including an array INSIDE an element (a method's params, a step's catches). Add "action: 'delete'" (or "remove: true") alongside that identity to REMOVE an element \u2014 including a stale lint allow. Arrays of plain STRINGS (owns, dependsOn, guarantees) carry no per-element identity and are replaced wholesale; pass [] to clear any array outright. To REMOVE an optional field entirely, list it in "unset": e.g. {"unset": ["basePath", "variant"]} \u2014 passing null/undefined means "no change" (they are skipped), and writing "" would leave the field present but empty, which is a different and usually wrong spec. Unsetting a required field is refused by schema validation, which names it. For narrative steps, match by "stepNumber" and use "action: 'insert'" (shifts subsequent steps up) or "action: 'delete'" (shifts subsequent steps down and removes it). Step entries apply in ASCENDING stepNumber order, each against the numbering the earlier entries of the SAME delta left behind \u2014 delete step 3 and step 7 becomes step 6 \u2014 so prefer labels, and restate the step's "label" or "description" on a delete to have it checked against the step actually addressed. Renumbering RELOCATES every flow jump field (onTrueStep/onFalseStep/cases.step/defaultStep/endStep/catches.step/finallyStep/toStep) in the same narrative. A delete is REJECTED when the narrative has no such step, when a jump still targets it (retarget the referrers first), when a restated label/description does not match, or when it is a loop/try/parallel header whose body would be left standing (retype the header first to dissolve the region, then delete it). Changing a step's "type" REBUILDS it for the new type: its description and label are kept and every field the new type cannot carry is dropped (returned as a NOTICE); a delta that retypes AND sets such a field is refused. A step delta is also refused when it carries a marker the merge does not recognise: a non-boolean "remove", an "action" that is neither "insert" nor "delete", a "captureJumps" outside an insert, or no "stepNumber" to address. Inserting AT a jump target relocates those jumps past the inserted step by default (a NOTICE is returned) \u2014 add "captureJumps": true on the inserted step to retarget entry jumps onto it (loop/try endStep region tails always relocate with the body and are never captured). Every jump field has a "*Label" twin (toLabel, onFalseLabel, endLabel, \u2026, and "label" on a cases/catches entry) resolved against step labels AFTER the merge, so a delta may anchor on a label only pre-existing steps carry; a label the delta supplies REPLACES the stored number it twins, while setting the number and its label together in one delta is refused as a contradiction. Reference ids in deltas may use LOCAL names \u2014 they are qualified against the spec's namespace exactly as the loader would. Per-spec lint suppression: set "lint: { allow: [{ code, reason }] }" to silence a WARNING code on this spec only (errors always surface; stale allows are flagged). This delta is deliberately OPEN below its top level \u2014 the shapes nest further than a schema here should restate \u2014 so a key that is not a field at its depth is not refused, it is NAMED BACK under NO EFFECT in the answer, together with any value the spec already held and any "unset" that removed nothing. Read that list: it is where a nested typo shows up.`),
         dryRun: import_zod11.z.boolean().optional().describe("Ask what this delta WOULD do instead of doing it. The whole write runs, the candidate gate included, and the answer is the change report it would have produced \u2014 marked DRY RUN, with nothing stamped and not one byte of the stored file moved. Use it before a delta that renumbers a long narrative.")
-      }
+      },
+      outputSchema: specChangeReportOutput
     },
     ({ kind, id, delta, dryRun }) => {
       try {
-        return text(renderChangeReport(updateSpecGated(kind, id, delta, dryRun)));
+        const report2 = updateSpecGated(kind, id, delta, dryRun);
+        return structured(renderChangeReport(report2), report2);
       } catch (e) {
         return errText(String(e));
       }
@@ -28376,7 +28711,7 @@ async function startMcpServer() {
   } catch {
   }
 }
-var import_mcp, import_stdio, import_zod11, import_types3, fs20, path27, import_url, SERVER_BUILD_STAMP, STALE_SERVER_WARNING, SPEC_WRITE_TOOLS, listChangedEmitters, STORE_MANAGED_FIELDS, STATUS_ORDER, statusInput, ALWAYS_CARRIED_FIELDS, SKILL_RESOURCE_MIME, AGENT_BRIEF_SCHEME;
+var import_mcp, import_stdio, import_zod11, import_types3, fs20, path27, import_url, TYPE_REF_GRAMMAR, staleServerOutput, SPEC_KINDS, STATUS_ORDER, specWriteReceiptOutput, specChangeOutput, specChangeReportOutput, validationIssueOutput, validateTreeOutput, getSpecOutput, SERVER_BUILD_STAMP, STALE_SERVER_WARNING, SPEC_WRITE_TOOLS, listChangedEmitters, STORE_MANAGED_FIELDS, statusInput, ALWAYS_CARRIED_FIELDS, SKILL_RESOURCE_MIME, AGENT_BRIEF_SCHEME;
 var init_server = __esm({
   "src/mcp/server.ts"() {
     "use strict";
@@ -28407,6 +28742,105 @@ var init_server = __esm({
     init_agent_resolver();
     init_budget_policy();
     init_surfaces();
+    TYPE_REF_GRAMMAR = (what) => `${what}: a primitive/builtin or a defined type id (qualified across subsystems, e.g. "billing.Invoice" or "billing::Invoice"). Generics, arrays and UNIONS are all read, at any depth: "Invoice | null" (the commonest shape there is), "Invoice | undefined", "Invoice | Receipt", "Promise<Invoice | null>", "Map<string, Invoice | null>", "Invoice[] | null", "(Invoice | null)[]". Every identifier the string names must resolve \u2014 a union of two defined types means BOTH must exist. A union of string literals ("read" | "write") names no type and resolves to nothing.`;
+    staleServerOutput = {
+      staleServer: import_zod11.z.boolean().optional().describe(
+        "True when the wairon build on disk changed after this server started \u2014 the structured twin of the text answer's STALE SERVER banner. Writes through a stale process can silently drop fields a newer schema introduced: restart the MCP session before editing further."
+      )
+    };
+    SPEC_KINDS = ["system", "subsystem", "component", "interface", "implementation", "type"];
+    STATUS_ORDER = ["draft", "design", "complete"];
+    specWriteReceiptOutput = {
+      kind: import_zod11.z.enum(SPEC_KINDS).describe("The spec kind written."),
+      id: import_zod11.z.string().describe('The id the spec is stored under; "system" for the L0 singleton.'),
+      name: import_zod11.z.string().describe("The spec's display name as written."),
+      replacedExisting: import_zod11.z.boolean().describe(
+        "True when a spec already held this id and the call re-authored it in place rather than adding one. The notices then say what was carried forward, removed or cleared by the restatement."
+      ),
+      status: import_zod11.z.enum(STATUS_ORDER).optional().describe(
+        "The lifecycle status written. Absent for a type, which carries none."
+      ),
+      notices: import_zod11.z.array(import_zod11.z.string()).describe(
+        "The notice lines the text answer lists, one per entry: what was carried forward, what a restatement removed, what an omission cleared, and every gate warning the write raised. Empty for a clean create."
+      ),
+      scaffoldedProjectPath: import_zod11.z.string().optional().describe(
+        "The child project directory a chained subsystem's create scaffolded; absent for every other write."
+      ),
+      ...staleServerOutput
+    };
+    specChangeOutput = {
+      path: import_zod11.z.string().describe("The dotted path the change addresses, with names and indexes."),
+      change: import_zod11.z.enum(["set", "added", "removed", "cleared"]).describe("What happened at that path."),
+      before: import_zod11.z.string().optional().describe("The previous value, summarized; absent when there was none."),
+      after: import_zod11.z.string().optional().describe("The new value, summarized; absent when there is none.")
+    };
+    specChangeReportOutput = {
+      kind: import_zod11.z.enum(SPEC_KINDS).describe("The spec kind written."),
+      id: import_zod11.z.string().describe("The stored spec's id."),
+      written: import_zod11.z.boolean().describe("False when the merged spec equals what is stored: nothing reached disk."),
+      dryRun: import_zod11.z.boolean().describe(
+        "True when the caller asked what the delta WOULD do. `written` is false for a dry run exactly as it is for a delta that changed nothing, and only this field tells the two apart."
+      ),
+      changes: import_zod11.z.array(import_zod11.z.object(specChangeOutput)).describe(
+        "Every change the write made; empty exactly when `written` is false."
+      ),
+      ineffective: import_zod11.z.array(import_zod11.z.string()).describe(
+        "Every path the delta named that the write did not act on, each with why. Read it: a nested typo the permissive delta cannot refuse shows up here and nowhere else."
+      ),
+      notices: import_zod11.z.array(import_zod11.z.string()).describe("Store placement notices, gate warnings and delta notices."),
+      summary: import_zod11.z.string().describe("One line for people."),
+      ...staleServerOutput
+    };
+    validationIssueOutput = {
+      severity: import_zod11.z.enum(["error", "warning"]).describe("The finding's severity after project overrides."),
+      code: import_zod11.z.string().describe("The rule code, UPPER_SNAKE \u2014 the stable handle to filter and suppress by."),
+      message: import_zod11.z.string().describe("What is wrong, named."),
+      agentId: import_zod11.z.string().optional().describe("The agent the finding concerns, when it concerns one."),
+      specId: import_zod11.z.string().optional().describe("The spec the finding concerns, when it concerns one."),
+      draftContext: import_zod11.z.boolean().optional().describe(
+        "True when the finding was raised against a draft/design spec \u2014 what the --ci gate waives."
+      ),
+      surfaceResolved: import_zod11.z.boolean().optional().describe(
+        "True when the finding was verified against a vendored surface snapshot, so it is a contract verdict rather than a resolution failure."
+      )
+    };
+    validateTreeOutput = {
+      valid: import_zod11.z.boolean().describe("False when the tree holds at least one error."),
+      errors: import_zod11.z.array(import_zod11.z.object(validationIssueOutput)).describe("Every finding of severity error."),
+      warnings: import_zod11.z.array(import_zod11.z.object(validationIssueOutput)).describe("Every finding of severity warning."),
+      resolvedThrough: import_zod11.z.object({
+        root: import_zod11.z.string().describe("The top root that was validated."),
+        scope: import_zod11.z.string().describe("The mount chain the verdict was scoped to.")
+      }).optional().describe(
+        "Present when a chained subproject's verdict was resolved through its parent; absent when the tree was validated on its own."
+      ),
+      ...staleServerOutput
+    };
+    getSpecOutput = {
+      kind: import_zod11.z.enum(SPEC_KINDS).describe("The kind of spec read."),
+      id: import_zod11.z.string().describe("The id it was read by."),
+      spec: import_zod11.z.record(import_zod11.z.unknown()).describe(
+        "The stored spec, exactly as the text block renders it \u2014 minus the two derived markers below, which the text folds in and this answer keeps separate so nothing derived can be mistaken for stored."
+      ),
+      partialResult: import_zod11.z.object({
+        shown: import_zod11.z.array(import_zod11.z.string()).describe("The method names this answer carries."),
+        omitted: import_zod11.z.number().describe("How many of the spec's methods are NOT in it."),
+        warning: import_zod11.z.string().describe("Why it must never be re-authored from.")
+      }).optional().describe(
+        "Present only when `methods` filtered the read. A filtered spec is a partial one: sdd_define_interface and sdd_write_narrative REPLACE the method list, so re-authoring from it would delete every method left out."
+      ),
+      variantGuidance: import_zod11.z.object({
+        variant: import_zod11.z.string().describe("The variant id the component declares."),
+        base: import_zod11.z.string().describe("The core stereotype it specializes."),
+        guidance: import_zod11.z.string().describe("How to implement a component of this variant."),
+        siblings: import_zod11.z.array(import_zod11.z.string()).describe("Other components of the same variant, to implement alike."),
+        target: import_zod11.z.string().optional().describe("The target language the variant scopes itself to, if any."),
+        profile: import_zod11.z.string().optional().describe("The architectural profile it scopes itself to, if any.")
+      }).optional().describe(
+        "Derived, read-only guidance for a variant-tagged component \u2014 resolved from the variant registry, not part of the spec. Never write it back."
+      ),
+      ...staleServerOutput
+    };
     SERVER_BUILD_STAMP = captureBuildStamp(__filename);
     STALE_SERVER_WARNING = "\n\n\u26A0 STALE SERVER: the wairon build on disk changed after this MCP server started. Restart the MCP session (e.g. /mcp reconnect) before further spec edits \u2014 writes through a stale server can silently drop fields introduced by newer schemas.";
     SPEC_WRITE_TOOLS = /* @__PURE__ */ new Set([
@@ -28429,7 +28863,6 @@ var init_server = __esm({
     ]);
     listChangedEmitters = /* @__PURE__ */ new WeakMap();
     STORE_MANAGED_FIELDS = /* @__PURE__ */ new Set(["status", "updatedAt"]);
-    STATUS_ORDER = ["draft", "design", "complete"];
     statusInput = import_zod11.z.enum(STATUS_ORDER).optional().describe(
       "The spec's lifecycle status. Omitted means draft for a NEW spec and the status already stored for a re-authoring, so a restatement never reopens a frozen spec. State it to author straight at design or complete instead of promoting afterwards. A status that would LOWER the stored one is refused \u2014 reopening a spec for revision is sdd_update_spec's job, which sets the demotion deliberately."
     );