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

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.34";
+    WAIRON_VERSION = "5.1.1-dev.35";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     SUPPORTED_ALIASES = ["wai"];
     SCAN_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
@@ -23562,10 +23562,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;
@@ -23841,7 +23861,7 @@ function findLegacySpecFiles() {
 function updateSpec(kind, id, delta, hooks) {
   return current().updateSpec(kind, id, delta, hooks);
 }
-var fs17, path23, NO_ROOT_SUBSYSTEMS, SIGNATURE_TTL_MS, SpecWorkspace, workspaces;
+var fs17, path23, 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";
@@ -23859,6 +23879,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;
@@ -25096,9 +25146,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 = [];
@@ -25212,14 +25292,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(
@@ -25232,6 +25411,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;
@@ -25255,10 +25439,9 @@ var init_specs2 = __esm({
               const idx = steps.findIndex((s) => s.stepNumber === stepNum);
               if (idx !== -1) {
                 const { action, remove: remove2, ...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: remove2, ...cleanStep } = deltaStep;
                 steps.push(withUnset(cleanStep, deltaStep));
@@ -25289,12 +25472,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);
@@ -25316,12 +25498,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 {
@@ -25340,7 +25518,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");
@@ -25359,10 +25537,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");
@@ -25380,7 +25555,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(
@@ -26389,7 +26564,7 @@ var init_status = __esm({
 // src/core/authoring.ts
 function candidateOptions() {
   try {
-    const config = projectConfigRepository.load();
+    const config = loadProjectConfig2();
     return config ? { rules: config.rules, projectType: config.projectType } : {};
   } catch {
     return {};
@@ -26422,7 +26597,7 @@ var init_authoring = __esm({
     init_specs2();
     init_validation();
     init_candidate();
-    init_project_config();
+    init_core();
   }
 });
 
@@ -27718,7 +27893,7 @@ NOTICE:
       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", an interface method's findings by "code", boundaries by "name", globalRequirements by "description". 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). Renumbering RELOCATES every flow jump field (onTrueStep/onFalseStep/cases.step/defaultStep/endStep/catches.step/finallyStep/toStep) in the same narrative; deleting a step that is a jump target is rejected until the referrers are retargeted. 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). 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).`)
+        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).`)
       }
     },
     ({ kind, id, delta }) => {