@wairon/cli 5.1.1-dev.36 → 5.1.1-dev.38

package/dist/index.js

@@ -1113,7 +1113,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.1.1-dev.36";
+    WAIRON_VERSION = "5.1.1-dev.38";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     ARCHITECT_AGENT_ID = "agent-architect";
     ARCHITECT_TEMPLATE_ID = "architect";
@@ -1823,7 +1823,13 @@ var init_specs = __esm({
     GuaranteeSchema = import_zod8.z.string().min(1);
     MethodParamSchema = import_zod8.z.object({
       name: import_zod8.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_zod8.z.string(),
       description: import_zod8.z.string().optional(),
       optional: import_zod8.z.boolean().optional()
@@ -1841,8 +1847,9 @@ var init_specs = __esm({
       description: import_zod8.z.string(),
       signature: import_zod8.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_zod8.z.string(),
-      // e.g. "Promise<void>"
       /** Structured parameters (authoritative for type checking when present). */
       params: import_zod8.z.array(MethodParamSchema).optional(),
       /** Concrete wire binding for this method when its component is a Portal (set via sdd_set_endpoints). */
@@ -2111,8 +2118,10 @@ var init_specs = __esm({
     TypeKindSchema = import_zod8.z.enum(["entity", "value-object"]);
     TypeFieldSchema = import_zod8.z.object({
       name: import_zod8.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_zod8.z.string(),
-      // a primitive, or another type id (qualified across subsystems, e.g. "billing.Invoice")
       description: import_zod8.z.string().optional(),
       optional: import_zod8.z.boolean().default(false),
       /**
@@ -18471,6 +18480,117 @@ function specChanges(before, after, prefix = "") {
   if (JSON.stringify(before) === JSON.stringify(after)) return [];
   return [{ path: prefix, change: "set", before: summarizeValue(before), after: summarizeValue(after) }];
 }
+function identityFieldsOf(field) {
+  switch (field) {
+    case "dispatch":
+      return ["capability"];
+    case "lifecycle":
+      return ["phase", "component", "method"];
+    case "emits":
+    case "subscribesTo":
+      return ["topic", "event"];
+    case "trustedLinks":
+      return ["subsystem"];
+    case "allow":
+    case "findings":
+      return ["code"];
+    case "invariants":
+    case "patterns":
+      return ["id"];
+    case "boundaries":
+      return ["name"];
+    case "globalRequirements":
+      return ["description"];
+    case "databases":
+      return ["id", "name"];
+    case "cases":
+      return ["value"];
+    case "catches":
+      return ["error"];
+    case "narrative":
+      return ["stepNumber"];
+    default:
+      return ["name", "id"];
+  }
+}
+function carriesEditMarker(item) {
+  if (item === null || typeof item !== "object") return false;
+  const o = item;
+  return o.action !== void 0 || o.remove !== void 0;
+}
+function ineffectiveDeltaPaths(delta, merged, stored) {
+  const out = [];
+  const isPlain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+  const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+  const at = (prefix, key) => prefix ? `${prefix}.${key}` : key;
+  const say = (path27, why) => {
+    out.push(`${path27} \u2014 ${why}`);
+  };
+  const walkValue = (d, m, s, path27, field) => {
+    if (Array.isArray(d)) {
+      if (!Array.isArray(m)) {
+        say(path27, "the level does not have this field, so the write dropped it");
+        return;
+      }
+      if (field === "narrative" && d.some(carriesEditMarker)) return;
+      for (const element of d) {
+        if (carriesEditMarker(element)) continue;
+        const key = reportIdentityOf(field, element);
+        if (key === null) {
+          if (!same(m, d)) say(path27, "the level does not keep this value, so the write dropped it");
+          else if (same(s, d)) say(path27, "the stored spec already held this value");
+          return;
+        }
+        const mMatch = m.find((i) => reportIdentityOf(field, i) === key);
+        const sMatch = Array.isArray(s) ? s.find((i) => reportIdentityOf(field, i) === key) : void 0;
+        if (mMatch === void 0) {
+          say(at(path27, key), "the write did not store this element");
+          continue;
+        }
+        walk2(element, mMatch, sMatch, at(path27, key), field);
+      }
+      return;
+    }
+    if (isPlain(d)) {
+      if (!isPlain(m)) {
+        say(path27, "the level does not have this field, so the write dropped it");
+        return;
+      }
+      walk2(d, m, s, path27, field);
+      return;
+    }
+    if (!same(m, d)) say(path27, "the write did not store it \u2014 the level's schema does not keep this value");
+    else if (same(s, d)) say(path27, "the stored spec already held this value");
+  };
+  function walk2(d, m, s, path27, container) {
+    for (const [key, value] of Object.entries(d)) {
+      if (DELTA_VERBS.has(key) || JUMP_LABEL_TWINS.has(key)) continue;
+      if (key === "label" && LABEL_TWIN_CONTAINERS.has(container)) continue;
+      if (identityFieldsOf(container).includes(key)) continue;
+      if (key === "unset") {
+        for (const name of Array.isArray(value) ? value : []) {
+          if (typeof name !== "string") continue;
+          const had = isPlain(s) && s[name] !== void 0;
+          const still = isPlain(m) && m[name] !== void 0;
+          if (!had) say(at(path27, name), "unset named a field the stored spec did not have");
+          else if (still) say(at(path27, name), "unset did not remove it");
+        }
+        continue;
+      }
+      if (value === void 0 || value === null) continue;
+      const here = at(path27, key);
+      const mValue = isPlain(m) ? m[key] : void 0;
+      const sValue = isPlain(s) ? s[key] : void 0;
+      if (mValue === void 0) {
+        say(here, "the level does not have this field, so the write dropped it");
+        continue;
+      }
+      walkValue(value, mValue, sValue, here, key);
+    }
+  }
+  walk2(delta, merged, stored, "", "");
+  return out;
+}
 function workspaceFor(rootDir) {
   const key = path16.resolve(rootDir);
   let ws = workspaces.get(key);
@@ -18696,10 +18816,10 @@ function restoreSpecFiles(snapshot) {
 function findLegacySpecFiles() {
   return current().findLegacySpecFiles();
 }
-function updateSpec(kind, id, delta, hooks) {
-  return current().updateSpec(kind, id, delta, hooks);
+function updateSpec(kind, id, delta, hooks, dryRun) {
+  return current().updateSpec(kind, id, delta, hooks, dryRun);
 }
-var fs11, path16, NO_ROOT_SUBSYSTEMS, SIGNATURE_TTL_MS, SpecWorkspace, workspaces;
+var fs11, path16, NO_ROOT_SUBSYSTEMS, SIGNATURE_TTL_MS, DELTA_VERBS, JUMP_LABEL_TWINS, LABEL_TWIN_CONTAINERS, SpecWorkspace, workspaces;
 var init_specs2 = __esm({
   "src/core/specs.ts"() {
     "use strict";
@@ -18717,6 +18837,16 @@ var init_specs2 = __esm({
     init_diagram();
     NO_ROOT_SUBSYSTEMS = /* @__PURE__ */ new Set();
     SIGNATURE_TTL_MS = 2e3;
+    DELTA_VERBS = /* @__PURE__ */ new Set(["action", "remove", "captureJumps"]);
+    JUMP_LABEL_TWINS = /* @__PURE__ */ new Set([
+      "onTrueLabel",
+      "onFalseLabel",
+      "defaultLabel",
+      "endLabel",
+      "finallyLabel",
+      "toLabel"
+    ]);
+    LABEL_TWIN_CONTAINERS = /* @__PURE__ */ new Set(["cases", "catches", "branches"]);
     SpecWorkspace = class {
       constructor(rootDir) {
         this.cachedIndex = null;
@@ -19432,6 +19562,9 @@ var init_specs2 = __esm({
         const existing = this.loadSubsystemSpec(spec.id);
         if (existing) {
           specToWrite.createdAt = existing.createdAt;
+          if (!opts?.allowStatusDemotion && existing.status && (!spec.status || spec.status === "draft")) {
+            specToWrite.status = existing.status;
+          }
         }
         specToWrite.updatedAt = opts?.preserveUpdatedAt && existing?.updatedAt ? existing.updatedAt : (/* @__PURE__ */ new Date()).toISOString();
         writeYamlFile(p, parseOrThrow(SubsystemSpecSchema, specToWrite, "subsystem", spec.id));
@@ -19980,15 +20113,22 @@ var init_specs2 = __esm({
        *     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.
+       *     schema. Equal means nothing is written and `written` is false. The same
+       *     comparison names every delta path the write did NOT act on — one the
+       *     schema drops at a depth the permissive delta cannot refuse, one the
+       *     stored spec already held, an `unset` that removed nothing.
+       *  8. GATE the merged spec through the caller's hook. A DRY RUN stops here
+       *     and answers with the report it would have produced — after the gate, so
+       *     it accounts for a write that would really be accepted, and before the
+       *     stamp, so not one byte of the stored file moves.
+       *  9. STAMP updatedAt and 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) {
+      updateSpec(kind, id, delta, hooks, dryRun = false) {
         const notices = [];
         const result = (() => {
           switch (kind) {
@@ -20467,7 +20607,8 @@ var init_specs2 = __esm({
         const unsetFields = Array.isArray(delta.unset) ? delta.unset.filter((f) => typeof f === "string") : [];
         const { unset: _unset, ...mergeableDelta } = delta;
         const storedBefore = JSON.parse(JSON.stringify(result));
-        const mergedResult = mergeDelta(result, qualifyDeltaRefs(mergeableDelta));
+        const qualifiedDelta = qualifyDeltaRefs(mergeableDelta);
+        const mergedResult = mergeDelta(result, qualifiedDelta);
         for (const field of unsetFields) delete mergedResult[field];
         if (kind === "implementation" && Array.isArray(mergedResult.methods)) {
           const labelErrors = [];
@@ -20485,20 +20626,41 @@ var init_specs2 = __esm({
           delete value.updatedAt;
           return value;
         };
-        const changes = specChanges(canonical(storedBefore), canonical(mergedResult));
+        const canonicalStored = canonical(storedBefore);
+        const canonicalMerged = canonical(mergedResult);
+        const changes = specChanges(canonicalStored, canonicalMerged);
+        const ineffective = ineffectiveDeltaPaths(
+          { ...qualifiedDelta, ...unsetFields.length ? { unset: unsetFields } : {} },
+          canonicalMerged,
+          canonicalStored
+        );
         if (changes.length === 0) {
           return {
             kind,
             id,
             written: false,
+            dryRun,
             changes,
+            ineffective,
             notices,
-            summary: `No change to ${kind} "${id}" \u2014 the delta matches what is stored, so nothing was written.`
+            summary: `No change to ${kind} "${id}" \u2014 the delta matches what is stored, so nothing ${dryRun ? "would be" : "was"} written.`
           };
         }
-        mergedResult.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
         const gateNotices = hooks?.gate?.(kind, mergedResult);
         if (gateNotices?.length) notices.push(...gateNotices);
+        if (dryRun) {
+          return {
+            kind,
+            id,
+            written: false,
+            dryRun: true,
+            changes,
+            ineffective,
+            notices,
+            summary: `Dry run on ${kind} "${id}": ${changes.length} change${changes.length === 1 ? "" : "s"} would be made. Nothing was written.`
+          };
+        }
+        mergedResult.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
         const opts = {
           allowStatusDemotion: Object.prototype.hasOwnProperty.call(delta, "status")
         };
@@ -20507,7 +20669,7 @@ var init_specs2 = __esm({
             this.saveSystemSpec(mergedResult);
             break;
           case "subsystem":
-            this.saveSubsystemSpec(mergedResult);
+            this.saveSubsystemSpec(mergedResult, opts);
             break;
           case "component":
             notices.push(...this.saveComponentSpec(mergedResult, opts));
@@ -20526,7 +20688,9 @@ var init_specs2 = __esm({
           kind,
           id,
           written: true,
+          dryRun: false,
           changes,
+          ineffective,
           notices,
           summary: `Updated ${kind} "${id}": ${changes.length} change${changes.length === 1 ? "" : "s"}.`
         };
@@ -26274,6 +26438,7 @@ __export(src_exports, {
   implementationSourceFiles: () => implementationSourceFiles,
   importSpecTree: () => importSpecTree,
   importSurface: () => importSurface,
+  ineffectiveDeltaPaths: () => ineffectiveDeltaPaths,
   inspectChainedRoots: () => inspectChainedRoots,
   inspectTreeArchive: () => inspectTreeArchive2,
   installPackFromDirectory: () => installPackFromDirectory,
@@ -27001,6 +27166,7 @@ function loadProjectConfig4() {
   implementationSourceFiles,
   importSpecTree,
   importSurface,
+  ineffectiveDeltaPaths,
   inspectChainedRoots,
   inspectTreeArchive,
   installPackFromDirectory,