@wairon/cli 5.1.1-dev.34 → 5.1.1-dev.35

package/dist/index.js

@@ -1113,7 +1113,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.1.1-dev.34";
+    WAIRON_VERSION = "5.1.1-dev.35";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     ARCHITECT_AGENT_ID = "agent-architect";
     ARCHITECT_TEMPLATE_ID = "architect";
@@ -18345,10 +18345,30 @@ function identityKeyOf(field, item) {
       return str(o.description);
     case "databases":
       return str(o.id) ?? str(o.name);
+    // A flow step's own arrays, addressed by the thing the author named them
+    // for. Their `step` is a RELOCATABLE number, never an identity — a switch
+    // case is the value it matches and a catch clause is the error it catches,
+    // and both survive the renumbering that moves their target. (A parallel
+    // arm falls to the default: named, it merges by name; unnamed, it carries
+    // no identity at all and the list replaces wholesale, which is the same
+    // rule everywhere else.)
+    case "cases":
+      return str(o.value);
+    case "catches":
+      return str(o.error);
     default:
       return str(o.name) ?? str(o.id);
   }
 }
+function stepFieldsFor(type) {
+  const own = STEP_TYPE_FIELDS[type] ?? [];
+  const allowed = /* @__PURE__ */ new Set([...STEP_COMMON_FIELDS, ...own]);
+  for (const field of own) {
+    const twin = STEP_LABEL_TWINS[field];
+    if (twin) allowed.add(twin);
+  }
+  return allowed;
+}
 function reportIdentityOf(field, item) {
   if (item !== null && typeof item === "object") {
     const step = item.stepNumber;
@@ -18624,7 +18644,7 @@ function findLegacySpecFiles() {
 function updateSpec(kind, id, delta, hooks) {
   return current().updateSpec(kind, id, delta, hooks);
 }
-var fs11, path16, NO_ROOT_SUBSYSTEMS, SIGNATURE_TTL_MS, SpecWorkspace, workspaces;
+var fs11, path16, NO_ROOT_SUBSYSTEMS, SIGNATURE_TTL_MS, STEP_TYPE_FIELDS, STEP_COMMON_FIELDS, STEP_LABEL_TWINS, SpecWorkspace, workspaces;
 var init_specs2 = __esm({
   "src/core/specs.ts"() {
     "use strict";
@@ -18642,6 +18662,36 @@ var init_specs2 = __esm({
     init_diagram();
     NO_ROOT_SUBSYSTEMS = /* @__PURE__ */ new Set();
     SIGNATURE_TTL_MS = 2e3;
+    STEP_TYPE_FIELDS = {
+      local: [],
+      call: ["targetComponent", "targetMethod", "auth", "detach"],
+      register: ["targetComponent", "targetMethod"],
+      dispatch: ["targetComponent", "capability", "auth", "detach"],
+      branch: ["condition", "onTrueStep", "onFalseStep"],
+      switch: ["on", "cases", "defaultStep"],
+      loop: ["loopKind", "over", "condition", "endStep"],
+      try: ["endStep", "catches", "finallyStep"],
+      parallel: ["endStep", "branches"],
+      jump: ["toStep"],
+      return: ["outcome"],
+      throw: ["error"]
+    };
+    STEP_COMMON_FIELDS = [
+      "stepNumber",
+      "label",
+      "description",
+      "type",
+      "assertsGuarantees",
+      "assertsInvariants"
+    ];
+    STEP_LABEL_TWINS = {
+      onTrueStep: "onTrueLabel",
+      onFalseStep: "onFalseLabel",
+      defaultStep: "defaultLabel",
+      endStep: "endLabel",
+      finallyStep: "finallyLabel",
+      toStep: "toLabel"
+    };
     SpecWorkspace = class {
       constructor(rootDir) {
         this.cachedIndex = null;
@@ -19879,9 +19929,39 @@ var init_specs2 = __esm({
       // Granular delta updates (sdd_update_spec)
       // -------------------------------------------------------------------------
       /**
-       * Returns non-fatal notices about the merge (e.g. an insert whose position
-       * was a jump target, so the relocated jumps now bypass the inserted step) —
-       * empty when the merge had nothing to warn about.
+       * Apply a delta to one stored spec, in this ORDER — the order is the contract,
+       * because every stage below can see what the stage above left:
+       *
+       *  1. LOAD the stored spec for the addressed kind and id; a spec that does
+       *     not exist refuses, and a mis-selected `system` kind refuses by name.
+       *  2. REFUSE unknown delta keys, whole. A key the level's schema does not
+       *     know is dropped on write, so the edit would report a success it never
+       *     performed.
+       *  3. QUALIFY the delta's id-bearing references against the spec's namespace,
+       *     BEFORE the merge — post-merge a bare id is ambiguous.
+       *  4. MERGE. Identity-keyed arrays upsert element by element and honour their
+       *     delete markers, at every depth. Narrative step deltas apply in ASCENDING
+       *     stepNumber order, each against the numbering the earlier entries of the
+       *     same delta left behind — delete step 3 and step 7 becomes step 6, so a
+       *     second delete written as 7 addresses what used to be step 8. That is why
+       *     a delete may restate the step's `label` or `description` as a guard, and
+       *     why labels are the reliable way to name a jump target. Inserts and
+       *     deletes relocate every jump field in the same narrative around them; a
+       *     step whose `type` changes is REBUILT for its new type, keeping its
+       *     description and label.
+       *  5. UNSET the fields the delta names, at the level each `unset` sits in.
+       *  6. RESOLVE symbolic `*Label` references against the MERGED numbering — after
+       *     the merge, so a delta may anchor on a label that only pre-existing steps
+       *     carry, and a label in the delta retargets the stored numeric jump it
+       *     twins. An unresolved reference aborts the whole update.
+       *  7. COMPARE with what is stored, both read through the level's canonical
+       *     schema. Equal means nothing is written and `written` is false.
+       *  8. GATE the merged spec through the caller's hook, then SAVE.
+       *
+       * Returns the change report, whose `notices` carry the non-fatal effects (an
+       * insert whose position was a jump target, so the relocated jumps now bypass
+       * the inserted step; the fields a retype dropped) — empty when the merge had
+       * nothing to say.
        */
       updateSpec(kind, id, delta, hooks) {
         const notices = [];
@@ -19995,14 +20075,113 @@ var init_specs2 = __esm({
             );
           }
         };
-        const mergeNarrative = (existingSteps, deltaSteps) => {
+        const NO_NESTED_MERGE = /* @__PURE__ */ new Set(["ext", "narrative", "unset"]);
+        const mergeElement = (existing, deltaItem) => {
+          const out = { ...existing, ...deltaItem };
+          if (!existing || typeof existing !== "object" || !deltaItem || typeof deltaItem !== "object") return out;
+          for (const [key, value] of Object.entries(deltaItem)) {
+            if (NO_NESTED_MERGE.has(key) || !Array.isArray(value) || value.length === 0) continue;
+            const before = existing[key];
+            if (before !== void 0 && !Array.isArray(before)) continue;
+            const stored = Array.isArray(before) ? before : [];
+            if (!isIdentifiedArray(key, stored, value)) continue;
+            out[key] = mergeIdentifiedArray(key, stored, value);
+          }
+          return out;
+        };
+        const retargetByLabel = (merged, deltaStep) => {
+          const out = { ...merged };
+          for (const [stepField, labelField] of Object.entries(STEP_LABEL_TWINS)) {
+            if (deltaStep?.[labelField] !== void 0 && deltaStep?.[stepField] === void 0) delete out[stepField];
+          }
+          for (const key of ["cases", "catches"]) {
+            const deltaEntries = deltaStep?.[key];
+            if (!Array.isArray(deltaEntries) || !Array.isArray(out[key])) continue;
+            const retargeted = new Set(
+              deltaEntries.filter((e) => e?.label !== void 0 && e?.step === void 0).map((e) => identityKeyOf(key, e)).filter((k) => k !== null)
+            );
+            if (!retargeted.size) continue;
+            out[key] = out[key].map((e) => {
+              const k = identityKeyOf(key, e);
+              if (k === null || !retargeted.has(k)) return e;
+              const { step, ...rest } = e;
+              return rest;
+            });
+          }
+          return out;
+        };
+        const rebuildOnRetype = (stored, deltaStep, merged, methodName) => {
+          const newType = merged?.type;
+          if (typeof newType !== "string" || stored?.type === newType) return merged;
+          if (!Object.prototype.hasOwnProperty.call(STEP_TYPE_FIELDS, newType)) return merged;
+          const allowed = stepFieldsFor(newType);
+          const stated = Object.keys(deltaStep).filter(
+            (k) => k !== "type" && deltaStep[k] !== void 0 && !allowed.has(k)
+          );
+          if (stated.length) {
+            throw new Error(
+              `Refusing to retype narrative step ${stored.stepNumber} of "${methodName}" from "${stored.type}" to "${newType}": the same delta sets ${stated.map((f) => `"${f}"`).join(", ")}, which a ${newType} step cannot carry. Drop those keys, or retype to a step type that carries them.`
+            );
+          }
+          const out = {};
+          const dropped = [];
+          for (const [key, value] of Object.entries(merged)) {
+            if (allowed.has(key)) out[key] = value;
+            else dropped.push(key);
+          }
+          if (dropped.length) {
+            notices.push(
+              `Narrative step ${stored.stepNumber} of "${methodName}" was retyped ${stored.type} -> ${newType}: ${dropped.join(", ")} dropped \u2014 a ${newType} step cannot carry ${dropped.length === 1 ? "it" : "them"}. Its description and label are kept.`
+            );
+          }
+          return out;
+        };
+        const mergeNarrative = (methodName, existingSteps, deltaSteps) => {
           let steps = [...existingSteps];
           const sortedDeltas = [...deltaSteps].sort((a, b) => a.stepNumber - b.stepNumber);
           for (const deltaStep of sortedDeltas) {
             const stepNum = deltaStep.stepNumber;
+            if (typeof stepNum !== "number") {
+              throw new Error(
+                `Refusing to update the narrative of "${methodName}": a step delta must carry the "stepNumber" it addresses, got ${JSON.stringify(stepNum ?? null)}.`
+              );
+            }
+            if ("remove" in deltaStep && typeof deltaStep.remove !== "boolean") {
+              throw new Error(
+                `Refusing to update narrative step ${stepNum} of "${methodName}": "remove" must be the boolean true, got ${JSON.stringify(deltaStep.remove)}. A non-boolean is ignored, which would leave the step in place while reporting success.`
+              );
+            }
+            if ("action" in deltaStep && deltaStep.action !== "insert" && deltaStep.action !== "delete") {
+              throw new Error(
+                `Refusing to update narrative step ${stepNum} of "${methodName}": unknown action ${JSON.stringify(deltaStep.action)} \u2014 expected "insert" or "delete", or no action at all to edit the step in place. An unknown verb is ignored, which would report success for an edit never made.`
+              );
+            }
+            if ("captureJumps" in deltaStep && deltaStep.action !== "insert") {
+              throw new Error(
+                `Refusing to update narrative step ${stepNum} of "${methodName}": "captureJumps" only means anything on an inserted step \u2014 it decides whether jumps aimed at that number follow the shifted original or land on the new step. On any other delta it is ignored.`
+              );
+            }
             if (deltaStep.action === "delete" || deltaStep.remove === true) {
               const idx = steps.findIndex((s) => s.stepNumber === stepNum);
               if (idx !== -1) {
+                const victim = steps[idx];
+                for (const field of ["label", "description"]) {
+                  if (deltaStep[field] === void 0) continue;
+                  if (victim[field] !== deltaStep[field]) {
+                    throw new Error(
+                      `Refusing to delete narrative step ${stepNum}: the delta states ${field} ${JSON.stringify(deltaStep[field])}, but step ${stepNum} holds ${JSON.stringify(victim[field] ?? null)}. Step deltas apply in ascending order against the numbering earlier entries of the same delta left behind, so a later delete can address a step that has already moved.`
+                    );
+                  }
+                }
+                if (typeof victim.endStep === "number") {
+                  const body = steps.filter((s) => s.stepNumber > stepNum && s.stepNumber <= victim.endStep);
+                  if (body.length) {
+                    const span = body.length === 1 ? `step ${body[0].stepNumber}` : `steps ${body[0].stepNumber}-${body[body.length - 1].stepNumber}`;
+                    throw new Error(
+                      `Cannot delete narrative step ${stepNum}: it is a ${victim.type} header and ${span} ${body.length === 1 ? "is" : "are"} still its body. Deleting it would leave them in place with no ${victim.type} around them \u2014 a change of meaning nothing later reports. Dissolve the region first: retype step ${stepNum} to a type that carries no region (the region fields are dropped and reported), then delete it.`
+                    );
+                  }
+                }
                 const referrers = steps.filter((s) => s.stepNumber !== stepNum).map((s) => ({ n: s.stepNumber, refs: jumpRefsTo(s, stepNum) })).filter((r) => r.refs.length > 0);
                 if (referrers.length) {
                   throw new Error(
@@ -20015,6 +20194,11 @@ var init_specs2 = __esm({
                   stepNum,
                   -1
                 ));
+              } else {
+                const present = steps.length ? ` \u2014 it has steps ${steps[0].stepNumber}-${steps[steps.length - 1].stepNumber}` : " \u2014 it has no steps";
+                throw new Error(
+                  `Refusing to delete narrative step ${stepNum}: this narrative has no step ${stepNum}${present}. Step deltas apply in ascending order against the numbering earlier entries of the same delta left behind, so a later delete can address a step that has already moved.`
+                );
               }
             } else if (deltaStep.action === "insert") {
               const capture = deltaStep.captureJumps === true;
@@ -20038,10 +20222,9 @@ var init_specs2 = __esm({
               const idx = steps.findIndex((s) => s.stepNumber === stepNum);
               if (idx !== -1) {
                 const { action, remove, ...cleanStep } = deltaStep;
-                steps[idx] = withUnset({
-                  ...steps[idx],
-                  ...cleanStep
-                }, deltaStep);
+                const stored = steps[idx];
+                const merged = withUnset(retargetByLabel(mergeElement(stored, cleanStep), cleanStep), deltaStep);
+                steps[idx] = rebuildOnRetype(stored, cleanStep, merged, methodName);
               } else {
                 const { action, remove, ...cleanStep } = deltaStep;
                 steps.push(withUnset(cleanStep, deltaStep));
@@ -20072,12 +20255,11 @@ var init_specs2 = __esm({
                 const existingMethod = merged[idx];
                 let narrative = existingMethod.narrative ? [...existingMethod.narrative] : [];
                 if (Array.isArray(deltaMethod.narrative)) {
-                  narrative = deltaMethod.narrative.length === 0 ? [] : mergeNarrative(narrative, deltaMethod.narrative);
+                  narrative = deltaMethod.narrative.length === 0 ? [] : mergeNarrative(String(deltaMethod.name), narrative, deltaMethod.narrative);
                 }
                 const { narrative: _, ...cleanMethod } = deltaMethod;
                 merged[idx] = withUnset({
-                  ...existingMethod,
-                  ...cleanMethod,
+                  ...mergeElement(existingMethod, cleanMethod),
                   ...deltaMethod.ext !== void 0 ? { ext: mergeExt(existingMethod.ext, deltaMethod.ext) } : {},
                   narrative
                 }, deltaMethod);
@@ -20099,12 +20281,8 @@ var init_specs2 = __esm({
                 merged.splice(idx, 1);
               } else {
                 merged[idx] = withUnset({
-                  ...merged[idx],
-                  ...deltaItem,
-                  ...deltaItem.ext !== void 0 ? { ext: mergeExt(merged[idx].ext, deltaItem.ext) } : {},
-                  // An interface method's findings upsert and delete by code, like
-                  // lint.allow; an empty list still clears them outright.
-                  ...Array.isArray(deltaItem.findings) && deltaItem.findings.length > 0 ? { findings: mergeIdentifiedArray("findings", merged[idx].findings ?? [], deltaItem.findings) } : {}
+                  ...mergeElement(merged[idx], deltaItem),
+                  ...deltaItem.ext !== void 0 ? { ext: mergeExt(merged[idx].ext, deltaItem.ext) } : {}
                 }, deltaItem);
               }
             } else {
@@ -20123,7 +20301,7 @@ var init_specs2 = __esm({
               if (deltaItem.remove === true || deltaItem.action === "delete") {
                 merged.splice(idx, 1);
               } else {
-                merged[idx] = withUnset({ ...merged[idx], ...deltaItem }, deltaItem);
+                merged[idx] = withUnset(mergeElement(merged[idx], deltaItem), deltaItem);
               }
             } else {
               assertUnmatchedIsAnAddition(deltaItem, keyOf(deltaItem), merged.map(keyOf), "entry");
@@ -20142,10 +20320,7 @@ var init_specs2 = __esm({
               if (deltaItem.remove === true || deltaItem.action === "delete") {
                 merged.splice(idx, 1);
               } else {
-                merged[idx] = withUnset({
-                  ...merged[idx],
-                  ...deltaItem
-                }, deltaItem);
+                merged[idx] = withUnset(mergeElement(merged[idx], deltaItem), deltaItem);
               }
             } else {
               assertUnmatchedIsAnAddition(deltaItem, piKey(deltaItem), merged.map(piKey), "publicInterface");
@@ -20163,7 +20338,7 @@ var init_specs2 = __esm({
             const isDelete = deltaItem?.remove === true || deltaItem?.action === "delete";
             if (idx !== -1) {
               if (isDelete) merged.splice(idx, 1);
-              else merged[idx] = withUnset({ ...merged[idx], ...deltaItem }, deltaItem);
+              else merged[idx] = withUnset(mergeElement(merged[idx], deltaItem), deltaItem);
             } else {
               if (key !== null) {
                 assertUnmatchedIsAnAddition(