@wairon/cli 5.1.1-dev.92 → 5.1.1-dev.93

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.92";
+    WAIRON_VERSION = "5.1.1-dev.93";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     SUPPORTED_ALIASES = ["wai"];
     SCAN_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
@@ -212,6 +212,7 @@ __export(fs_exports, {
   getProjectRootOverride: () => getProjectRootOverride,
   getRequestParentReach: () => getRequestParentReach,
   getRequestProjectRoot: () => getRequestProjectRoot,
+  getWriteReach: () => getWriteReach,
   isOutsideRoot: () => isOutsideRoot,
   listFiles: () => listFiles,
   listFilesRecursive: () => listFilesRecursive,
@@ -222,7 +223,9 @@ __export(fs_exports, {
   runWithProjectRoot: () => runWithProjectRoot,
   setProjectRoot: () => setProjectRoot,
   writeFile: () => writeFile,
-  writeFileIfChanged: () => writeFileIfChanged
+  writeFileIfChanged: () => writeFileIfChanged,
+  writeReachDenials: () => writeReachDenials,
+  writeReachPermits: () => writeReachPermits
 });
 function ensureDir(dirPath) {
   fs3.mkdirSync(dirPath, { recursive: true });
@@ -277,6 +280,17 @@ function listFilesRecursive(dirPath, ext) {
   }
   return files;
 }
+function writeReachPermits(reach2, root, subsystemId) {
+  const own = subsystemId === null ? void 0 : reach2.subsystems.find((s) => s.subsystemId === subsystemId && sameRoot(s.root, root));
+  if (own) return own.writable;
+  return !reach2.unwritableRoots.some((r) => sameRoot(r, root));
+}
+function writeReachDenials(reach2, root) {
+  return reach2.subsystems.filter((s) => !s.writable && sameRoot(s.root, root));
+}
+function getWriteReach() {
+  return requestRootStore.getStore()?.writeReach ?? null;
+}
 function currentRootBinding() {
   return requestRootStore.getStore();
 }
@@ -291,7 +305,8 @@ function runWithProjectBinding(dir, reach2, fn) {
       parentReach: reach2.parentReach,
       ...reach2.narrowed ? { narrowed: true } : {},
       ...reach2.unwritableRoots ? { unwritableRoots: reach2.unwritableRoots.map((r) => path4.resolve(r)) } : {},
-      ...reach2.hostedLookup ? { hostedLookup: reach2.hostedLookup } : {}
+      ...reach2.hostedLookup ? { hostedLookup: reach2.hostedLookup } : {},
+      ...reach2.writeReach ? { writeReach: reach2.writeReach } : {}
     },
     fn
   );
@@ -369,7 +384,7 @@ function aiDirAt(root, ...segments) {
   const base = !fs3.existsSync(waiPath) && fs3.existsSync(waironPath) ? waironPath : waiPath;
   return path4.join(base, ...segments);
 }
-var fs3, path4, import_node_async_hooks, projectRootOverride, requestRootStore;
+var fs3, path4, import_node_async_hooks, projectRootOverride, sameRoot, requestRootStore;
 var init_fs = __esm({
   "src/utils/fs.ts"() {
     "use strict";
@@ -377,6 +392,7 @@ var init_fs = __esm({
     path4 = __toESM(require("path"));
     import_node_async_hooks = require("async_hooks");
     projectRootOverride = null;
+    sameRoot = (a, b) => path4.resolve(a) === path4.resolve(b);
     requestRootStore = new import_node_async_hooks.AsyncLocalStorage();
   }
 });
@@ -24970,6 +24986,28 @@ var init_exports2 = __esm({
 });
 
 // src/core/specs.ts
+function deniedOwners(reach2, owners) {
+  const seen = /* @__PURE__ */ new Set();
+  const denied = [];
+  for (const o of owners) {
+    const key = `${path23.resolve(o.root)}|${o.subsystemId ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (writeReachPermits(reach2, o.root, o.subsystemId)) continue;
+    const rule = o.subsystemId === null ? void 0 : reach2.subsystems.find((s) => s.subsystemId === o.subsystemId && path23.resolve(s.root) === path23.resolve(o.root));
+    denied.push(o.subsystemId === null ? `project "${o.project}" itself (a spec of no subsystem, decided at the project rung)` : `subsystem "${o.subsystemId}" of project "${o.project}" (decided by ${rule?.decidedBy ?? "the project rung"})`);
+  }
+  return denied;
+}
+function assertSpecWritesPermitted(owners, what) {
+  const reach2 = getWriteReach();
+  if (!reach2) return;
+  const denied = deniedOwners(reach2, owners);
+  if (denied.length === 0) return;
+  throw new SubsystemWriteDenied(
+    `SubsystemWriteDenied: ${what} would change ${denied.length === 1 ? "a spec" : "specs"} this request may not change \u2014 ${denied.join("; ")}. Nothing was written.`
+  );
+}
 function unknownKeysIn(raw, parsed, at, out) {
   if (Array.isArray(raw)) {
     if (!Array.isArray(parsed) || parsed.length !== raw.length) return;
@@ -26686,10 +26724,18 @@ function normalizeReferences(kind, id) {
 function rewriteReferences(kind, id, edits) {
   return current().respellReferences(kind, id, edits);
 }
+function assertSpecsInReach(targets, what, projectRung = false) {
+  if (!getWriteReach()) return;
+  const ws = current();
+  const writable = ["system", "subsystem", "component", "interface", "implementation", "type"];
+  const owners = targets.map((t) => ws.specOwner(t.kind, t.kind === "system" ? null : (writable.includes(t.kind) ? ws.load(t.kind, t.id) : null) ?? { id: t.id }));
+  if (projectRung) owners.push(ws.specOwner("system", null));
+  assertSpecWritesPermitted(owners, what);
+}
 function moveMethods(from, to, methods, hooks, dryRun) {
   return current().moveMethods(from, to, methods, hooks, dryRun);
 }
-var fs16, path23, crypto5, PartReadOnly, PART_FORBIDDEN_FIELDS, IMPORTABLE_POSITIONS, SIGNATURE_TTL_MS, COMPONENT_AUTH_SOURCE, STEP_JUMP_FIELDS, STEP_JUMP_LISTS, DELTA_VERBS, JUMP_LABEL_TWINS, LABEL_TWIN_CONTAINERS, SpecWorkspace, DEFAULT_DEPENDENCY_LIMIT, PROSE_FIELDS, DELTA_JUMP_PINS, workspaces, lastServedBinding;
+var fs16, path23, crypto5, PartReadOnly, SubsystemWriteDenied, PART_FORBIDDEN_FIELDS, IMPORTABLE_POSITIONS, SIGNATURE_TTL_MS, COMPONENT_AUTH_SOURCE, STEP_JUMP_FIELDS, STEP_JUMP_LISTS, DELTA_VERBS, JUMP_LABEL_TWINS, LABEL_TWIN_CONTAINERS, SpecWorkspace, DEFAULT_DEPENDENCY_LIMIT, PROSE_FIELDS, DELTA_JUMP_PINS, workspaces, lastServedBinding;
 var init_specs2 = __esm({
   "src/core/specs.ts"() {
     "use strict";
@@ -26722,6 +26768,12 @@ var init_specs2 = __esm({
         this.name = "PartReadOnly";
       }
     };
+    SubsystemWriteDenied = class extends WaironError {
+      constructor(message) {
+        super(message);
+        this.name = "SubsystemWriteDenied";
+      }
+    };
     PART_FORBIDDEN_FIELDS = ["members", "externals", "rules", "extensions", "composition", "targets"];
     IMPORTABLE_POSITIONS = /* @__PURE__ */ new Set(["dependsOn", "dispatch", "mounts", "narrative"]);
     SIGNATURE_TTL_MS = 2e3;
@@ -27397,6 +27449,92 @@ var init_specs2 = __esm({
           `The spec file ${file} belongs to the part "${held.part.alias}", fetched from git (${held.source?.git ?? "its repository"} at ${held.part.commit ?? "its pinned commit"}): a git part is read-only here. Edit it in its own repository, commit it there, and take it in with \`wairon member update ${held.part.alias}\`. Nothing was written.`
         );
       }
+      /**
+       * spec_registry.save step 5 / delete step 2: inside a hosted request, may the
+       * request change this spec? Judged against the request's write reach with the
+       * home's project root and the spec's owning subsystem — the document written
+       * and, when a stored document is replaced or removed, the one stored (a
+       * component moved out of a subsystem changes that subsystem too). Outside a
+       * hosted request nothing is judged.
+       */
+      assertHomeInReach(file, kind, document) {
+        if (!getWriteReach()) return;
+        const raw = this.homeRootOf(file);
+        const owners = [];
+        if (document !== null) owners.push(this.documentOwner(raw, kind, document));
+        if (pathExists(file)) {
+          try {
+            owners.push(this.documentOwner(raw, kind, readSpecFile(file)));
+          } catch {
+          }
+        }
+        assertSpecWritesPermitted(owners, `writing ${kind} spec ${path23.basename(path23.dirname(file))}/${path23.basename(file)}`);
+      }
+      /** The project root a spec file is homed under: the root whose specs folder, or one of whose parts' folders, holds it (deepest wins). */
+      homeRootOf(file) {
+        this.scanAll();
+        let best;
+        let depth = -1;
+        for (const raw of this.cachedRawRoots) {
+          const homes = [aiPathsAt(raw.dir).specsDir(), ...raw.record.parts.map((p) => p.directory).filter((d) => d !== void 0)];
+          for (const home of homes) {
+            if (isWithin(home, file) && path23.resolve(home).length > depth) {
+              best = raw;
+              depth = path23.resolve(home).length;
+            }
+          }
+        }
+        if (!best) return { dir: this.rootDir, namespace: "", project: path23.basename(this.rootDir) };
+        return { dir: best.dir, namespace: best.record.namespace, project: idOf(best) ?? (best.record.namespace || path23.basename(best.dir)) };
+      }
+      /**
+       * The owner of one spec DOCUMENT as stored in its root (its references local
+       * to that root): a subsystem is its own, a component or type names its
+       * subsystem, an interface or implementation follows its component; the L0, a
+       * system-level type and a type group belong to no subsystem.
+       */
+      documentOwner(root, kind, document) {
+        const doc = document ?? {};
+        const local = (v) => typeof v === "string" && v ? splitNamespace(v).localId : null;
+        const key = (v) => typeof v === "string" && v ? keyIn(root.namespace, splitNamespace(v).localId) : null;
+        let subsystemId = null;
+        if (kind === "subsystem") subsystemId = local(doc.id);
+        else if (kind === "component" || kind === "type") subsystemId = local(doc.subsystem);
+        else if (kind === "interface") subsystemId = this.componentSubsystem(key(doc.component));
+        else if (kind === "implementation") {
+          const contract = key(doc.contract);
+          subsystemId = this.componentSubsystem(contract ? this.loadInterfaceSpec(contract)?.component ?? null : null);
+        }
+        return { root: root.dir, project: root.project, subsystemId };
+      }
+      /** The local id of a component's subsystem, by the component's key; null when no such component is stored. */
+      componentSubsystem(componentKey) {
+        if (!componentKey) return null;
+        const subsystem = this.loadComponentSpec(componentKey)?.subsystem;
+        return subsystem ? splitNamespace(subsystem).localId : null;
+      }
+      /**
+       * The owner of one IN-MEMORY spec (its references keys, as the loader binds
+       * them) — what a multi-spec write (a rename, a method move) judges before its
+       * first write. `staged` answers a spec the write itself creates.
+       */
+      specOwner(kind, spec, staged) {
+        this.scanAll();
+        const id = kind === "system" ? "" : String(spec?.id ?? "");
+        const namespace = (kind === "system" ? "" : this.ownerKeyOf(id)) ?? "";
+        const raw = this.cachedRawRoots.find((r) => r.record.namespace === namespace);
+        const root = raw ? { dir: raw.dir, project: idOf(raw) ?? (namespace || path23.basename(raw.dir)) } : { dir: this.rootDir, project: path23.basename(this.rootDir) };
+        const localOfKey = (v) => v ? splitNamespace(v).localId : null;
+        let subsystemId = null;
+        if (kind === "subsystem") subsystemId = localOfKey(id);
+        else if (kind === "component" || kind === "type") subsystemId = localOfKey(spec?.subsystem);
+        else if (kind === "interface") subsystemId = this.componentSubsystem(spec?.component ?? null);
+        else if (kind === "implementation" && spec?.contract) {
+          const component = this.loadInterfaceSpec(spec.contract)?.component ?? staged?.("interface", spec.contract)?.component ?? null;
+          subsystemId = this.componentSubsystem(component);
+        }
+        return { root: root.dir, project: root.project, subsystemId };
+      }
       /**
        * The key one spec file is approved under (stage 8): its path from the bound
        * root, POSIX — or, for a part's file, `members/<alias>/<path inside the
@@ -27407,13 +27545,15 @@ var init_specs2 = __esm({
         return approvalKeyIn(file, this.rootDir, this.cachedRoots[0]?.parts ?? []);
       }
       /** The file store's write, at a home the writer resolved — a part's folder included, a git part's refused. */
-      writeHome(file, document) {
+      writeHome(file, document, kind) {
         this.assertHomeWritable(file);
+        this.assertHomeInReach(file, kind, document);
         writeSpecFile(file, document);
       }
       /** The file store's delete, pruning up to the specs folder the file lives in (its part's, for a part's file). */
-      removeHome(file) {
+      removeHome(file, kind) {
         this.assertHomeWritable(file);
+        this.assertHomeInReach(file, kind, null);
         const part = this.partHolding(file)?.part;
         return removeSpecFile(file, part?.directory ? aiPathsAt(part.directory).specsDir() : this.paths.specsDir());
       }
@@ -27764,6 +27904,7 @@ var init_specs2 = __esm({
       }
       saveSystemSpec(spec) {
         const p = this.paths.specsSystem();
+        this.assertHomeInReach(p, "system", spec);
         ensureDir(path23.dirname(p));
         writeSpecFile(p, parseOrThrow(SystemSpecSchema, spec, "system", spec.name));
         invalidateSpecCache();
@@ -27914,12 +28055,12 @@ var init_specs2 = __esm({
           }
         }
         specToWrite.updatedAt = opts?.preserveUpdatedAt && existing?.updatedAt ? existing.updatedAt : (/* @__PURE__ */ new Date()).toISOString();
-        this.writeHome(p, parseOrThrow(SubsystemSpecSchema, specToWrite, "subsystem", spec.id));
+        this.writeHome(p, parseOrThrow(SubsystemSpecSchema, specToWrite, "subsystem", spec.id), "subsystem");
         invalidateSpecCache();
       }
       deleteSubsystemSpec(id) {
         const p = this.getSubsystemPath(id);
-        if (!this.removeHome(p)) return false;
+        if (!this.removeHome(p, "subsystem")) return false;
         invalidateSpecCache();
         return true;
       }
@@ -27974,14 +28115,14 @@ var init_specs2 = __esm({
           );
         }
         specToWrite.updatedAt = opts?.preserveUpdatedAt && existing?.updatedAt ? existing.updatedAt : (/* @__PURE__ */ new Date()).toISOString();
-        this.writeHome(p, parseOrThrow(ComponentSpecSchema, specToWrite, "component", spec.id));
+        this.writeHome(p, parseOrThrow(ComponentSpecSchema, specToWrite, "component", spec.id), "component");
         invalidateSpecCache();
         this.normalizeComponentLayout();
         return notices;
       }
       deleteComponentSpec(id) {
         const p = this.getComponentPath(id);
-        if (!this.removeHome(p)) return false;
+        if (!this.removeHome(p, "component")) return false;
         invalidateSpecCache();
         return true;
       }
@@ -28103,13 +28244,13 @@ var init_specs2 = __esm({
           }
         }
         specToWrite.updatedAt = opts?.preserveUpdatedAt && existing?.updatedAt ? existing.updatedAt : (/* @__PURE__ */ new Date()).toISOString();
-        this.writeHome(p, parseOrThrow(InterfaceSpecSchema, specToWrite, "interface", spec.id));
+        this.writeHome(p, parseOrThrow(InterfaceSpecSchema, specToWrite, "interface", spec.id), "interface");
         invalidateSpecCache();
         return notices;
       }
       deleteInterfaceSpec(id) {
         const p = this.getInterfacePath(id);
-        if (!this.removeHome(p)) return false;
+        if (!this.removeHome(p, "interface")) return false;
         invalidateSpecCache();
         return true;
       }
@@ -28159,13 +28300,13 @@ var init_specs2 = __esm({
           }
         }
         specToWrite.updatedAt = opts?.preserveUpdatedAt && existing?.updatedAt ? existing.updatedAt : (/* @__PURE__ */ new Date()).toISOString();
-        this.writeHome(p, parseOrThrow(ImplementationSpecSchema, specToWrite, "implementation", spec.id));
+        this.writeHome(p, parseOrThrow(ImplementationSpecSchema, specToWrite, "implementation", spec.id), "implementation");
         invalidateSpecCache();
         return notices;
       }
       deleteImplementationSpec(id) {
         const p = this.getImplementationPath(id);
-        if (!this.removeHome(p)) return false;
+        if (!this.removeHome(p, "implementation")) return false;
         invalidateSpecCache();
         return true;
       }
@@ -28211,14 +28352,14 @@ var init_specs2 = __esm({
           }
         }
         specToWrite.updatedAt = opts?.preserveUpdatedAt && existing?.updatedAt ? existing.updatedAt : (/* @__PURE__ */ new Date()).toISOString();
-        this.writeHome(p, parseOrThrow(TypeSpecSchema, specToWrite, "type", spec.id));
+        this.writeHome(p, parseOrThrow(TypeSpecSchema, specToWrite, "type", spec.id), "type");
         invalidateSpecCache();
         return notices;
       }
       deleteTypeSpec(id) {
         const spec = this.loadTypeSpec(id);
         const p = this.getTypePath(id, spec?.subsystem, spec?.group);
-        if (!this.removeHome(p)) return false;
+        if (!this.removeHome(p, "type")) return false;
         invalidateSpecCache();
         return true;
       }
@@ -28241,12 +28382,12 @@ var init_specs2 = __esm({
           specToWrite.createdAt = existing.createdAt;
         }
         specToWrite.updatedAt = opts?.preserveUpdatedAt && existing?.updatedAt ? existing.updatedAt : (/* @__PURE__ */ new Date()).toISOString();
-        this.writeHome(p, parseOrThrow(GroupSpecSchema, specToWrite, "group", spec.id));
+        this.writeHome(p, parseOrThrow(GroupSpecSchema, specToWrite, "group", spec.id), "group");
         invalidateSpecCache();
       }
       deleteGroupSpec(id) {
         const p = this.getGroupPath(id);
-        if (!this.removeHome(p)) return false;
+        if (!this.removeHome(p, "group")) return false;
         invalidateSpecCache();
         return true;
       }
@@ -28444,7 +28585,7 @@ var init_specs2 = __esm({
           );
         }
         if (JSON.stringify(document) === JSON.stringify(stored)) return false;
-        this.writeHome(file, document);
+        this.writeHome(file, document, kind);
         invalidateSpecCache();
         return true;
       }
@@ -29358,6 +29499,7 @@ var init_specs2 = __esm({
           }
         }
         const carried = projectConfigRepository.rekeyCarried(rename, true);
+        this.assertMoveInReach(from, to, plan7, carried.length > 0);
         if (dryRun) {
           const edits2 = moveChangeReports([...plan7.edits.values()], true);
           return {
@@ -29397,6 +29539,14 @@ var init_specs2 = __esm({
           carried
         };
       }
+      /** Refuse a method move, naming every subsystem it may not change, before anything is written. */
+      assertMoveInReach(from, to, plan7, rekeysRegister) {
+        if (!getWriteReach()) return;
+        const staged = (kind, id) => plan7.edits.get(`${kind}:${id}`)?.after;
+        const owners = [...plan7.edits.values()].flatMap((e) => [e.before, e.after].filter((s) => s !== null && s !== void 0).map((s) => this.specOwner(e.kind, s, staged)));
+        if (rekeysRegister) owners.push(this.specOwner("system", null));
+        assertSpecWritesPermitted(owners, `moving methods from "${from}" to "${to}"`);
+      }
       /**
        * Rekey every lint allow keyed on a moved method, staging each spec it
        * changes like any other reference the move follows. An allow anchored at a
@@ -31346,7 +31496,7 @@ function restateReExports(from, to) {
     publicInterfaces: entries.map((e) => e.from === from ? { ...e, from: to } : e)
   });
 }
-function rewriteRefFields(specsDir, remap, excludeDir) {
+function rewriteRefFields(specsDir, remap, excludeDir, dryRun = false) {
   const rewritten = [];
   for (const file of listFilesRecursive(specsDir, ".yaml")) {
     if (excludeDir && isWithinDir2(excludeDir, file)) continue;
@@ -31359,12 +31509,12 @@ function rewriteRefFields(specsDir, remap, excludeDir) {
     if (!raw || typeof raw !== "object") continue;
     const kind = specKind(raw);
     if (!rewriteSpecRefs(raw, remap) || !kind) continue;
-    writeYamlFile(file, raw);
+    if (!dryRun) writeYamlFile(file, raw);
     rewritten.push({ kind, id: kind === "system" ? "system" : String(raw.id) });
   }
   return rewritten;
 }
-function rekeyLintAllows(specsDir, rename) {
+function rekeyLintAllows(specsDir, rename, dryRun = false) {
   const rewritten = [];
   for (const file of listFilesRecursive(specsDir, ".yaml")) {
     let raw;
@@ -31395,7 +31545,7 @@ function rekeyLintAllows(specsDir, rename) {
       }
     }
     if (!changed) continue;
-    writeYamlFile(file, raw);
+    if (!dryRun) writeYamlFile(file, raw);
     rewritten.push({ kind, id: specId });
   }
   return rewritten;
@@ -31473,15 +31623,22 @@ function renameComponent(componentId, newId) {
     specs: renamed.map(({ from, to }) => ({ from, to })),
     components: [{ from: componentId, to: newId }]
   };
-  projectConfigRepository.rekeyCarried(rename, true);
-  const rewrittenRefs = rewriteRefFields(aiPathsAt(getProjectRoot()).specsDir(), (ref, position) => {
+  const registerEdits = projectConfigRepository.rekeyCarried(rename, true);
+  const remap = (ref, position) => {
     if (position === "component" || position === "entity-class" || position === "auth-source") {
       return ref === componentId ? newId : ref;
     }
     if (position === "interface" && ref === movingInterface?.id) return interfaceId;
     return ref;
-  });
-  const allowsRekeyed = rekeyLintAllows(aiPathsAt(getProjectRoot()).specsDir(), rename);
+  };
+  const specsDir = aiPathsAt(getProjectRoot()).specsDir();
+  assertSpecsInReach(
+    [...renamed.map(({ kind, from }) => ({ kind, id: from })), ...rewriteRefFields(specsDir, remap, void 0, true), ...rekeyLintAllows(specsDir, rename, true)],
+    `renaming component "${componentId}"`,
+    Array.isArray(registerEdits) && registerEdits.length > 0
+  );
+  const rewrittenRefs = rewriteRefFields(specsDir, remap);
+  const allowsRekeyed = rekeyLintAllows(specsDir, rename);
   const rewritten = [...new Set([...rewrittenRefs, ...allowsRekeyed].filter((spec) => !renamed.some((moved) => moved.kind === spec.kind && moved.from === spec.id)).map((spec) => spec.id))];
   invalidateSpecCache();
   moveRenamedSpecs(componentId, newId, component, movingInterface, movingImplementation);
@@ -31559,7 +31716,18 @@ function renameMethod(componentId, methodName, newName, pinSymbol) {
       ]
     }]
   };
-  projectConfigRepository.rekeyCarried(rename, true);
+  const registerEdits = projectConfigRepository.rekeyCarried(rename, true);
+  const methodRemap = (ref, position, owner) => position === "method" && owner === componentId && ref === methodName ? newName : ref;
+  const reachDir = aiPathsAt(getProjectRoot()).specsDir();
+  assertSpecsInReach(
+    [
+      ...(rename.methods?.[0]?.specs ?? []).map((id) => ({ kind: moving.some((i) => i.id === id) ? "interface" : "implementation", id })),
+      ...rewriteRefFields(reachDir, methodRemap, void 0, true),
+      ...rekeyLintAllows(reachDir, rename, true)
+    ],
+    `renaming method "${componentId}.${methodName}"`,
+    Array.isArray(registerEdits) && registerEdits.length > 0
+  );
   for (const contract of moving) {
     saveInterfaceSpec({
       ...contract,
@@ -31582,7 +31750,7 @@ function renameMethod(componentId, methodName, newName, pinSymbol) {
   }
   invalidateSpecCache();
   const specsDir = aiPathsAt(getProjectRoot()).specsDir();
-  const retargeted = rewriteRefFields(specsDir, (ref, position, owner) => position === "method" && owner === componentId && ref === methodName ? newName : ref);
+  const retargeted = rewriteRefFields(specsDir, methodRemap);
   const allowsRekeyed = rekeyLintAllows(specsDir, rename);
   const rewritten = [...new Set([...retargeted, ...allowsRekeyed].map((spec) => spec.id))];
   const mentions = collectMentions(specsDir, methodName, moving);
@@ -41386,10 +41554,13 @@ function rehearse2(plan7) {
     return { ...plan7, refusals: [...plan7.refusals, { code: `${plan7.request.verb}-refused`, project: "", detail }] };
   }
   const changes = diff(rehearsal);
-  const outside = unwritableOwners(changes);
-  if (outside.length > 0) {
+  const refused2 = [
+    ...unwritableOwners(changes).map((o) => ({ code: "family-partial", project: o, detail: `the plan must write ${o}, which this request may not write` })),
+    ...deniedSubsystems(changes)
+  ];
+  if (refused2.length > 0) {
     discard(rehearsal);
-    return { ...plan7, refusals: [...plan7.refusals, ...outside.map((o) => ({ code: "family-partial", project: o, detail: `the plan must write ${o}, which this request may not write` }))] };
+    return { ...plan7, refusals: [...plan7.refusals, ...refused2] };
   }
   return { ...plan7, rehearsal, changes, relock: relockOf(plan7, changes) };
 }
@@ -41433,6 +41604,16 @@ function unwritableOwners(changes) {
   const owners = [...new Set(changes.map((c) => path48.resolve(c.project)))];
   return owners.filter((o) => denied.includes(o));
 }
+function deniedSubsystems(changes) {
+  const reach2 = getWriteReach();
+  if (!reach2) return [];
+  const owners = [...new Set(changes.map((c) => path48.resolve(c.project)))];
+  return owners.flatMap((o) => writeReachDenials(reach2, o).map((s) => ({
+    code: "subsystem-denied",
+    project: o,
+    detail: `the plan must change ${o}, which holds subsystem "${s.subsystemId}" this request may not change (decided by ${s.decidedBy}); a family migration reshapes its projects whole, so it needs write on every subsystem of every project it changes`
+  })));
+}
 function pathProducers(plan7, family) {
   const inside = (dir) => {
     const rel2 = path48.relative(plan7.familyRoot, dir);
@@ -48465,6 +48646,27 @@ function existingProjectRoot(dataDir, id) {
   const rec = records.find((r) => r.id === id);
   return rec ? derivedRoot(records, rec) : null;
 }
+function declaredSubsystemIds(dataDir, id) {
+  const root = rootOnDisk(dataDir, id);
+  return root ? subsystemIdsAt(root) : null;
+}
+function rootOnDisk(dataDir, id) {
+  if (!isValidProjectId(id)) return null;
+  const records = load5(dataDir);
+  const rec = records.find((r) => r.id === id);
+  const root = rec ? derivedRoot(records, rec) : null;
+  return root && fs39.existsSync(root) ? root : null;
+}
+function subsystemIdsAt(dir) {
+  return runWithProjectRoot(dir, () => loadSubsystemSpecs()).map((s) => s.id).filter((key) => !key.includes("::"));
+}
+function partSubsystemIds(dataDir, id, alias) {
+  const root = rootOnDisk(dataDir, id);
+  const decl = root ? memberDeclarationsOn(root).find((d) => d.alias === alias && d.path && !d.hosted && !d.refused) : void 0;
+  if (!root || !decl?.path) return null;
+  const dir = assertContainedProjectPath(root, decl.path);
+  return fs39.existsSync(dir) ? subsystemIdsAt(dir) : null;
+}
 function createProjectRecord(dataDir, id) {
   if (!isValidProjectId(id)) {
     throw new Error(`Invalid project id "${id}" (allowed: lowercase letters, digits, hyphen).`);
@@ -49382,6 +49584,23 @@ var fs42 = __toESM(require("fs"));
 var path64 = __toESM(require("path"));
 
 // src/server/types.ts
+var SUBSYSTEM_SCOPE_SEPARATOR = "/";
+var SUBSYSTEM_NOT_FOUND = "subsystem not found";
+function parseSubsystemScope(scopeId) {
+  const at = scopeId.indexOf(SUBSYSTEM_SCOPE_SEPARATOR);
+  if (at <= 0 || at === scopeId.length - 1) return null;
+  return { projectId: scopeId.slice(0, at), subsystemId: scopeId.slice(at + 1) };
+}
+function describeDecision(p) {
+  const setting = { "instance-admin": "the instance-admin bypass", user: "a user setting", role: "a role", "everyone-default": "the everyone-default", "instance-default": "the instance default" }[p.source];
+  if (p.source === "instance-admin" || p.source === "instance-default") return setting;
+  if (p.decidedScopeKind === "subsystem" && p.decidedScopeId) {
+    const parsed = parseSubsystemScope(p.decidedScopeId);
+    return `${setting} at subsystem ${parsed?.subsystemId ?? p.decidedScopeId} of project ${parsed?.projectId ?? ""}`.trim();
+  }
+  if (p.decidedScopeKind && p.decidedScopeKind !== "instance") return `${setting} at ${p.decidedScopeKind} ${p.decidedScopeId ?? ""}`.trim();
+  return `${setting} at the instance`;
+}
 var SSO_ADMIN_ROLE_ID = "sso-admin";
 var UNAUTHENTICATED = {
   tokenId: "",
@@ -49491,6 +49710,7 @@ function listRoles(dataDir) {
 }
 
 // src/server/permission-rules.ts
+var SUBSYSTEM_CAPABILITY = "project:write";
 var INSTANCE_ROOT = { kind: "instance" };
 var scopeKey = (kind, id) => `${kind}:${id ?? ""}`;
 function isDefinitive(value) {
@@ -49528,7 +49748,13 @@ function familyRootUnits(projectId, world) {
   const placement = world.placements.find((p) => p.projectId === familyRoot);
   return placement ? unitChain(placement.unitId, world) : [];
 }
-function ancestorChain(targetScopeKind, targetScopeId, world) {
+function ancestorChain(capability, targetScopeKind, targetScopeId, world) {
+  if (targetScopeKind === "subsystem") {
+    const parsed = parseSubsystemScope(targetScopeId);
+    if (!parsed) return [INSTANCE_ROOT];
+    const own = capability === SUBSYSTEM_CAPABILITY ? [{ kind: "subsystem", id: targetScopeId }] : [];
+    return [...own, ...ancestorChain(capability, "project", parsed.projectId, world)];
+  }
   if (targetScopeKind === "project") {
     const projects = projectChain(targetScopeId, world).map((id) => ({ kind: "project", id }));
     return [...projects, ...familyRootUnits(targetScopeId, world), INSTANCE_ROOT];
@@ -49570,7 +49796,8 @@ function subjectIdMatches(subject, assignmentSubjectId) {
   if (assignmentSubjectId === subject.subjectId) return true;
   return (subject.aliasSubjectIds ?? []).includes(assignmentSubjectId);
 }
-function decideScope(settings) {
+function decideScope(settings, kind) {
+  if (kind === "subsystem") return decideSubsystemScope(settings);
   if (isDefinitive(settings.user)) return { value: settings.user, source: "user" };
   const best = settings.roleValues.reduce(
     (acc, v) => acc === void 0 || grantRank(v) > grantRank(acc) ? v : acc,
@@ -49580,14 +49807,21 @@ function decideScope(settings) {
   if (isDefinitive(settings.everyone)) return { value: settings.everyone, source: "everyone-default" };
   return null;
 }
+function decideSubsystemScope(settings) {
+  const yesOrNo = (v) => v === "yes" || v === "no";
+  if (yesOrNo(settings.user)) return { value: settings.user, source: "user" };
+  if (settings.roleValues.includes("yes")) return { value: "yes", source: "role" };
+  if (yesOrNo(settings.everyone)) return { value: settings.everyone, source: "everyone-default" };
+  return null;
+}
 function resolvePermission(subject, capability, targetScopeKind, targetScopeId, world) {
   if (subject.instanceAdmin) {
     return { value: "yes", source: "instance-admin" };
   }
-  const chain = ancestorChain(targetScopeKind, targetScopeId, world);
+  const chain = ancestorChain(capability, targetScopeKind, targetScopeId, world);
   for (const scope of chain) {
     const settings = settingsAtScope(subject, capability, scope, world);
-    const decision = decideScope(settings);
+    const decision = decideScope(settings, scope.kind);
     if (decision) {
       return {
         value: decision.value,
@@ -49606,7 +49840,21 @@ function allScopes(world) {
     ...projectIds.map((id) => ({ kind: "project", id }))
   ];
 }
+function namedSubsystemScopes(subject, world) {
+  const ids = [
+    ...world.assignments.filter((a) => a.scopeKind === "subsystem" && a.capability === SUBSYSTEM_CAPABILITY && a.scopeId).map((a) => a.scopeId),
+    ...subject.roleBindings.filter((b) => b.scopeKind === "subsystem" && b.scopeId).map((b) => b.scopeId)
+  ];
+  return [...new Set(ids)].filter((id) => parseSubsystemScope(id) !== null);
+}
+function judgedScopes(subject, capability, world) {
+  const subsystems = capability === SUBSYSTEM_CAPABILITY ? namedSubsystemScopes(subject, world).map((id) => ({ kind: "subsystem", id })) : [];
+  return [...allScopes(world), ...subsystems];
+}
 function ancestorUnitsOf(scope, world) {
+  if (scope.kind === "subsystem") {
+    return familyRootUnits(parseSubsystemScope(scope.id)?.projectId ?? "", world).map((s) => s.id);
+  }
   if (scope.kind === "project") return familyRootUnits(scope.id, world).map((s) => s.id);
   return unitChain(scope.id, world).map((s) => s.id).filter((id) => id !== scope.id);
 }
@@ -49621,7 +49869,7 @@ function resolveVisibleScopes(subject, capability, world) {
   }
   const actionable = /* @__PURE__ */ new Map();
   const context = /* @__PURE__ */ new Map();
-  for (const scope of allScopes(world)) {
+  for (const scope of judgedScopes(subject, capability, world)) {
     const effective = resolvePermission(subject, capability, scope.kind, scope.id, world);
     if (effective.value === "yes" || effective.value === "approval") {
       actionable.set(scopeKey(scope.kind, scope.id), {
@@ -49630,6 +49878,15 @@ function resolveVisibleScopes(subject, capability, world) {
         value: effective.value,
         context: false
       });
+      const project2 = scope.kind === "subsystem" ? parseSubsystemScope(scope.id)?.projectId : void 0;
+      if (project2 !== void 0 && !context.has(scopeKey("project", project2))) {
+        context.set(scopeKey("project", project2), {
+          scopeKind: "project",
+          scopeId: project2,
+          value: resolvePermission(subject, capability, "project", project2, world).value,
+          context: true
+        });
+      }
       for (const unitId of ancestorUnitsOf(scope, world)) {
         const key = scopeKey("unit", unitId);
         if (context.has(key)) continue;
@@ -49645,6 +49902,26 @@ function resolveVisibleScopes(subject, capability, world) {
   const contextOnly = [...context.entries()].filter(([key]) => !actionable.has(key)).map(([, scope]) => scope);
   return [...actionable.values(), ...contextOnly];
 }
+function resolveSubsystemReach(subject, projectId, world) {
+  if (subject.instanceAdmin) return [];
+  const prefix = `${projectId}${SUBSYSTEM_SCOPE_SEPARATOR}`;
+  const applies = (a) => a.subjectKind === "everyone" || a.subjectKind === "user" && subjectIdMatches(subject, a.subjectId);
+  const scopeIds = [
+    ...world.assignments.filter((a) => a.scopeKind === "subsystem" && a.scopeId?.startsWith(prefix) && applies(a)).map((a) => a.scopeId),
+    ...subject.roleBindings.filter((b) => b.scopeKind === "subsystem" && b.scopeId?.startsWith(prefix)).map((b) => b.scopeId)
+  ];
+  const reach2 = [];
+  for (const scopeId of new Set(scopeIds)) {
+    const parsed = parseSubsystemScope(scopeId);
+    if (!parsed || parsed.projectId !== projectId) continue;
+    reach2.push({
+      projectId,
+      subsystemId: parsed.subsystemId,
+      permission: resolvePermission(subject, SUBSYSTEM_CAPABILITY, "subsystem", scopeId, world)
+    });
+  }
+  return reach2;
+}
 
 // src/server/authorization.ts
 function mergeRoles(stored) {
@@ -49665,15 +49942,20 @@ function gatherPermissionWorld(dataDir) {
   return gatherWorld(dataDir);
 }
 function resolveFamilyReach(dataDir, principal, projectIds) {
-  const reach2 = { readable: [], writable: [] };
+  const reach2 = { readable: [], writable: [], subsystems: [] };
   if (!principal.authenticated || !principal.permissionSubject) return reach2;
   const world = gatherPermissionWorld(dataDir);
   for (const id of projectIds) {
     if (resolvePermission(principal.permissionSubject, "project:read", "project", id, world).value === "yes") reach2.readable.push(id);
     if (resolvePermission(principal.permissionSubject, "project:write", "project", id, world).value === "yes") reach2.writable.push(id);
+    reach2.subsystems.push(...resolveSubsystemReach(principal.permissionSubject, id, world));
   }
   return reach2;
 }
+function explain2(dataDir, subject, capability, scopeKind, scopeId) {
+  const world = gatherPermissionWorld(dataDir);
+  return resolvePermission(subject, capability, scopeKind, scopeId, world);
+}
 function authorize(dataDir, principal, capability, scopeKind, scopeId) {
   if (!principal.authenticated || !principal.permissionSubject) {
     return { value: "no", source: "instance-default" };
@@ -50159,6 +50441,40 @@ function compare5(users, before, beforeId, after, afterId) {
   }
   return rows;
 }
+var subjectOfSetting = (subjectKind, subjectId) => subjectKind === "everyone" ? EVERYONE_ELSE : subjectId ?? "";
+function carryPlan(users, world, parentId, memberId, moved) {
+  const scopes = new Set(moved.map((s) => `${parentId}/${s}`));
+  const bySubject = /* @__PURE__ */ new Map();
+  for (const a of world.assignments) {
+    if (a.scopeKind !== "subsystem" || !scopes.has(a.scopeId ?? "") || a.capability !== "project:write") continue;
+    if (a.value !== "yes" && a.value !== "no") continue;
+    const subject = subjectOfSetting(a.subjectKind, a.subjectId);
+    const held = bySubject.get(subject) ?? { scopes: [], values: [] };
+    held.scopes.push(a.scopeId);
+    held.values.push(a.value);
+    bySubject.set(subject, held);
+  }
+  const own = new Set(world.assignments.filter((a) => a.scopeKind === "project" && a.scopeId === memberId && a.capability === "project:write").map((a) => subjectOfSetting(a.subjectKind, a.subjectId)));
+  const rules = [];
+  for (const [subject, held] of bySubject) {
+    if (own.has(subject)) continue;
+    rules.push({
+      from: [...held.scopes].sort(),
+      to: memberId,
+      subject,
+      kind: "assignment",
+      value: held.values.includes("no") ? "no" : "yes",
+      note: held.scopes.length > 1 ? "most restrictive wins" : "carried"
+    });
+  }
+  for (const user of users) {
+    for (const b of user.roleBindings ?? []) {
+      if (b.scopeKind !== "subsystem" || !scopes.has(b.scopeId ?? "")) continue;
+      rules.push({ from: [b.scopeId], to: memberId, subject: user.subject.userId || user.id, kind: "role", value: b.roleId, note: "not carried (can only narrow)" });
+    }
+  }
+  return rules;
+}
 function narrowing(key, members) {
   if (!key.projects.some((e) => e.includes("::"))) {
     return null;
@@ -50341,6 +50657,7 @@ function configureSync(periodicSyncMinutes, skipIfClean) {
 // src/server/members.ts
 init_fs();
 init_project();
+var EVERYONE = "everyone";
 var UPGRADE_AREAS = ["projects.json", "auth/credentials.json"];
 var UPGRADE_VERB = "member-upgrade";
 var OPERATOR = { userId: "operator:host-doctor", kind: "service", issuer: "local" };
@@ -50536,7 +50853,7 @@ function recoverData(dataDir, fix) {
   return found;
 }
 var ROOT_RENAME_REFUSED = "renaming a hosted family root's id is not supported; a member can be renamed, or the root recreated";
-function screen(dataDir, binding, tool, alias, path93) {
+function screen(dataDir, binding, tool, alias, path93, newId) {
   if (path93 !== void 0 && (tool === "sdd_add_member" || tool === "sdd_attach_member")) {
     const storage = parseMemberSource(path93).storage;
     if (storage === "path" || storage === "git") {
@@ -50554,7 +50871,10 @@ function screen(dataDir, binding, tool, alias, path93) {
   const users = listUsers(dataDir);
   const incoming = standIn(binding.projectId, alias, path93);
   const after = relink(world, [{ projectId: incoming, parentProjectId: binding.projectId }], [], [], []);
-  return { reachChanges: compare5(users, world, null, after, incoming).filter((r) => !r.equal) };
+  const reachChanges = compare5(users, world, null, after, incoming).filter((r) => !r.equal);
+  if (tool !== "sdd_promote_member" && tool !== "sdd_externalize_subsystem") return { reachChanges };
+  const moved = tool === "sdd_externalize_subsystem" ? [alias] : partSubsystemIds(dataDir, binding.projectId, alias) ?? [];
+  return { reachChanges, carried: carryPlan(users, world, binding.projectId, newId || alias, moved) };
 }
 function screenDemote(dataDir, binding, alias) {
   const declared = planMemberRecords(dataDir, binding.projectId).find((d) => d.record.parentProjectId === binding.projectId && d.qualifier.endsWith(`${SUBPROJECT_SEPARATOR}${alias}`) && d.action !== "unreadable");
@@ -50589,7 +50909,8 @@ function reconcile(dataDir, principal, projectId, touched) {
     setProjectRecordStatus(dataDir, r.id, "disabled");
     changes.push({ kind: "departed", id: r.id, detail: { parent: r.parentProjectId, memberPath: r.memberPath } });
   }
-  const reachChanges = reachOf2(users, world, changes);
+  const carried = carrySubsystemRules(dataDir, listChangedLinks(changes.filter((c) => c.kind === "registered" || c.kind === "returned")));
+  const reachChanges = [...reachOf2(users, world, changes, listAssignments(dataDir)), ...carried];
   const ids = [.../* @__PURE__ */ new Set([...touched, ...changes.map((c) => c.id)])];
   for (const id of ids) auditTouched(dataDir, principal, projectId, id, changes.find((c) => c.id === id), reachChanges);
   const commit3 = publishFamily(dataDir, ids, `wairon: reconcile the family of ${projectId} (${ids.join(", ")})`);
@@ -50612,16 +50933,28 @@ function rekey(dataDir, world, users, m) {
   if (refused2) {
     return { kind: "registered", id: newId, detail: { parent: m.record.parentProjectId, memberPath: m.record.memberPath, rekeyRefused: oldId } };
   }
-  const moved = { assignments: world.assignments.filter((a) => a.scopeKind === "project" && a.scopeId === oldId).length };
-  remapScope(dataDir, [{ oldId, newId }]);
-  remapUnitReferences(dataDir, [{ oldId, newId }], []);
+  const subsystemRemap = subsystemScopesOf(world, users, oldId).map((scopeId) => ({ oldId: scopeId, newId: `${newId}${scopeId.slice(oldId.length)}` }));
+  const moved = {
+    assignments: world.assignments.filter((a) => a.scopeKind === "project" && a.scopeId === oldId).length,
+    subsystemRules: subsystemRemap.map((r) => `${r.oldId} -> ${r.newId}`)
+  };
+  remapScope(dataDir, [{ oldId, newId }, ...subsystemRemap]);
+  remapUnitReferences(dataDir, [{ oldId, newId }, ...subsystemRemap], []);
   const keys = listCredentials(dataDir, oldId).filter((k) => k.projects.includes(oldId) && !k.revokedAt);
   for (const k of keys) renarrowCredential(dataDir, k.id, [...new Set(k.projects.map((e) => e === oldId ? newId : e))]);
   removeProjectRecord(dataDir, oldId);
   return { kind: "renamed", id: newId, previousId: oldId, detail: { ...moved, keys: keys.map((k) => k.id) } };
 }
+function subsystemScopesOf(world, users, id) {
+  const prefix = `${id}/`;
+  const ids = [
+    ...world.assignments.filter((a) => a.scopeKind === "subsystem" && a.scopeId?.startsWith(prefix)).map((a) => a.scopeId),
+    ...users.flatMap((u) => (u.roleBindings ?? []).filter((b) => b.scopeKind === "subsystem" && b.scopeId?.startsWith(prefix)).map((b) => b.scopeId))
+  ];
+  return [...new Set(ids)];
+}
 function hasOwnSettings(world, users, id) {
-  return world.assignments.some((a) => a.scopeKind === "project" && a.scopeId === id) || users.some((u) => (u.roleBindings ?? []).some((b) => b.scopeKind === "project" && b.scopeId === id));
+  return world.assignments.some((a) => a.scopeKind === "project" && a.scopeId === id) || users.some((u) => (u.roleBindings ?? []).some((b) => b.scopeKind === "project" && b.scopeId === id)) || subsystemScopesOf(world, users, id).length > 0;
 }
 function departedRecords(family, declared, changes) {
   const live = new Set(declared.filter((d) => d.action !== "unreadable").map((d) => d.record.id));
@@ -50629,16 +50962,52 @@ function departedRecords(family, declared, changes) {
   const rekeyed = new Set(changes.filter((c) => c.kind === "renamed").map((c) => c.previousId));
   return family.filter((r) => r.parentProjectId !== void 0 && r.status === "active" && !live.has(r.id) && !rekeyed.has(r.id) && !held.includes(`${r.parentProjectId}/${r.memberPath}`));
 }
-function reachOf2(users, world, changes) {
+function reachOf2(users, world, changes, assignmentsAfter) {
   const links = listChangedLinks(changes);
   const departed = changes.filter((c) => c.kind === "departed" || c.kind === "retired").map((c) => c.id);
-  const after = relink(world, links, departed, [], []);
+  const after = { ...relink(world, links, departed, [], []), assignments: assignmentsAfter };
   return changes.filter((c) => c.kind !== "renamed").flatMap((c) => {
     const before = c.kind === "registered" || c.kind === "returned" ? null : c.id;
     const now = c.kind === "departed" ? null : c.kind === "retired" ? String(c.detail.parent ?? "") || null : c.id;
     return compare5(users, world, before, after, now).filter((r) => !r.equal).map((r) => ({ ...r, memberId: c.id }));
   });
 }
+function carrySubsystemRules(dataDir, members) {
+  const rows = [];
+  for (const { projectId: memberId, parentProjectId: parentId } of members) {
+    const parentHolds = declaredSubsystemIds(dataDir, parentId) ?? [];
+    const moved = (declaredSubsystemIds(dataDir, memberId) ?? []).filter((s) => !parentHolds.includes(s));
+    if (moved.length === 0) continue;
+    const plan7 = carryPlan(listUsers(dataDir), gatherPermissionWorld(dataDir), parentId, memberId, moved);
+    for (const rule of plan7.filter((r) => r.kind === "assignment")) {
+      const everyone = rule.subject === EVERYONE;
+      setAssignment(dataDir, {
+        id: "",
+        subjectKind: everyone ? "everyone" : "user",
+        ...everyone ? {} : { subjectId: rule.subject },
+        scopeKind: "project",
+        scopeId: memberId,
+        capability: "project:write",
+        value: rule.value,
+        createdAt: ""
+      });
+      rows.push(carriedRow(rule));
+    }
+  }
+  return rows;
+}
+function carriedRow(rule) {
+  const source = rule.subject === EVERYONE ? "everyone-default" : "user";
+  const value = rule.value;
+  return {
+    memberId: rule.to,
+    subjectId: rule.subject,
+    capability: "project:write",
+    before: { value, source, decidedScopeKind: "subsystem", decidedScopeId: rule.from.join(", ") },
+    after: { value, source, decidedScopeKind: "project", decidedScopeId: rule.to },
+    equal: true
+  };
+}
 function listChangedLinks(changes) {
   return changes.filter((c) => c.kind === "registered" || c.kind === "returned" || c.kind === "relocated").map((c) => ({ projectId: c.id, parentProjectId: String(c.detail.parent) }));
 }
@@ -52207,7 +52576,17 @@ function generateDiagram(cfg, credential, project2, format) {
   requireAdmin(credential);
   const root = existingProjectRoot(cfg.dataDir, project2);
   if (!root) throw new Error(`Unknown project "${project2}".`);
-  return runWithProjectRoot(root, () => renderDiagram(format));
+  const relations = format === "canvas" ? instanceRelations(cfg, project2, root) : void 0;
+  return runWithProjectRoot(root, () => renderDiagram(format, relations));
+}
+function instanceRelations(cfg, project2, root) {
+  const familyRoot = listFamilyRecords(cfg.dataDir, project2)[0];
+  const reach2 = {
+    topRoot: familyRoot?.rootPath || root,
+    parentReach: true,
+    hostedLookup: (id) => existingProjectRoot(cfg.dataDir, id)
+  };
+  return runWithProjectBinding(root, reach2, () => familyRelations2());
 }
 function downloadDiagram(cfg, credential, project2, format) {
   return generateDiagram(cfg, credential, project2, format);
@@ -52756,6 +53135,7 @@ function setAssignment2(cfg, credential, assignment) {
       "the instance-admin marker ('*'@instance) is reserved to the built-in admin account"
     );
   }
+  refuseUnfitSubsystemAssignment(assignment);
   requireAdminOverScope(
     cfg,
     principal,
@@ -52763,8 +53143,9 @@ function setAssignment2(cfg, credential, assignment) {
     assignment.scopeId ?? "",
     "setting an assignment requires project:admin over its scope"
   );
+  const { scopeNote: _label, ...unlabelled } = assignment;
   const stored = setAssignment(cfg.dataDir, {
-    ...assignment,
+    ...unlabelled,
     // Canonical grid key: user-kind subjects store the subject's userId, so
     // permission rules' primary match (not the legacy-alias path) serves them.
     ...assignment.subjectKind === "user" && assignment.subjectId ? { subjectId: canonicalSubjectId(cfg, assignment.subjectId) } : {},
@@ -52773,6 +53154,27 @@ function setAssignment2(cfg, credential, assignment) {
   tryAppendAudit(cfg, buildAuditEvent(principal, "permission.set", stored.id));
   return stored;
 }
+var SUBSYSTEM_VALUES = /* @__PURE__ */ new Set(["yes", "no", "inherit"]);
+function refuseUnfitSubsystemAssignment(assignment) {
+  if (assignment.scopeKind !== "subsystem") return;
+  const fits = String(assignment.capability) === "project:write" && SUBSYSTEM_VALUES.has(String(assignment.value)) && parseSubsystemScope(assignment.scopeId ?? "") !== null;
+  if (!fits) {
+    throw new ForbiddenError(
+      `a subsystem scope carries only project:write, yes or no (or inherit), at <projectId>/<subsystemId> \u2014 got ${assignment.capability}=${assignment.value} at "${assignment.scopeId ?? ""}"`
+    );
+  }
+}
+function refuseUnfitSubsystemBinding(scopeKind, scopeId) {
+  if (scopeKind === "subsystem" && parseSubsystemScope(scopeId ?? "") === null) {
+    throw new ForbiddenError(`a subsystem scope id is <projectId>/<subsystemId> \u2014 got "${scopeId ?? ""}"`);
+  }
+}
+function subsystemMissing(cfg, scopeId, cache2) {
+  const parsed = parseSubsystemScope(scopeId);
+  if (!parsed) return true;
+  if (!cache2.has(parsed.projectId)) cache2.set(parsed.projectId, declaredSubsystemIds(cfg.dataDir, parsed.projectId));
+  return !(cache2.get(parsed.projectId) ?? []).includes(parsed.subsystemId);
+}
 function removeAssignment2(cfg, credential, assignmentId) {
   const principal = requirePrincipal3(cfg, credential);
   const existing = getAssignment(cfg.dataDir, assignmentId);
@@ -52801,13 +53203,15 @@ function listAssignments2(cfg, credential, scopeKind, scopeId, subjectKind, subj
   const subjectIds = subjectKind === "user" && subjectId ? [.../* @__PURE__ */ new Set([subjectId, canonicalSubjectId(cfg, subjectId)])] : void 0;
   const assignments = subjectIds ? subjectIds.flatMap((id) => listAssignments(cfg.dataDir, void 0, subjectKind, id)) : listAssignments(cfg.dataDir, void 0, subjectKind, subjectId);
   const seen = /* @__PURE__ */ new Set();
-  return assignments.filter((a) => {
+  const listed = assignments.filter((a) => {
     if (seen.has(a.id)) return false;
     seen.add(a.id);
     if (scopeKind !== void 0 && a.scopeKind !== scopeKind) return false;
     if (scopeId !== void 0 && (a.scopeId ?? "") !== scopeId) return false;
     return true;
   });
+  const trees = /* @__PURE__ */ new Map();
+  return listed.map((a) => a.scopeKind === "subsystem" && subsystemMissing(cfg, a.scopeId ?? "", trees) ? { ...a, scopeNote: SUBSYSTEM_NOT_FOUND } : a);
 }
 function bindingScope(scopeKind, scopeId) {
   return { kind: scopeKind ?? "instance", id: scopeId ?? "" };
@@ -52817,6 +53221,7 @@ function sameBinding(a, b) {
 }
 function bindRole(cfg, credential, userId, roleId, scopeKind, scopeId) {
   const principal = requirePrincipal3(cfg, credential);
+  refuseUnfitSubsystemBinding(scopeKind, scopeId);
   const scope = bindingScope(scopeKind, scopeId);
   requireAdminOverScope(cfg, principal, scope.kind, scope.id, "binding a role requires project:admin over the scope");
   const user = getUserById(cfg.dataDir, userId);
@@ -52852,6 +53257,27 @@ function unbindRole(cfg, credential, userId, roleId, scopeKind, scopeId) {
   tryAppendAudit(cfg, buildAuditEvent(principal, "role.unbind", `${userId}:${roleId}`));
   return stored;
 }
+function subjectOfUser(user) {
+  const subjectId = user.subject.userId || user.id;
+  const aliases = [user.id, user.subject.userId].filter((id) => !!id && id !== subjectId);
+  return {
+    subjectId,
+    ...aliases.length ? { aliasSubjectIds: [...new Set(aliases)] } : {},
+    roleBindings: user.roleBindings ?? [],
+    instanceAdmin: false
+  };
+}
+function explain3(cfg, credential, userId, capability, scopeKind, scopeId) {
+  const principal = requirePrincipal3(cfg, credential);
+  requireAdminOverScope(cfg, principal, scopeKind, scopeId, "explaining a permission requires project:admin over its scope");
+  const user = findUserByRecordOrSubjectId(cfg.dataDir, userId);
+  if (!user) throw new Error(`User "${userId}" not found.`);
+  const explained = explain2(cfg.dataDir, subjectOfUser(user), capability, scopeKind, scopeId);
+  if (scopeKind === "subsystem" && subsystemMissing(cfg, scopeId, /* @__PURE__ */ new Map())) {
+    return { ...explained, scopeNote: SUBSYSTEM_NOT_FOUND };
+  }
+  return explained;
+}
 
 // src/server/identity.ts
 var crypto19 = __toESM(require("crypto"));
@@ -56118,6 +56544,7 @@ function lockTargetOf(cfg, req) {
 function lifecycleAction(cfg, credential, projectId, opts) {
   const principal = requirePrincipal7(cfg, credential);
   const effective = authorize(cfg.dataDir, principal, PROJECT_WRITE_CAPABILITY4, "project", projectId);
+  if (effective.value !== "no") refuseDeniedSubsystems(cfg, principal, projectId);
   switch (effective.value) {
     case "yes": {
       const outcome = opts.execute(hostedApprover(principal.subject));
@@ -56149,6 +56576,13 @@ function lifecycleAction(cfg, credential, projectId, opts) {
     }
   }
 }
+function refuseDeniedSubsystems(cfg, principal, projectId) {
+  const denied = resolveFamilyReach(cfg.dataDir, principal, [projectId]).subsystems.filter((s) => s.projectId === projectId && s.permission.value === "no");
+  if (denied.length === 0) return;
+  throw new ForbiddenError(
+    "a lock signs the whole tree, and the caller may not change these subsystems: " + denied.map((s) => `${s.subsystemId} (decided by ${describeDecision(s.permission)})`).join(", ")
+  );
+}
 function getApprovalStatus(cfg, credential, requestId) {
   const principal = requirePrincipal7(cfg, credential);
   expirePendingApprovals(cfg.dataDir, (/* @__PURE__ */ new Date()).toISOString());
@@ -57431,6 +57865,9 @@ function bindRole2(cfg, sessionId, userId, roleId, scopeKind, scopeId) {
 function unbindRole2(cfg, sessionId, userId, roleId, scopeKind, scopeId) {
   return unbindRole(cfg, sessionId, userId, roleId, scopeKind, scopeId);
 }
+function explainPermission(cfg, sessionId, userId, capability, scopeKind, scopeId) {
+  return explain3(cfg, sessionId, userId, capability, scopeKind, scopeId);
+}
 
 // src/server/webproject.ts
 function listProjects2(cfg, sessionId) {
@@ -58137,7 +58574,9 @@ function getWebProjectCanvas(cfg, sessionId, projectId) {
   if (!root) {
     throw new ForbiddenError("project not authorized or unknown");
   }
-  return runWithProjectRoot(root, () => renderDiagram("canvas"));
+  const listed = listProjects2(cfg, sessionId);
+  const relations = runWithProjectBinding(root, readReach(cfg, projectId, root, listed), () => familyRelations2());
+  return runWithProjectRoot(root, () => renderDiagram("canvas", relations));
 }
 function getWebProjectCanvasModel(cfg, sessionId, projectId) {
   const principal = authenticateSession(cfg.dataDir, sessionId);
@@ -60323,6 +60762,9 @@ function adminUnbindRole(cfg, sessionId, userId, roleId, scopeKind, scopeId) {
 function adminListAssignments(cfg, sessionId, scopeKind, scopeId, subjectKind, subjectId) {
   return listAssignments3(cfg, sessionId, scopeKind, scopeId, subjectKind, subjectId);
 }
+function adminExplainPermission(cfg, sessionId, userId, capability, scopeKind, scopeId) {
+  return explainPermission(cfg, sessionId, userId, capability, scopeKind, scopeId ?? "");
+}
 function adminSetAssignment(cfg, sessionId, assignment) {
   return setAssignment3(cfg, sessionId, assignment);
 }
@@ -60824,6 +61266,10 @@ async function handleWebRequest(cfg, req, res, body, url, ctx) {
           )
         });
       }
+      if (req.method === "GET" && parts.length === 4 && parts[2] === "permissions" && parts[3] === "explain") {
+        const q2 = (name) => url.searchParams.get(name) ?? "";
+        return sendJson(res, 200, adminExplainPermission(cfg, sessionId, q2("userId"), q2("capability"), q2("scopeKind") || "instance", q2("scopeId") || void 0));
+      }
       if (req.method === "POST" && parts.length === 3 && parts[2] === "permissions") {
         return sendJson(res, 200, adminSetAssignment(cfg, sessionId, body));
       }
@@ -61209,6 +61655,23 @@ var WRITE_TOOL_PREFIXES = [
   "sdd_promote_",
   "sdd_demote_"
 ];
+var SUBSYSTEM_SCOPED_WRITE_TOOLS = /* @__PURE__ */ new Set([
+  "sdd_add_subsystem",
+  "sdd_add_component",
+  "sdd_add_type",
+  "sdd_define_interface",
+  "sdd_write_narrative",
+  "sdd_set_endpoints",
+  "sdd_set_public_interfaces",
+  "sdd_update_spec",
+  "sdd_delete_spec",
+  "sdd_rename_component",
+  "sdd_rename_method",
+  "sdd_move_methods"
+]);
+function isSubsystemScopedWrite(toolName) {
+  return SUBSYSTEM_SCOPED_WRITE_TOOLS.has(toolName);
+}
 var READ_TOOL_PREFIXES = ["sdd_get_", "sdd_validate_"];
 var READ_TOOL_NAMES = /* @__PURE__ */ new Set([
   "listAgents",
@@ -61244,18 +61707,22 @@ function mcpChangeChannels(body, projectId, response) {
   if (MUTATING_HOST_TOOLS.has(name)) return [`project:${projectId}`, "projects"];
   return [];
 }
-function dataPlanePermissionError(cfg, principal, projectId, body) {
+function dataPlanePermissionError(cfg, principal, projectId, body, reach2) {
   const msg = jsonRpcRequest(body);
   if (!msg || msg.method !== "tools/call") return void 0;
   const name = msg.params?.name;
   if (typeof name !== "string" || name.length === 0) return void 0;
   const needed = requiredDataPlaneCapability(name);
-  if (authorize(cfg.dataDir, principal, needed, "project", projectId).value === "yes") return void 0;
+  const decided = authorize(cfg.dataDir, principal, needed, "project", projectId);
+  if (decided.value === "yes") return void 0;
+  if (needed === "project:write" && isSubsystemScopedWrite(name) && reach2.subsystems.some((s) => s.projectId === projectId && s.permission.value === "yes")) {
+    return void 0;
+  }
   return {
     jsonrpc: "2.0",
     id: msg.id ?? null,
     result: {
-      content: [{ type: "text", text: `Forbidden \u2014 permission ${needed} required for ${name}` }],
+      content: [{ type: "text", text: `Forbidden \u2014 permission ${needed} required for ${name}, decided at ${describeDecision(decided)}` }],
       isError: true
     }
   };
@@ -61431,7 +61898,7 @@ async function handleMcpRequest(cfg, req, res, body, credential) {
       for (const ch of mcpChangeChannels(body, projectId, dispatchedResponse)) publishChange(ch);
       return;
     }
-    const permissionError = dataPlanePermissionError(cfg, principal, projectId, body);
+    const permissionError = dataPlanePermissionError(cfg, principal, projectId, body, reach2.family);
     if (permissionError !== void 0) {
       sendJson(res, 200, permissionError);
       auditToolCall(cfg.dataDir, principal, binding, body, deriveMcpOutcome(permissionError));
@@ -61471,7 +61938,11 @@ async function handleMcpRequest(cfg, req, res, body, credential) {
     for (const ch of mcpChangeChannels(body, projectId, response)) publishChange(ch);
   });
 }
-var MEMBERSHIP_TOOLS = /* @__PURE__ */ new Set(["sdd_attach_member", "sdd_adopt_member", "sdd_detach_member", "sdd_rename_project", "sdd_promote_member", "sdd_demote_member", "sdd_add_member"]);
+var MEMBERSHIP_TOOLS = /* @__PURE__ */ new Set(["sdd_attach_member", "sdd_adopt_member", "sdd_detach_member", "sdd_rename_project", "sdd_promote_member", "sdd_demote_member", "sdd_add_member", "sdd_externalize_subsystem"]);
+function isMembershipCall(call) {
+  if (call.name === "sdd_externalize_subsystem") return call.args.as === "project";
+  return MEMBERSHIP_TOOLS.has(call.name);
+}
 var FAMILY_SHAPE_TOOLS = /* @__PURE__ */ new Set([
   "sdd_add_member",
   "sdd_move_member",
@@ -61493,7 +61964,7 @@ function reachLines(rows) {
 }
 function serveMembershipTool(cfg, principal, binding, body) {
   const call = toolCall(body);
-  if (!call || !MEMBERSHIP_TOOLS.has(call.name)) return {};
+  if (!call || !isMembershipCall(call)) return {};
   const apply4 = call.args.dryRun !== true;
   const answer = (result) => ({ response: { jsonrpc: "2.0", id: call.id, result } });
   try {
@@ -61503,9 +61974,10 @@ function serveMembershipTool(cfg, principal, binding, body) {
       case "sdd_adopt_member":
         return answer(relocationResult("adopt", adopt(cfg.dataDir, principal, binding, String(call.args.alias ?? ""), String(call.args.path ?? ""), apply4), apply4));
       default: {
-        const named2 = call.name === "sdd_rename_project" ? String(call.args.project ?? "") : String(call.args.alias ?? "");
+        const named2 = call.name === "sdd_rename_project" ? String(call.args.project ?? "") : call.name === "sdd_externalize_subsystem" ? String(call.args.subsystem ?? "") : String(call.args.alias ?? "");
         const located = typeof call.args.source === "string" ? call.args.source : typeof call.args.path === "string" ? call.args.path : void 0;
-        const screened = screen(cfg.dataDir, binding, call.name, named2, located);
+        const newId = call.name === "sdd_promote_member" && typeof call.args.id === "string" && call.args.id ? call.args.id : void 0;
+        const screened = screen(cfg.dataDir, binding, call.name, named2, located, newId);
         if (screened.refusal !== void 0) return answer({ content: [{ type: "text", text: screened.refusal }], isError: true });
         return { screen: screened };
       }
@@ -61549,6 +62021,10 @@ function withReachListing(result, screened, body) {
   const lines = reachLines(screened.reachChanges);
   r.content.push({ type: "text", text: lines.length > 0 ? `Reach changes \u2014 who gains access through the new parent:
 ${lines.join("\n")}` : "Reach changes: none \u2014 nobody gains or loses access." });
+  if (!screened.carried) return;
+  const carried = screened.carried.map((c) => `${c.from.join(", ")} -> project ${c.to}: ${c.subject} ` + (c.kind === "role" ? `role ${c.value} \u2014 ${c.note}` : `project:write ${c.value} (${c.note})`));
+  r.content.push({ type: "text", text: carried.length > 0 ? `Subsystem rules carried onto the new project:
+${carried.join("\n")}` : "Subsystem rules carried onto the new project: none." });
 }
 function reconcileAfter(cfg, principal, binding, body, response) {
   const call = toolCall(body);
@@ -61591,7 +62067,14 @@ function familyReachOf(cfg, principal, binding) {
   const topRoot = existingProjectRoot(cfg.dataDir, binding.familyRootId) ?? binding.rootPath;
   const parentReach = reach2.readable.includes(binding.familyRootId) && covered(binding.familyRootId);
   const unwritableRoots = family.filter((r) => r.rootPath && !isRetiredPart(r) && !(reach2.writable.includes(r.id) && covered(r.id))).map((r) => r.rootPath);
-  return { topRoot, parentReach, unwritableRoots, hostedLookup: hostedRecordLookup(cfg, principal) };
+  const roots = new Map(family.filter((r) => r.rootPath && !isRetiredPart(r)).map((r) => [r.id, r.rootPath]));
+  const subsystems = reach2.subsystems.flatMap((s) => {
+    const root = roots.get(s.projectId);
+    if (!root) return [];
+    return [{ root, subsystemId: s.subsystemId, writable: s.permission.value === "yes" && covered(s.projectId), decidedBy: describeDecision(s.permission) }];
+  });
+  const writeReach = { unwritableRoots, subsystems };
+  return { topRoot, parentReach, unwritableRoots, hostedLookup: hostedRecordLookup(cfg, principal), writeReach, family: reach2 };
 }
 function hostedRecordLookup(cfg, principal) {
   return (recordId) => {
@@ -63133,6 +63616,10 @@ function printMemberUpgrade(upgrade, fix) {
 var CAPABILITIES = ["project:read", "project:create", "project:write", "project:admin", "approval:decide", "share:create"];
 var PERMISSION_VALUES = ["yes", "approval", "no", "inherit"];
 function resolveScopeOptions(options) {
+  if (options.subsystem) {
+    if (!options.project) throw new WaironError("`--subsystem <id>` needs `--project <id>`: a subsystem scope is `<project>/<subsystem>`.");
+    return { kind: "subsystem", id: `${options.project}/${options.subsystem}` };
+  }
   if (options.project) return { kind: "project", id: options.project };
   if (options.unit) return { kind: "unit", id: options.unit };
   return { kind: "instance" };
@@ -63172,7 +63659,7 @@ async function runHostPermission(action, options = {}) {
         const list2 = listAssignments2(
           cfg,
           cred,
-          options.project || options.unit || options.instance ? scope.kind : void 0,
+          options.project || options.unit || options.instance || options.subsystem ? scope.kind : void 0,
           scope.id,
           options.user ? "user" : void 0,
           options.user
@@ -63182,7 +63669,7 @@ async function runHostPermission(action, options = {}) {
         } else {
           for (const a of list2) {
             const subject = a.subjectKind === "everyone" ? "everyone" : a.subjectId;
-            logger.info(`  ${a.id}  ${String(subject).padEnd(20)} ${a.capability.padEnd(16)} ${a.value.padEnd(9)} ${a.scopeKind}${a.scopeId ? ` ${a.scopeId}` : ""}`);
+            logger.info(`  ${a.id}  ${String(subject).padEnd(20)} ${a.capability.padEnd(16)} ${a.value.padEnd(9)} ${a.scopeKind}${a.scopeId ? ` ${a.scopeId}` : ""}${a.scopeNote ? `  (${a.scopeNote})` : ""}`);
           }
         }
         break;
@@ -64720,12 +65207,13 @@ hostCmd.command("unit <action>").description("create an organization unit (proje
 hostCmd.command("doctor").description("migrate a hosted data dir to the permission model (grants \u2192 assignments, owners, unit ids, placements); dry-run without --fix").option("--fix", "apply the migration (REQUIRED at rollout \u2014 legacy users/tokens otherwise resolve to zero permissions)").option("--data-dir <path>", "data root").action(async (opts) => {
   await runHostDoctor({ fix: opts.fix, dataDir: opts.dataDir });
 });
-hostCmd.command("permission <action>").description("set | list | remove a permission assignment (the subject\xD7scope\xD7capability grid)").option("--user <userId>", "the subject user id (for set; optional filter for list)").option("--capability <capability>", "project:read | project:create | project:write | project:admin | approval:decide").option("--value <value>", "yes | approval | no | inherit", "yes").option("--project <id>", "anchor the assignment at a project scope").option("--unit <unitId>", "anchor the assignment at an organization-unit scope").option("--instance", "anchor the assignment at the instance scope (the default)").option("--id <assignmentId>", "assignment id (for remove)").option("--data-dir <path>", "data root").action(async (action, opts) => {
+hostCmd.command("permission <action>").description("set | list | remove a permission assignment (the subject\xD7scope\xD7capability grid)").option("--user <userId>", "the subject user id (for set; optional filter for list)").option("--capability <capability>", "project:read | project:create | project:write | project:admin | approval:decide").option("--value <value>", "yes | approval | no | inherit", "yes").option("--project <id>", "anchor the assignment at a project scope").option("--subsystem <id>", "with --project: anchor at a subsystem of that project (project:write only, yes | no | inherit)").option("--unit <unitId>", "anchor the assignment at an organization-unit scope").option("--instance", "anchor the assignment at the instance scope (the default)").option("--id <assignmentId>", "assignment id (for remove)").option("--data-dir <path>", "data root").action(async (action, opts) => {
   await runHostPermission(action, {
     user: opts.user,
     capability: opts.capability,
     value: opts.value,
     project: opts.project,
+    subsystem: opts.subsystem,
     unit: opts.unit,
     instance: opts.instance,
     id: opts.id,