@wairon/cli 5.1.1-dev.68 → 5.1.1-dev.69

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.68";
+    WAIRON_VERSION = "5.1.1-dev.69";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     SUPPORTED_ALIASES = ["wai"];
     SCAN_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
@@ -1770,7 +1770,7 @@ function typeSourceFiles(type) {
   for (const method2 of type.methods ?? []) add(method2.sourcePath);
   return files;
 }
-var import_zod8, 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 import_zod8, 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, PortalMountSchema, 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"() {
     "use strict";
@@ -2024,6 +2024,24 @@ var init_specs = __esm({
       description: import_zod8.z.string().optional(),
       example: import_zod8.z.string().optional()
     });
+    PortalMountSchema = import_zod8.z.object({
+      /** The mounted Portal's component id. */
+      portal: import_zod8.z.string(),
+      /**
+       * The path prefixes this listener routes to the portal. A path lies under a
+       * prefix when it EQUALS it or continues it past a slash — so `/` covers the
+       * root itself and nothing else, which is what lets an app shell sit at `GET /`
+       * without swallowing every other route.
+       */
+      prefixes: import_zod8.z.array(import_zod8.z.string()),
+      /**
+       * The router entry the listener calls to hand the portal its request,
+       * exported by the PORTAL's own file (so export-conformance holds that file to
+       * it). Absent when the listener calls the portal's contract methods directly,
+       * route by route — then there is no entry to name.
+       */
+      via: import_zod8.z.string().optional()
+    });
     ComponentSpecSchema = import_zod8.z.object({
       id: SpecIdSchema,
       name: import_zod8.z.string(),
@@ -2043,6 +2061,13 @@ var init_specs = __esm({
       auth: PortalAuthSchema.optional(),
       /** Portal-only: capability → component.method dispatch table (see DispatchBindingSchema). */
       dispatch: import_zod8.z.array(DispatchBindingSchema).optional(),
+      /**
+       * Portal-only: the portals this LISTENER serves (see PortalMountSchema).
+       * Declaring the field — even as an empty array — is what marks a portal as a
+       * listener: the one kind of portal the host starts directly, so nothing else
+       * needs to mount it. Absent means "a portal something else must serve".
+       */
+      mounts: import_zod8.z.array(PortalMountSchema).optional(),
       /** Store-only: whether held state survives restart (see DurabilitySchema). */
       durability: DurabilitySchema.optional(),
       /** Orchestrator-only: what the logic may depend on; unset means a workflow (see DependencyClassSchema). */
@@ -12365,6 +12390,90 @@ var init_lifecycle_entrypoints = __esm({
   }
 });
 
+// src/core/rules/wiring/portal-mounts.ts
+function liesUnder(path71, prefix) {
+  return path71 === prefix || path71.startsWith(prefix + "/");
+}
+var portalMountsRule;
+var init_portal_mounts = __esm({
+  "src/core/rules/wiring/portal-mounts.ts"() {
+    "use strict";
+    portalMountsRule = {
+      name: "portal-mounts",
+      description: "Which listener serves which portal: a portal's routes are its methods' endpoint bindings, but nothing said which listener hands it its requests, so a portal no listener serves was unreachable without anyone noticing, and the call that mounts one crossed a boundary no contract described. A listener Portal declares its mounts \u2014 each a portal, the path prefixes routed to it, and optionally the router entry it calls \u2014 and this rule checks them against the tree: a mount must name a Portal, every HTTP endpoint of a mounted portal must lie under one of its prefixes, and every portal with HTTP endpoints must be mounted by some listener unless it is one. A path lies under a prefix when it equals it or continues it past a slash, so `/` covers only the root. Whether the named entry is really exported is the code's question, and export-conformance asks it.",
+      codes: [
+        {
+          code: "MOUNT_TARGET_NOT_PORTAL",
+          defaultSeverity: "error",
+          summary: "A listener mounts something that is not a Portal \u2014 an unknown component, or one whose type cannot serve routes"
+        },
+        {
+          code: "ENDPOINT_OUTSIDE_MOUNT",
+          defaultSeverity: "warning",
+          summary: "A mounted portal declares an HTTP endpoint under none of the prefixes its listener routes to it \u2014 a route the contract promises that no request can reach"
+        },
+        {
+          code: "UNMOUNTED_PORTAL",
+          defaultSeverity: "warning",
+          summary: "A portal declares HTTP endpoints but no listener mounts it and it declares no mounts of its own \u2014 a whole surface nothing serves"
+        }
+      ],
+      check(ctx) {
+        const httpRoutesOf = (compId) => {
+          const routes = [];
+          for (const method2 of ctx.interfaceMethodsOf(compId)) {
+            const ep = method2.endpoint;
+            if (ep?.transport === "HTTP") routes.push({ method: method2.name, verb: ep.method, path: ep.path });
+          }
+          return routes;
+        };
+        const mounted = /* @__PURE__ */ new Set();
+        for (const listener of ctx.components) {
+          if (listener.componentType !== "Portal" || !listener.mounts) continue;
+          const listenerDraft = ctx.isComponentDraft(listener.id);
+          for (const mount of listener.mounts) {
+            const target = ctx.componentMap.get(mount.portal);
+            if (!target || target.componentType !== "Portal") {
+              ctx.addIssue(
+                "error",
+                "MOUNT_TARGET_NOT_PORTAL",
+                target ? `Listener "${listener.id}" mounts "${mount.portal}" under ${mount.prefixes.map((p) => `"${p}"`).join(", ") || "no prefixes"}, but "${target.id}" is a ${target.componentType} \u2014 only a Portal serves routes, so this mount routes requests to nothing.` : `Listener "${listener.id}" mounts "${mount.portal}" under ${mount.prefixes.map((p) => `"${p}"`).join(", ") || "no prefixes"}, but no component "${mount.portal}" exists \u2014 this mount routes requests to nothing.`,
+                listener.id,
+                listenerDraft || (target ? ctx.isComponentDraft(target.id) : false)
+              );
+              continue;
+            }
+            mounted.add(target.id);
+            for (const route of httpRoutesOf(target.id)) {
+              if (mount.prefixes.some((prefix) => liesUnder(route.path, prefix))) continue;
+              ctx.addIssue(
+                "warning",
+                "ENDPOINT_OUTSIDE_MOUNT",
+                `Portal "${target.id}" binds "${route.method}" to ${route.verb} ${route.path}, but listener "${listener.id}" routes it only ${mount.prefixes.map((p) => `"${p}"`).join(", ") || "no prefixes at all"} \u2014 a route the contract promises that no request through this listener can reach. A path lies under a prefix when it equals it or continues it past a slash. Add the prefix to the mount, or move the endpoint under one it already routes.`,
+                listener.id,
+                listenerDraft || ctx.isComponentDraft(target.id)
+              );
+            }
+          }
+        }
+        for (const portal of ctx.components) {
+          if (portal.componentType !== "Portal") continue;
+          if (portal.mounts !== void 0 || mounted.has(portal.id)) continue;
+          const routes = httpRoutesOf(portal.id);
+          if (routes.length === 0) continue;
+          ctx.addIssue(
+            "warning",
+            "UNMOUNTED_PORTAL",
+            `Portal "${portal.id}" declares ${routes.length} HTTP endpoint(s), but no listener mounts it and it declares no mounts of its own \u2014 a whole surface nothing serves. Mount it on the listener that routes its requests, or, if it IS a listener the host starts directly, declare its mounts (an empty list says it serves only its own routes).`,
+            portal.id,
+            ctx.isComponentDraft(portal.id)
+          );
+        }
+      }
+    };
+  }
+});
+
 // src/core/rules/narrative-graph-projector.ts
 function stepEdges(step, ctx, followRegisterEdges) {
   if (step.type === "call" && step.targetComponent && step.targetMethod) {
@@ -14327,7 +14436,7 @@ var init_export_conformance = __esm({
     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.",
+      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 listener's mount names the router entry it calls to hand a portal its requests; both are declared publication, 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",
@@ -14340,7 +14449,7 @@ var init_export_conformance = __esm({
         {
           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"
+          summary: "A declared publication handle \u2014 a method's `exportedVia`, or the router entry a listener mounts a portal through \u2014 names an export its own source file does not have: the spec names a route to the code 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.
@@ -14386,6 +14495,30 @@ var init_export_conformance = __esm({
             draftContext
           );
         }
+        for (const listener of ctx.components) {
+          if (listener.componentType !== "Portal") continue;
+          for (const mount of listener.mounts ?? []) {
+            const handle = mount.via;
+            if (!handle) continue;
+            const portal = ctx.componentMap.get(mount.portal);
+            if (!portal) continue;
+            const files = realization.filesOf(portal.id).map(pathKey);
+            const exact = files.filter((file) => {
+              const facts = code.factsAt(file);
+              return !!facts && facts.status === "analyzed" && facts.analysisGrade === "exact";
+            });
+            const exporters = exact.filter((file) => code.factsAt(file).exportedNames.includes(handle));
+            for (const file of exporters) promise(file, handle);
+            if (exporters.length > 0 || exact.length === 0 || exact.length < files.length) continue;
+            ctx.addIssue(
+              "warning",
+              "UNREALIZED_EXPORT_HANDLE",
+              `Listener "${listener.id}" mounts portal "${portal.id}" through "${handle}", but ${files.map((f) => `"${f}"`).join(", ")} \u2014 the file(s) realizing "${portal.id}" \u2014 export no such name. A mount's \`via\` names the router entry the listener calls to hand the portal its requests, published by the portal's own files, so one they do not publish promises a route nobody can import. It allows nothing either: every export of those files is still read against the contracts. Name the entry the portal's file actually exports, export it, or drop \`via\` if the listener calls the portal's contract methods directly.`,
+              listener.id,
+              ctx.isComponentDraft(listener.id) || ctx.isComponentDraft(portal.id)
+            );
+          }
+        }
         for (const type of ctx.types) {
           if (!type.sourcePath) continue;
           promise(type.sourcePath, type.symbol ?? type.name);
@@ -15762,6 +15895,7 @@ var init_repository = __esm({
     init_dispatch_table_bindings();
     init_dispatch_step_routing();
     init_lifecycle_entrypoints();
+    init_portal_mounts();
     init_unused_detection();
     init_invoked_by_description();
     init_unused_types();
@@ -15903,6 +16037,9 @@ var init_repository = __esm({
       dispatchTableBindingsRule,
       dispatchStepRoutingRule,
       lifecycleRule,
+      // Which listener serves which portal: another declared edge into a
+      // component, so its validity reads beside dispatch and lifecycle.
+      portalMountsRule,
       // The declared entrypoint's own prose before the walk that its declaration
       // silences, then the walk, then the types no walk can reach.
       invokedByDescriptionRule,
@@ -19620,6 +19757,10 @@ function stripNamespaceFromComponent(spec, prefix) {
     dispatch: spec.dispatch?.map((b) => ({
       ...b,
       component: relativizeId(b.component, prefix)
+    })),
+    mounts: spec.mounts?.map((m) => ({
+      ...m,
+      portal: relativizeId(m.portal, prefix)
     }))
   };
 }
@@ -19768,6 +19909,7 @@ function rewriteSpecRefs(raw, remap) {
     rewriteEach(raw.dependsOn, "component");
     rewriteEach(raw.owns, "component");
     for (const binding of entries(raw.dispatch)) rewritePair(binding, "component", "method");
+    for (const mount of entries(raw.mounts)) rewrite(mount, "portal", "component");
   } else if (kind === "subsystem") {
     for (const entrypoint of entries(raw.lifecycle)) rewritePair(entrypoint, "component", "method");
     rewritePublished(raw.publicInterfaces);
@@ -19822,6 +19964,9 @@ function identityKeyOf(field, item) {
   switch (field) {
     case "dispatch":
       return str(o.capability);
+    // A listener mounts each portal once, so the portal IS the mount's identity.
+    case "mounts":
+      return str(o.portal);
     case "lifecycle":
       return `${String(o.phase)} ${String(o.component)} ${String(o.method)}`;
     case "emits":
@@ -20542,6 +20687,12 @@ var init_specs2 = __esm({
             dispatch: comp.dispatch?.map((b) => ({
               ...b,
               component: qualifyId(b.component, namespacePrefix, this.rootSubsystems)
+            })),
+            // A listener's mount names a portal id, qualified like any other
+            // component reference so a chained listener still finds its portals.
+            mounts: comp.mounts?.map((m) => ({
+              ...m,
+              portal: qualifyId(m.portal, namespacePrefix, this.rootSubsystems)
             }))
           }));
           index.interfaces = index.interfaces.map((intf) => ({
@@ -22086,6 +22237,9 @@ var init_specs2 = __esm({
               if (Array.isArray(out.dispatch)) {
                 out.dispatch = out.dispatch.map((b) => typeof b?.component === "string" ? { ...b, component: q2(b.component) } : b);
               }
+              if (Array.isArray(out.mounts)) {
+                out.mounts = out.mounts.map((m) => typeof m?.portal === "string" ? { ...m, portal: q2(m.portal) } : m);
+              }
               break;
             case "interface":
               if (typeof out.component === "string") out.component = q2(out.component);
@@ -29923,6 +30077,11 @@ function createMcpServer(options = {}) {
       method: import_zod11.z.string().describe("Method name on the serving component's interface"),
       description: import_zod11.z.string().optional()
     }).strict()).optional().describe("Portal-only: capability \u2192 component.method dispatch table for generic-handle portals. Gives the reachability walker real edges and is validated against target interfaces (UNSERVED_CAPABILITY)."),
+    mounts: import_zod11.z.array(import_zod11.z.object({
+      portal: import_zod11.z.string().describe("The mounted Portal's component id"),
+      prefixes: import_zod11.z.array(import_zod11.z.string()).describe('The path prefixes this listener routes to the portal. A path lies under a prefix when it equals it or continues it past a slash, so "/" covers only the root itself'),
+      via: import_zod11.z.string().optional().describe("The router entry the listener calls to hand the portal its request, exported by the PORTAL's own file (held to it: UNREALIZED_EXPORT_HANDLE). Omit when the listener calls the portal's contract methods directly, route by route")
+    }).strict()).optional().describe("Portal-only: the portals this LISTENER serves, each under its path prefixes and through its router entry. Declaring the field \u2014 even as an empty array \u2014 marks this portal as a listener, the one kind of portal nothing else needs to mount. Checked by portal-mounts: a mount must name a Portal (MOUNT_TARGET_NOT_PORTAL), every HTTP endpoint of a mounted portal must lie under one of its prefixes (ENDPOINT_OUTSIDE_MOUNT), and a portal with HTTP endpoints that is neither a listener nor mounted by one is reported (UNMOUNTED_PORTAL)."),
     durability: import_zod11.z.enum(["ram-projection", "durable", "read-through", "cache"]).optional().describe("Store-only \u2014 OMIT IT on any other componentType, where it is refused at the write (DURABILITY_ON_NON_STORE) and nothing is saved. Every Store should declare one (MISSING_DURABILITY): durable = persisted RAM projection (hydration read-back from a lifecycle init entrypoint required \u2014 MISSING_HYDRATION); read-through = persisted with no RAM copy (every read is the read-back, hydration exempt); ram-projection = rebuilt not restored; cache = evictable loss-safe memo state."),
     dependencyClass: import_zod11.z.enum(["pure", "read"]).optional().describe("Orchestrator-only \u2014 OMIT IT on any other componentType, where it is refused at the write (DEPENDENCY_CLASS_ON_NON_ORCHESTRATOR) and nothing is saved. Declares what logic may depend on, enforced as a Store's durability is (DEPENDENCY_CLASS_VIOLATION): pure = depends only on pure Orchestrators (a computation over the values it is handed, e.g. an arbiter or codec); read = also on read Orchestrators, Repositories, Indexes and Adapters, never calling their write methods; unset = a workflow."),
     emits: import_zod11.z.array(import_zod11.z.object({
@@ -29947,7 +30106,7 @@ function createMcpServer(options = {}) {
       inputSchema: componentInput,
       outputSchema: specWriteReceiptOutput
     },
-    ({ id, name, description, subsystem, componentType, owns, dependsOn, portalType, basePath, dispatch, durability, dependencyClass, emits, subscribesTo, ext, status: status2 }) => {
+    ({ id, name, description, subsystem, componentType, owns, dependsOn, portalType, basePath, dispatch, mounts, durability, dependencyClass, emits, subscribesTo, ext, status: status2 }) => {
       try {
         const { loadSubsystemSpec: loadSubsystemSpec2, loadComponentSpec: loadComponentSpec2 } = requireSpecs();
         const sub = loadSubsystemSpec2(subsystem);
@@ -29967,6 +30126,8 @@ function createMcpServer(options = {}) {
           ...portalType ? { portalType } : {},
           ...basePath ? { basePath } : {},
           ...dispatch ? { dispatch } : {},
+          // An EMPTY list is kept: declaring the field is what marks a listener.
+          ...mounts ? { mounts } : {},
           ...durability ? { durability } : {},
           ...dependencyClass ? { dependencyClass } : {},
           ...emits ? { emits } : {},
@@ -30557,7 +30718,7 @@ function createMcpServer(options = {}) {
       inputSchema: {
         kind: import_zod11.z.enum(["system", "subsystem", "component", "interface", "implementation", "type"]).describe("The spec kind to update (system = the singleton L0 \u2014 vision, boundaries, globalRequirements, databases, and publicInterfaces: the project gateway surface, each entry {id, name, subsystem, component, type, details, audience: project|department|instance|partner|external}; id is informational)"),
         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" AND "at" (an allow covers one occurrence, so several may share a code on one spec), 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, at, covers, reason }] }" to silence a WARNING code on this spec only (errors always surface; stale allows are flagged). An allow covers EXACTLY the occurrence it names: "at" is the site the finding names (a contract method, an import edge "from -> to", a declared edge "component -> target") and is REQUIRED for a code whose findings report one, while a finding that reports no site is covered only by an allow that names none; "covers" lists the units an aggregating finding reports, and the allow silences it only when every one is listed. 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.`),
+        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", a listener's mounts by "portal", lifecycle by phase+component+method, emits/subscribesTo by topic+event, trustedLinks by "subsystem", invariants and patterns by "id", lint.allow by "code" AND "at" (an allow covers one occurrence, so several may share a code on one spec), 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, at, covers, reason }] }" to silence a WARNING code on this spec only (errors always surface; stale allows are flagged). An allow covers EXACTLY the occurrence it names: "at" is the site the finding names (a contract method, an import edge "from -> to", a declared edge "component -> target") and is REQUIRED for a code whose findings report one, while a finding that reports no site is covered only by an allow that names none; "covers" lists the units an aggregating finding reports, and the allow silences it only when every one is listed. 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