@wairon/cli 5.1.1-dev.91 → 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.91";
+    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();
   }
 });
@@ -3229,6 +3245,12 @@ function typeSourceFiles(type) {
   for (const method2 of type.methods ?? []) add2(method2.sourcePath);
   return files;
 }
+function relationHealth(status2) {
+  if (status2.uses.some((u) => u.state === "changed" || u.state === "removed")) return "incompatible";
+  if (!status2.reachable || status2.outOfReach || status2.uses.some((u) => u.state === "unavailable" || u.state === "unlocked")) return "unavailable";
+  if (status2.drifted) return "drifted";
+  return "ok";
+}
 var import_zod8, SpecIdSchema, SpecStatusSchema, BoundaryItemSchema, RequirementItemSchema, DatabaseSpecSchema, DiagramConfigSchema, SURFACE_AUDIENCES, SurfaceAudienceSchema, SystemPublicInterfaceSchema, SystemSpecSchema, PublicInterfaceTypeSchema, PublicInterfaceSchema, TrustedLinkSchema, LintAllowSchema, LintConfigSchema, ExtDataSchema, LifecycleEntrypointSchema, SubsystemSpecSchema, ComponentTypeSchema, PATTERN_TYPES, RETIRED_STEREOTYPES, PortalTypeSchema, DispatchBindingSchema, DurabilitySchema, DependencyClassSchema, PatternRefSchema, EventBindingSchema, ExternalLinkTypeSchema, ExternalLinkSchema, PortalAuthSchemeSchema, PortalAuthSchema, PortalMountSchema, ComponentSpecSchema, BLOCK_NOUNS, HttpMethodSchema, TransportSchema, EndpointSchema, SEMANTIC_GUARANTEES, GuaranteeSchema, MethodParamSchema, FindingDeclarationSchema, MethodSignatureSchema, INTENT_FLOOR_MIN_CHARS, InterfaceSpecSchema, NarrativeStepTypeSchema, LoopKindSchema, SwitchCaseSchema, CatchClauseSchema, ParallelBranchSchema, NarrativeStepSchema, NarrativeDetailSchema, ConformanceTierSchema, MethodImplementationSchema, TechnologySchema, ImplementationSpecSchema, TypeKindSchema, TypeFieldSchema, TypeMethodSchema, InvariantSchema, TypeSpecSchema, SurfaceOriginSchema, SurfaceTypeDefSchema, SurfaceTypeExportSchema, SurfaceContractEntrySchema, SurfaceSnapshotSchema, ExternalLockEntrySchema, ExternalsLockSchema, ParentExcerptSchema, NamedOpenApiSpecSchema, GroupSpecSchema;
 var init_specs = __esm({
   "src/models/specs.ts"() {
@@ -5585,12 +5607,16 @@ function memberProjectNodes() {
     trustedLinks: [],
     project: true
   }));
-  const referenced = (family.nodes.find((n) => n.namespace === "")?.externals ?? []).filter((e) => e.role === "member").map((e) => ({ id: e.alias, name: e.alias, description: "", trustedLinks: [], project: true, storage: storageBadge(e.sourceKind === "family" ? "contained" : e.sourceKind, e.directory, e.commit) }));
-  return [...contained, ...referenced];
+  const rootExternals = family.nodes.find((n) => n.namespace === "")?.externals ?? [];
+  const referenced = rootExternals.filter((e) => e.role === "member").map((e) => ({ id: e.alias, name: e.alias, description: "", trustedLinks: [], project: true, storage: storageBadge(e.sourceKind === "family" ? "contained" : e.sourceKind, e.directory, e.commit) }));
+  const taken = new Set([...contained, ...referenced].map((n) => n.id));
+  const external = rootExternals.filter((e) => e.role !== "member" && e.sourceKind !== "family" && !taken.has(e.alias)).map((e) => ({ id: e.alias, name: e.alias, description: e.project === e.alias ? "" : `project ${e.project}`, trustedLinks: [], project: true, external: true, storage: storageBadge(e.sourceKind, e.directory, e.commit) }));
+  return [...contained, ...referenced, ...external];
 }
 function storageBadge(storage, directory, commit3) {
   if (storage === "git") return `git ${commit3 ? commit3.slice(0, 7) : ""}`.trim();
   if (storage === "hosted") return "hosted";
+  if (storage === "unresolved") return "unresolved";
   if (storage === "path") return directory ? `../${directory.split(/[\\/]/).pop()}` : "sibling";
   return "contained";
 }
@@ -5602,7 +5628,60 @@ function partBadges() {
   }
   return out;
 }
-function buildCanvasModel(issues = []) {
+function useLabel(use) {
+  if (use.publicName === void 0) return use.member ?? "(the external)";
+  return use.member === void 0 || use.member === "type" ? use.publicName : `${use.publicName}.${use.member}`;
+}
+function relationFrom(id, consumer, producer, status2, comparedAt) {
+  const changed = status2.uses.filter((u) => u.state !== "unchanged");
+  const health = relationHealth(status2);
+  return {
+    id,
+    consumer,
+    producer,
+    health,
+    uses: changed.map((u) => ({ name: useLabel(u), state: u.state, ...u.detail !== void 0 ? { detail: u.detail } : {} })),
+    unchanged: status2.uses.length - changed.length,
+    ...status2.pinnedCommit !== void 0 ? { pinnedCommit: status2.pinnedCommit } : {},
+    ...status2.pinnedDigest !== void 0 ? { pinnedDigest: status2.pinnedDigest } : {},
+    comparedAt,
+    ...health === "unavailable" && status2.detail !== void 0 ? { detail: status2.detail } : {}
+  };
+}
+function statusFor(entry, consumer, producer) {
+  const { alias, node } = producer;
+  return entry.externals.find((s) => alias !== void 0 && s.alias === alias || node !== void 0 && (node.parent === consumer && s.alias === node.mountAlias || s.sourceKind === "family" && node.id !== void 0 && s.project === node.id));
+}
+function nameRelations(edges, relations, outsideIds, ownerOf4) {
+  const family = graph();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const out = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    if (!edge.consumption) continue;
+    const consumer = ownerOf4(edge.from);
+    const node = outsideIds.has(edge.to) ? void 0 : familyNode(family, ownerOf4(edge.to)) ?? void 0;
+    const alias = outsideIds.has(edge.to) ? edge.to : void 0;
+    const entry = relations.find((r) => r.project === consumer);
+    const status2 = entry && !entry.detail ? statusFor(entry, consumer, { alias, node }) : void 0;
+    const producer = status2?.alias ?? alias ?? (node?.parent === consumer ? node.mountAlias : void 0) ?? node?.id ?? ownerOf4(edge.to);
+    const id = `${consumer}\u2192${producer}`;
+    if (!out.has(id)) {
+      out.set(id, status2 ? relationFrom(id, consumer, producer, status2, entry.comparedAt) : {
+        id,
+        consumer,
+        producer,
+        health: "unavailable",
+        uses: [],
+        unchanged: 0,
+        comparedAt: entry?.comparedAt ?? now,
+        detail: entry?.detail ?? (entry ? `the consumer's statuses name no producer "${producer}"` : "the consumer's statuses were not read")
+      });
+    }
+    edge.relation = id;
+  }
+  return [...out.values()];
+}
+function buildCanvasModel(issues = [], relations) {
   const system = loadSystemSpec();
   const subsystems = loadSubsystemSpecs();
   const components = loadComponentSpecs();
@@ -5710,22 +5789,26 @@ function buildCanvasModel(issues = []) {
   const badges = partBadges();
   const componentSub = new Map(components.map((c) => [c.id, c.subsystem]));
   const edges = [];
-  const referencedIds = new Set(projectNodes.filter((p) => p.storage !== void 0).map((p) => p.id));
+  const outsideIds = new Set(projectNodes.filter((p) => p.storage !== void 0).map((p) => p.id));
+  const owners = graph().owners;
+  const ownerOfSpec = (id) => owners.get(id) ?? "";
   for (const comp of components) {
     for (const depId of comp.dependsOn) {
       const alias = depId.includes("::") ? depId.split("::")[0] : "";
-      if (referencedIds.has(alias) && !componentIds.has(depId)) {
-        edges.push({ from: comp.id, to: alias, cross: true });
+      if (outsideIds.has(alias) && !componentIds.has(depId)) {
+        edges.push({ from: comp.id, to: alias, cross: true, consumption: true });
         continue;
       }
       if (!componentIds.has(depId)) continue;
       edges.push({
         from: comp.id,
         to: depId,
-        cross: componentSub.get(depId) !== comp.subsystem
+        cross: componentSub.get(depId) !== comp.subsystem,
+        ...ownerOfSpec(depId) !== ownerOfSpec(comp.id) ? { consumption: true } : {}
       });
     }
   }
+  const canvasRelations2 = relations === void 0 ? void 0 : nameRelations(edges, relations, outsideIds, ownerOfSpec);
   const typeSpecs = loadTypeSpecs();
   const usedByFor = (t) => {
     const qualified = t.subsystem && !t.id.startsWith(`${t.subsystem}::`) ? `${t.subsystem}::${t.id}` : t.id;
@@ -5847,6 +5930,7 @@ function buildCanvasModel(issues = []) {
     ],
     components: modelComponents,
     edges,
+    ...canvasRelations2 !== void 0 ? { relations: canvasRelations2 } : {},
     types: modelTypes,
     typeEdges,
     dataEdges,
@@ -6029,6 +6113,7 @@ body[data-theme="light"] .selectControl { color-scheme:light; }
 #cy { position:absolute; inset:0; }
 .legend { position:absolute; left:12px; bottom:12px; background:var(--chrome); border:1px solid var(--chrome-border); border-radius:10px; padding:8px 12px; font-size:11px; color:var(--dim); z-index:5; pointer-events:none; }
 .legend .sw { display:inline-block; width:10px; height:10px; border-radius:3px; margin-right:4px; vertical-align:-1px; border:1.5px solid; }
+.reltip { position:absolute; display:none; background:var(--chrome); border:1px solid var(--chrome-border); border-radius:8px; padding:6px 10px; font-size:11px; color:var(--dim); white-space:pre; z-index:6; pointer-events:none; max-width:520px; overflow:hidden; }
 /* Stage overlays clear the floating header (52px + 10px top + 10px gap). The
    header hides in presentation mode, where they return to the top edge. */
 .viewhint { position:absolute; top:72px; left:12px; color:var(--dim); font-size:11px; background:var(--chrome); border:1px solid var(--chrome-border); border-radius:9px; padding:5px 10px; z-index:5; pointer-events:none; }
@@ -6214,6 +6299,7 @@ body.presentation #exitPresent, body.presentation #presentDetails { display:bloc
     <div class="viewhint" id="viewHint"></div>
     <div id="typesWarn"></div>
     <div class="legend" id="legend"></div>
+    <div class="reltip" id="relTip"></div>
   </div>
   <div id="panelResizer" title="Drag to resize details sidebar"></div>
   <div id="panel"></div>
@@ -6541,6 +6627,7 @@ var MODEL = __MODEL_JSON__;
         retired: { fill: '#ebe8e4', stroke: '#857b73', text: '#35302b' },
       },
       issue: '#b3261e', selGlow: '#3465b4', bgLabel: '#f2f5f8', png: '#f2f5f8',
+      relOk: '#2e7d4f', relDrift: '#8a6116', relBad: '#b3261e', relUnknown: '#5f6b78',
     },
     syw: {
       pageEdge: '#7c8ca3', edgeText: '#aebdd2', cross: '#ff6b81', ink: '#eef2f8',
@@ -6562,6 +6649,7 @@ var MODEL = __MODEL_JSON__;
         retired: { fill: '#24211f', stroke: '#a8a29e', text: '#e7e5e4' },
       },
       issue: '#ff6b81', selGlow: '#22ddff', bgLabel: '#0a0a0f', png: '#0a0a0f',
+      relOk: '#34d399', relDrift: '#f59e0b', relBad: '#ff6b81', relUnknown: '#93a1b8',
     },
   };
 
@@ -6624,6 +6712,15 @@ var MODEL = __MODEL_JSON__;
       { selector: 'edge.bundle', style: { width: 4.5, opacity: 0.7 } },
       { selector: 'edge.toghost', style: { 'line-style': 'dashed', opacity: 0.75 } },
       { selector: 'edge.inneredge', style: { width: 1.1, 'arrow-scale': 0.6, opacity: 0.8 } },
+      // Relation health on consumption edges: the health colour replaces the
+      // boundary-hop colour, and unavailable is dotted as well as grey, so the
+      // state never rests on colour alone (the glyph is the edge's label).
+      { selector: 'edge.rel-unchecked', style: { 'line-color': t.pageEdge, 'target-arrow-color': t.pageEdge } },
+      { selector: 'edge.rel-ok', style: { 'line-color': t.relOk, 'target-arrow-color': t.relOk } },
+      { selector: 'edge.rel-drifted', style: { 'line-color': t.relDrift, 'target-arrow-color': t.relDrift } },
+      { selector: 'edge.rel-incompatible', style: { 'line-color': t.relBad, 'target-arrow-color': t.relBad } },
+      { selector: 'edge.rel-unavailable', style: { 'line-color': t.relUnknown, 'target-arrow-color': t.relUnknown, 'line-style': 'dotted' } },
+      { selector: '.extProject', style: { 'border-style': 'dashed' } },
       { selector: 'edge.stubHover', style: { 'line-color': t.selGlow, 'target-arrow-color': t.selGlow, width: 2.6, opacity: 1, 'z-compound-depth': 'top' } },
       { selector: '.dimmed', style: { opacity: 0.13 } },
       { selector: '.hasIssue', style: { 'border-color': t.issue, 'border-style': 'dashed', 'border-width': 3 } },
@@ -6660,6 +6757,83 @@ var MODEL = __MODEL_JSON__;
     ];
   }
 
+  // ---- relation health (consumption edges) ----------------------------------
+  // The model carries relations only when health was computed; without them a
+  // consumption edge is drawn neutral and the legend says it was not checked \u2014
+  // never green for something nobody compared.
+  var HAS_RELATIONS = Array.isArray(MODEL.relations);
+  var REL_BY_ID = {};
+  (MODEL.relations || []).forEach(function (r) { REL_BY_ID[r.id] = r; });
+  var HEALTH_RANK = { ok: 1, drifted: 2, unavailable: 3, incompatible: 4 };
+  var HEALTH_GLYPH = { ok: '\\u2713', drifted: '\\u0394', incompatible: '\\u2715', unavailable: '?' };
+  var HAS_CONSUMPTION = MODEL.edges.some(function (e) { return !!e.consumption; });
+  function edgeHealth(edge) {
+    var r = edge.relation ? REL_BY_ID[edge.relation] : null;
+    return r ? r.health : (HAS_RELATIONS ? 'unavailable' : null);
+  }
+  // Where edges fold into one, the worst health wins.
+  function worseHealth(a, b) {
+    if (!a) return b;
+    if (!b) return a;
+    return HEALTH_RANK[b] > HEALTH_RANK[a] ? b : a;
+  }
+  function relationsComparedAt() {
+    var at = null;
+    (MODEL.relations || []).forEach(function (r) { if (!at || r.comparedAt < at) at = r.comparedAt; });
+    return at;
+  }
+  function shortPin(r) {
+    if (r.pinnedCommit) return r.pinnedCommit.slice(0, 7);
+    return r.pinnedDigest ? r.pinnedDigest.replace(/^[a-z0-9-]+:/, '').slice(0, 12) : '';
+  }
+  function relationName(r) { return (r.consumer || 'this project') + ' \\u2192 ' + r.producer; }
+  function relationText(r) {
+    var lines = [relationName(r) + ': ' + HEALTH_GLYPH[r.health] + ' ' + r.health];
+    r.uses.forEach(function (u) { lines.push('  ' + u.name + ' \\u2014 ' + u.state + (u.detail ? ': ' + u.detail : '')); });
+    if (r.unchanged) lines.push('  ' + r.unchanged + ' use' + (r.unchanged === 1 ? '' : 's') + ' unchanged');
+    if (r.detail) lines.push('  ' + r.detail);
+    var pin = shortPin(r);
+    lines.push((pin ? 'pinned ' + pin + ' \\u00B7 ' : '') + 'compared ' + r.comparedAt);
+    return lines.join('\\n');
+  }
+  function relationHtml(r) {
+    var pin = shortPin(r);
+    return '<div class="method"><div class="mname">' + esc(relationName(r)) + '<span class="grow"></span><span class="chip">' + HEALTH_GLYPH[r.health] + ' ' + esc(r.health) + '</span></div>'
+      + r.uses.map(function (u) { return '<div class="mdesc">' + esc(u.name) + ' \\u2014 ' + esc(u.state) + (u.detail ? ': ' + esc(u.detail) : '') + '</div>'; }).join('')
+      + (r.unchanged ? '<div class="mdesc">' + r.unchanged + ' use' + (r.unchanged === 1 ? '' : 's') + ' unchanged</div>' : '')
+      + (r.detail ? '<div class="mdesc">' + esc(r.detail) + '</div>' : '')
+      + '<div class="mdesc">' + (pin ? 'pinned ' + esc(pin) + ' \\u00B7 ' : '') + 'compared ' + esc(r.comparedAt) + '</div></div>';
+  }
+  // The relations whose consumption edges start or land inside a node.
+  function relationsTouching(sid) {
+    var seen = {}, out = [];
+    var inside = function (x) {
+      var c = compById[x];
+      return x === sid || x.indexOf(sid + '::') === 0 || !!(c && (c.subsystem === sid || c.subsystem.indexOf(sid + '::') === 0));
+    };
+    MODEL.edges.forEach(function (e) {
+      if (!e.relation || seen[e.relation] || !(inside(e.to) || inside(e.from))) return;
+      seen[e.relation] = true;
+      if (REL_BY_ID[e.relation]) out.push(REL_BY_ID[e.relation]);
+    });
+    return out;
+  }
+  // The one legend row, only when the model has a consumption edge.
+  function relationLegend(t) {
+    if (!HAS_CONSUMPTION) return '';
+    if (!HAS_RELATIONS) return '<br>relations: <span style="color:' + t.pageEdge + '">health not checked</span>';
+    var at = relationsComparedAt();
+    return '<br>relations: <span style="color:' + t.relOk + '">\\u2713 ok</span>&nbsp; <span style="color:' + t.relDrift + '">\\u0394 drifted</span>&nbsp; '
+      + '<span style="color:' + t.relBad + '">\\u2715 incompatible</span>&nbsp; <span style="color:' + t.relUnknown + '">? unavailable (dotted)</span>'
+      + (at ? '&nbsp; \\u00B7 as of ' + esc(at) : '');
+  }
+  // A project's own page, only through the host's open-project hook (the web
+  // app): never in a standalone file or on a shared page, which have none.
+  function openProjectButton(s) {
+    if (!s.recordId || typeof opts === 'undefined' || !opts || typeof opts.onOpenProject !== 'function') return '';
+    return '<div class="openbtn"><button class="tbtn" data-openproject-id="' + esc(s.recordId) + '">Open project \\u2197</button></div>';
+  }
+
   function renderLegend() {
     var t = THEMES[state.theme];
     var sw = function (c) { return '<span class="sw" style="background:' + c.fill + ';border-color:' + c.stroke + '"></span>'; };
@@ -6673,7 +6847,8 @@ var MODEL = __MODEL_JSON__;
       sw(t.proxyIn) + '\\u21E0 in-port&nbsp; ' + sw(t.proxyOut) + '\\u21E2 out-port&nbsp; \u2014 bold border = published \xB7 ' +
       '<span style="color:' + t.cross + '">red</span> = boundary hop \xB7 double-click = open<br>' +
       'on select: <span style="color:' + t.selGlow + '">\\u2192 depends on</span>&nbsp; <span style="color:' + t.warn + '">\\u2190 used by</span>' +
-      (state.dataCoupling ? '&nbsp; \xB7 &nbsp;<span style="color:' + t.typeV.stroke + '">- - \\u25B8 uses models</span>' : '');
+      (state.dataCoupling ? '&nbsp; \xB7 &nbsp;<span style="color:' + t.typeV.stroke + '">- - \\u25B8 uses models</span>' : '') +
+      relationLegend(t);
   }
 
   // ---- view layout ---------------------------------------------------------------
@@ -7140,6 +7315,14 @@ var MODEL = __MODEL_JSON__;
       if (!agg[key]) agg[key] = { src: src, tgt: tgt, n: 0, cross: false, ghost: ghost };
       agg[key].n++;
       if (edge.cross) agg[key].cross = true;
+      if (edge.consumption) {
+        agg[key].consumption = true;
+        agg[key].health = worseHealth(agg[key].health, edgeHealth(edge));
+        if (edge.relation) {
+          var rels = agg[key].rels || (agg[key].rels = []);
+          if (rels.indexOf(edge.relation) < 0) rels.push(edge.relation);
+        }
+      }
     });
     return { agg: agg, ghosts: ghosts };
   }
@@ -7700,7 +7883,7 @@ var MODEL = __MODEL_JSON__;
       var classes, label;
       var isPub = e.kind === 'component' && compById[e.id] && compById[e.id].public;
       if (e.kind === 'subsystem') {
-        classes = 'subsysBox';
+        classes = 'subsysBox' + (subById[e.id] && subById[e.id].external ? ' extProject' : '');
         label = nameOf(e) + (e.hasKids && !inner ? '\\n\\u25B8 open' : '');
       } else {
         var c = compById[e.id];
@@ -7908,9 +8091,13 @@ var MODEL = __MODEL_JSON__;
       var bundle = e.n > 1;
       var dim = state.query && (dimmedAnchors[e.src] || dimmedAnchors[e.tgt]);
       var route = routeData(e.src, e.tgt, key);
+      // A consumption edge carries its relation's health: the glyph at its middle,
+      // its colour (and line, dotted when unavailable) by class.
+      var glyph = e.health ? HEALTH_GLYPH[e.health] : '';
+      var relCls = e.consumption ? 'rel rel-' + (e.health || 'unchecked') + ' ' : '';
       eles.push({
-        data: { id: 'e' + (i++), source: e.src, target: e.tgt, lbl: bundle ? e.n + ' links' : '', cpDist: route.cpDist, cpWeight: route.cpWeight, taxiTurn: route.taxiTurn },
-        classes: 'routed ' + (e.cross ? 'cross ' : '') + (bundle ? 'bundle ' : '') + (e.ghost ? 'toghost ' : '') + (dim ? 'dimmed' : ''),
+        data: { id: 'e' + (i++), source: e.src, target: e.tgt, lbl: (bundle ? e.n + ' links' : '') + (glyph ? (bundle ? ' ' : '') + glyph : ''), rels: (e.rels || []).join('|'), cpDist: route.cpDist, cpWeight: route.cpWeight, taxiTurn: route.taxiTurn },
+        classes: 'routed ' + (e.cross ? 'cross ' : '') + (bundle ? 'bundle ' : '') + (e.ghost ? 'toghost ' : '') + relCls + (dim ? 'dimmed' : ''),
       });
     });
 
@@ -8410,6 +8597,27 @@ var MODEL = __MODEL_JSON__;
   cy.on('mouseover', 'node', function (ev) { setHover(ev.target); });
   cy.on('mouseout', 'node', function (ev) { if (hoveredNode && hoveredNode.id() === ev.target.id()) setHover(null); });
 
+  // Relation health: hovering a consumption edge shows its relation(s) \u2014 which
+  // uses changed or were removed, why one could not be compared, the pin and
+  // when it was compared; tapping it shows the same in the details panel.
+  function relationsOfEdge(edge) {
+    return (edge.data('rels') || '').split('|').filter(Boolean).map(function (rid) { return REL_BY_ID[rid]; }).filter(Boolean);
+  }
+  cy.on('mouseover', 'edge.rel', function (ev) {
+    var tip = document.getElementById('relTip');
+    var rels = relationsOfEdge(ev.target);
+    tip.textContent = rels.length ? rels.map(relationText).join('\\n\\n') : 'relation health not checked';
+    var at = ev.renderedPosition || { x: 0, y: 0 };
+    tip.style.left = (at.x + 12) + 'px';
+    tip.style.top = (at.y + 12) + 'px';
+    tip.style.display = 'block';
+  });
+  cy.on('mouseout', 'edge.rel', function () { document.getElementById('relTip').style.display = 'none'; });
+  cy.on('tap', 'edge.rel', function (ev) {
+    var ids = ev.target.data('rels') || '';
+    if (ids) select('relation', ids, false);
+  });
+
   cy.on('tap', 'node', function (ev) {
     var t = idOf(ev.target);
     if (t.group) return;
@@ -8467,7 +8675,15 @@ var MODEL = __MODEL_JSON__;
     var hasKids = t.kind === 'subsystem'
       ? (childSubsOf(t.id).length + childCompsOf(t.id).length) > 0
       : memberCompsOf(t.id).length > 0;
-    if (hasKids) navigateTo(t.kind, t.id);
+    if (hasKids) { navigateTo(t.kind, t.id); return; }
+    // A project node with nothing to drill into (a referenced or external one):
+    // its own page through the host's open-project hook when it carries a
+    // record id, else its details panel \u2014 its storage and its relations.
+    var ps = t.kind === 'subsystem' ? subById[t.id] : null;
+    if (ps && ps.project) {
+      if (ps.recordId && typeof opts !== 'undefined' && opts && typeof opts.onOpenProject === 'function') { opts.onOpenProject(ps.recordId); return; }
+      select('subsystem', t.id, false);
+    }
   });
   cy.on('dragfree', 'node', function () { harvestPositions(); });
 
@@ -9704,7 +9920,7 @@ var MODEL = __MODEL_JSON__;
     cy.nodes().removeClass('sel');
     cy.edges().removeClass('fieldhl');
     if (id) {
-      var node = nodeForRef(kind, id);
+      var node = kind === 'relation' ? cy.collection() : nodeForRef(kind, id);
       if (node.length) {
         node.addClass('sel');
         applyFocus(node);
@@ -9874,6 +10090,10 @@ var MODEL = __MODEL_JSON__;
             via.map(function (v) { return chip(v.label, v.kind, v.id); }).join(''), true);
         }
       }
+    } else if (focusKind === 'relation') {
+      var rl = String(focusId).split('|').map(function (rid) { return REL_BY_ID[rid]; }).filter(Boolean);
+      head = '<h2>' + esc(rl.length === 1 ? relationName(rl[0]) : rl.length + ' relations') + '</h2>' + staticChip('relation');
+      body += rl.map(relationHtml).join('');
     } else if (focusKind === 'type') {
       var ty = null;
       MODEL.types.forEach(function (t2) { if (t2.id === focusId) ty = t2; });
@@ -9957,8 +10177,14 @@ var MODEL = __MODEL_JSON__;
         + (scopeFocus ? staticChip('current view') : '')
         + (scopeFocus ? '' : openViewButton('subsystem', s.id, subKids > 0))
         + openApiButton(subsystemExposesApi(s.id), '')
-        + openSpecButton('subsystem', s.id);
+        + openSpecButton('subsystem', s.id)
+        + (s.project ? staticChip(s.external ? 'external project' : 'project') : '')
+        + (s.storage ? staticChip(s.storage) : '')
+        + openProjectButton(s);
       body += '<p class="desc">' + esc(s.description) + '</p>';
+      var nodeRels = relationsTouching(s.id);
+      if (nodeRels.length) body += section('Relations', nodeRels.length, nodeRels.map(relationHtml).join(''), true);
+      else if (s.project && HAS_CONSUMPTION && !HAS_RELATIONS) body += section('Relations', null, '<span class="desc">relation health was not checked</span>', true);
       if (s.trustedLinks.length) {
         body += section('Trusted links (fast lanes)', s.trustedLinks.length, s.trustedLinks.map(function (t2) {
           return '<div class="method">' + chip(t2.subsystem, 'subsystem', t2.subsystem) + '<div class="mdesc">' + esc(t2.reason) + '</div></div>';
@@ -10025,6 +10251,14 @@ var MODEL = __MODEL_JSON__;
         });
       })(ospecs[si]);
     }
+    var oprojs = panel.querySelectorAll('[data-openproject-id]');
+    for (var opi = 0; opi < oprojs.length; opi++) {
+      (function (b) {
+        b.addEventListener('click', function () {
+          if (typeof opts !== 'undefined' && opts && typeof opts.onOpenProject === 'function') opts.onOpenProject(b.getAttribute('data-openproject-id'));
+        });
+      })(oprojs[opi]);
+    }
     var flows = panel.querySelectorAll('[data-flow-comp]');
     for (var j = 0; j < flows.length; j++) {
       (function (b) {
@@ -11077,7 +11311,14 @@ function externalStatus(binding, lock) {
   const { external } = binding;
   const entry = lock?.externals[external.alias];
   const pinned = entry !== void 0 && externalsRepository.readSnapshot(external.alias) !== null;
-  const base = { alias: external.alias, project: external.project, sourceKind: external.sourceKind, pinned };
+  const base = {
+    alias: external.alias,
+    project: external.project,
+    sourceKind: external.sourceKind,
+    pinned,
+    ...entry !== void 0 ? { pinnedDigest: entry.digest } : {},
+    ...entry?.commit !== void 0 ? { pinnedCommit: entry.commit } : {}
+  };
   const unreadable = external.sourceKind === "unresolved" ? hostedOnly(external) ? external.problem : `the external does not resolve: ${external.problem}` : producerUnreadable(external);
   let live = null;
   let reason = unreadable;
@@ -11361,7 +11602,8 @@ function reachCeiling(root, family) {
 }
 function within2(dir, ceiling, fn) {
   if (ceiling === null) return runWithProjectRoot(dir, fn);
-  return runWithProjectBinding(dir, { topRoot: ceiling.topRoot, parentReach: true, narrowed: ceiling.narrowed }, fn);
+  const lookup2 = getHostedLookup();
+  return runWithProjectBinding(dir, { topRoot: ceiling.topRoot, parentReach: true, narrowed: ceiling.narrowed, ...lookup2 ? { hostedLookup: lookup2 } : {} }, fn);
 }
 function depthOf(family, node) {
   let depth = 0;
@@ -11412,7 +11654,8 @@ function referencedOf(nodes) {
   return out;
 }
 function atReferenced(ref, fn) {
-  return runWithProjectBinding(ref.directory, { topRoot: ref.directory, parentReach: true, narrowed: true }, fn);
+  const lookup2 = getHostedLookup();
+  return runWithProjectBinding(ref.directory, { topRoot: ref.directory, parentReach: true, narrowed: true, ...lookup2 ? { hostedLookup: lookup2 } : {} }, fn);
 }
 function narrowed(family, selected) {
   const keys = /* @__PURE__ */ new Set(["", ...selected.map((s) => s.node.namespace)]);
@@ -11725,6 +11968,86 @@ function projectApprovals(depth) {
   }
   return entries;
 }
+function relationReach(root) {
+  const granted = getRequestParentReach();
+  if (!granted) return null;
+  const lookup2 = getHostedLookup();
+  const base = granted.parentReach ? { topRoot: granted.topRoot ?? root, parentReach: true, ...granted.narrowed ? { narrowed: true } : {} } : { topRoot: root, parentReach: true, narrowed: true };
+  return { ...base, ...lookup2 ? { hostedLookup: lookup2 } : {} };
+}
+function outsideReach(node) {
+  const lookup2 = getHostedLookup();
+  if (!lookup2 || node.namespace === "") return null;
+  return lookup2(node.id ?? node.namespace) === null ? `the project "${node.id ?? node.namespace}" lies outside this request's reach` : null;
+}
+function referenceUse(ref) {
+  return ref.publicName ?? ref.resolved.split("::").pop() ?? ref.authored;
+}
+function failureAt(ref, failures) {
+  const site = `${ref.specId} (${ref.position})`;
+  const last = ref.resolved.split("::").pop() ?? "";
+  return failures.find((i) => i.resolution.callSite === site && (i.resolution.canonicalTarget === ref.authored || (i.resolution.canonicalTarget ?? "").endsWith(`::${last}`)));
+}
+function containedStatus(child, refs, failures) {
+  const base = { alias: child.mountAlias, project: child.id ?? child.namespace, sourceKind: "family", pinned: false };
+  const unreachable = outsideReach(child);
+  if (unreachable) {
+    const uses2 = [...new Set(refs.map(referenceUse))].map((name) => ({ publicName: name, state: "unavailable", code: "EXTERNAL_CHECK_UNAVAILABLE", detail: unreachable }));
+    return { ...base, reachable: false, stale: false, outOfReach: true, uses: uses2, detail: unreachable };
+  }
+  const uses = [];
+  for (const ref of refs) {
+    const failed = failureAt(ref, failures);
+    const use = failed ? { publicName: referenceUse(ref), state: "removed", code: failed.code, detail: failed.resolution.reason } : { publicName: referenceUse(ref), state: "unchanged" };
+    if (!uses.some((u) => u.publicName === use.publicName && u.state === use.state)) uses.push(use);
+  }
+  return { ...base, reachable: true, stale: uses.some((u) => u.state === "removed"), uses, detail: "a contained member, read live \u2014 nothing is pinned" };
+}
+function containedRelations(answered) {
+  const own = graph();
+  const consumed = own.nodes.filter((n) => n.parent === "" && n.mountAlias !== void 0 && !answered.some((s) => s.alias === n.mountAlias)).map((child) => ({
+    child,
+    refs: own.authoredReferences.filter((r) => (own.owners.get(r.specId) ?? "") === "" && r.producer === child.namespace && r.binding !== "local")
+  })).filter((c) => c.refs.length > 0);
+  if (consumed.length === 0) return [];
+  const config = configOrNull();
+  const failures = validateProject({ rules: config?.rules, projectType: config?.projectType }).issues.filter((i) => i.resolution !== void 0 && i.resolution.outcome !== "resolved");
+  return consumed.map(({ child, refs }) => containedStatus(child, refs, failures));
+}
+function relationsAt(key, dir, reach2) {
+  const bound2 = (fn) => reach2 === null ? runWithProjectRoot(dir, fn) : runWithProjectBinding(dir, reach2, fn);
+  return bound2(() => {
+    const statuses = getExternalsStatus2();
+    const contained = containedRelations(statuses);
+    return { project: key, externals: [...statuses, ...contained], comparedAt: (/* @__PURE__ */ new Date()).toISOString() };
+  });
+}
+function unopened(key, detail) {
+  return { project: key, externals: [], comparedAt: (/* @__PURE__ */ new Date()).toISOString(), detail };
+}
+function familyRelations() {
+  const family = graph();
+  const root = path17.resolve(getProjectRoot());
+  const reach2 = relationReach(root);
+  const out = [];
+  for (const node of family.nodes) {
+    const unreachable = outsideReach(node);
+    if (unreachable || !fs12.existsSync(node.directory)) {
+      out.push(unopened(node.namespace, unreachable ?? `its root ${node.directory} does not exist`));
+      continue;
+    }
+    out.push(relationsAt(node.namespace, node.directory, reach2));
+  }
+  for (const ref of referencedOf(family.nodes)) {
+    if (ref.directory === void 0) {
+      out.push(unopened(ref.key, ref.problem ?? "its root could not be located"));
+      continue;
+    }
+    const lookup2 = getHostedLookup();
+    out.push(relationsAt(ref.key, ref.directory, { topRoot: ref.directory, parentReach: true, narrowed: true, ...lookup2 ? { hostedLookup: lookup2 } : {} }));
+  }
+  return out;
+}
 function requiredBy(key) {
   return key === "" ? "the family root" : `"${key}"`;
 }
@@ -23340,6 +23663,9 @@ function directMemberSubjects() {
 function familyApprovals(depth) {
   return projectApprovals(depth);
 }
+function familyRelations2() {
+  return familyRelations();
+}
 var EXCERPT_EPOCH, GRADE_ORDER, NEVER_SUBJECT;
 var init_validation = __esm({
   "src/core/validation.ts"() {
@@ -23367,10 +23693,11 @@ var init_validation = __esm({
 });
 
 // src/core/diagram.ts
-function renderDiagram(format) {
+function renderDiagram(format, relations) {
   switch (format) {
+    // Only the canvas carries relation health; the other formats ignore it.
     case "canvas":
-      return renderCanvasHtml(buildCanvasModel(diagramIssues()));
+      return renderCanvasHtml(buildCanvasModel(diagramIssues(), relations));
     case "mermaid":
       return generateComponentDiagram();
     case "drawio":
@@ -23381,8 +23708,8 @@ function renderDiagram(format) {
       throw new Error(`Unsupported diagram format "${format}" (canvas | mermaid | drawio | excalidraw).`);
   }
 }
-function buildCanvasDataModel() {
-  return buildCanvasModel(diagramIssues());
+function buildCanvasDataModel(relations) {
+  return buildCanvasModel(diagramIssues(), relations);
 }
 function diagramIssues() {
   try {
@@ -24659,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;
@@ -26375,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";
@@ -26411,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;
@@ -27086,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
@@ -27096,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());
       }
@@ -27453,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();
@@ -27603,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;
       }
@@ -27663,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;
       }
@@ -27792,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;
       }
@@ -27848,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;
       }
@@ -27900,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;
       }
@@ -27930,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;
       }
@@ -28133,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;
       }
@@ -29047,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 {
@@ -29086,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
@@ -31035,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;
@@ -31048,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;
@@ -31084,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;
@@ -31162,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);
@@ -31248,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,
@@ -31271,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);
@@ -41075,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) };
 }
@@ -41122,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);
@@ -43240,7 +43732,10 @@ var init_server = __esm({
         stale: import_zod11.z.boolean(),
         drifted: import_zod11.z.boolean().optional(),
         uses: import_zod11.z.array(import_zod11.z.record(import_zod11.z.unknown())),
-        detail: import_zod11.z.string().optional()
+        detail: import_zod11.z.string().optional(),
+        outOfReach: import_zod11.z.boolean().optional(),
+        pinnedDigest: import_zod11.z.string().optional().describe("The content digest the lock recorded; provenance, never compared here."),
+        pinnedCommit: import_zod11.z.string().optional().describe("The producer commit the lock recorded, for one in another repository; provenance only.")
       })).describe("One status per declared external, in declaration order; EXTERNAL_CHECK_UNAVAILABLE marks what could not be compared."),
       ...staleServerOutput
     };
@@ -47113,12 +47608,16 @@ function parseSequenceRef(ref) {
   }
   return { component: ref.slice(0, sep18), method: ref.slice(sep18 + 1) };
 }
+function canvasRelations(options) {
+  if (options.health === false) return void 0;
+  return familyRelations2();
+}
 async function runDiagram(rawOptions = {}) {
   assertProjectInitialized();
   const options = applyFormat(rawOptions);
   if (options.canvas && !options.all) {
     const dest2 = options.out ?? path58.join(AI_PATHS.docsDir(), "diagrams", "canvas.html");
-    writeArtifact(dest2, renderDiagram("canvas"));
+    writeArtifact(dest2, renderDiagram("canvas", canvasRelations(options)));
     logger.success(`Interactive canvas written to ${dest2}`);
     logger.info("Open it in a browser \u2014 fully self-contained (works offline).");
     return;
@@ -47140,7 +47639,7 @@ async function runDiagram(rawOptions = {}) {
   const wantsMermaid = options.format?.toLowerCase().startsWith("mermaid") || !!options.subsystem || !!options.sequence;
   if (!options.all && !options.sequence && !wantsMermaid) {
     const dest2 = options.out ?? path58.join(AI_PATHS.docsDir(), "diagrams", "canvas.html");
-    writeArtifact(dest2, renderDiagram("canvas"));
+    writeArtifact(dest2, renderDiagram("canvas", canvasRelations(options)));
     logger.success(`Interactive canvas written to ${dest2}`);
     logger.info("Open it in a browser \u2014 fully self-contained (works offline). Other formats: --format mermaid|drawio|excalidraw.");
     return;
@@ -47155,7 +47654,7 @@ async function runDiagram(rawOptions = {}) {
     for (const file of files) {
       writeArtifact(path58.join(outDir, file.relPath), toMarkdown(file));
     }
-    writeArtifact(path58.join(outDir, "canvas.html"), renderDiagram("canvas"));
+    writeArtifact(path58.join(outDir, "canvas.html"), renderDiagram("canvas", canvasRelations(options)));
     writeArtifact(path58.join(outDir, "architecture.drawio"), renderDiagram("drawio"));
     writeArtifact(path58.join(outDir, "architecture.excalidraw"), renderDiagram("excalidraw"));
     const graph2 = loadSpecGraph();
@@ -48147,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).`);
@@ -49064,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: "",
@@ -49173,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) {
@@ -49210,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];
@@ -49252,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,
@@ -49262,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,
@@ -49288,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);
 }
@@ -49303,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), {
@@ -49312,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;
@@ -49327,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) {
@@ -49347,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" };
@@ -49841,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;
@@ -50023,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" };
@@ -50218,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") {
@@ -50236,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");
@@ -50271,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(", ")})`);
@@ -50294,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));
@@ -50311,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) }));
 }
@@ -51468,6 +52155,7 @@ init_validation();
 init_errors();
 init_validation();
 init_validation();
+init_validation();
 function validateAsComplete2() {
   const config = loadProjectConfig();
   if (!config) throw new ProjectNotInitializedError();
@@ -51888,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);
@@ -52437,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,
@@ -52444,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) } : {},
@@ -52454,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);
@@ -52482,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 ?? "" };
@@ -52498,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);
@@ -52533,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"));
@@ -55799,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));
@@ -55830,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());
@@ -57112,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) {
@@ -57239,20 +57995,31 @@ function getSnapshot2(dataDir, snapshotId) {
 function getSnapshotArtifact(dataDir, snapshotId, kind, portalId) {
   return new ShareSnapshotIndex(new ShareSnapshotStore(dataDir)).getArtifact(snapshotId, kind, portalId);
 }
+function creatorReach(dataDir, principal, projectId, root) {
+  const familyRoot = listFamilyRecords(dataDir, projectId)[0];
+  const top = familyRoot !== void 0 ? resolveProjectRoot(dataDir, principal, familyRoot.id) : null;
+  return {
+    topRoot: top ?? root,
+    parentReach: top !== null,
+    hostedLookup: (id) => resolveProjectRoot(dataDir, principal, id)
+  };
+}
 function captureSnapshot(dataDir, principal, projectId, view, artifacts) {
   const root = resolveProjectRoot(dataDir, principal, projectId);
   if (!root) throw new ForbiddenError("project not authorized or unknown");
+  const relations = runWithProjectBinding(root, creatorReach(dataDir, principal, projectId, root), () => familyRelations2());
   return runWithProjectRoot(root, () => {
     const snapshot = {
       id: "",
       projectId,
       view,
       capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      // The canvas model is the primary payload the shared view renders.
-      canvasModel: JSON.stringify(buildCanvasDataModel())
+      // Step 3: the canvas model is the primary payload the shared view renders,
+      // with those relations on its consumption edges and no member record ids.
+      canvasModel: JSON.stringify(buildCanvasDataModel(relations))
     };
     if (artifacts.includes("html")) {
-      snapshot.html = renderDiagram("canvas");
+      snapshot.html = renderDiagram("canvas", relations);
     }
     if (artifacts.includes("openapi")) {
       const result = exportSurface2("project", "openapi");
@@ -57807,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);
@@ -57819,17 +58588,34 @@ function getWebProjectCanvasModel(cfg, sessionId, projectId) {
   if (!root) {
     throw new ForbiddenError("project not authorized or unknown");
   }
-  const model = runWithProjectRoot(root, () => buildCanvasDataModel());
-  const readable = new Set(listProjects2(cfg, sessionId).map((r) => r.id));
+  const listed = listProjects2(cfg, sessionId);
+  const relations = runWithProjectBinding(root, readReach(cfg, projectId, root, listed), () => familyRelations2());
+  const model = runWithProjectRoot(root, () => buildCanvasDataModel(relations));
+  const readable = new Set(listed.map((r) => r.id));
   const members = new Set(listFamilyRecords(cfg.dataDir, projectId).filter((r) => r.parentProjectId !== void 0).map((r) => r.id));
-  return withMemberLinks(model, (id) => members.has(id) && readable.has(id));
+  const hostedOf = externalRecords(runWithProjectRoot(root, () => loadProjectConfig()));
+  return withProjectLinks(model, (node) => {
+    const id = node.external ? hostedOf.get(node.id) : node.id;
+    if (id === void 0 || !readable.has(id)) return void 0;
+    return node.external || members.has(id) ? id : void 0;
+  });
+}
+function externalRecords(config) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [alias, decl] of Object.entries(config?.externals ?? {})) {
+    if (decl?.source?.hosted !== void 0) out.set(alias, decl.source.hosted);
+  }
+  return out;
 }
-function withMemberLinks(model, linkable) {
+function withProjectLinks(model, linkOf) {
   const m = model;
   if (!Array.isArray(m.subsystems)) return model;
   return {
     ...model,
-    subsystems: m.subsystems.map((s) => s.project && linkable(s.id) ? { ...s, recordId: s.id } : s)
+    subsystems: m.subsystems.map((s) => {
+      const recordId = s.project ? linkOf(s) : void 0;
+      return recordId !== void 0 ? { ...s, recordId } : s;
+    })
   };
 }
 function getWebProjectExternals(cfg, sessionId, projectId) {
@@ -59976,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);
 }
@@ -60477,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));
       }
@@ -60862,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",
@@ -60897,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
     }
   };
@@ -61084,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));
@@ -61124,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",
@@ -61146,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 {
@@ -61156,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 };
       }
@@ -61202,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);
@@ -61244,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) => {
@@ -62786,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" };
@@ -62825,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
@@ -62835,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;
@@ -64200,7 +65034,7 @@ var variantsCmd = program.command("variants").description("Component variants \u
 variantsCmd.command("list").alias("ls").description("List the component variants in the registry (global + project) with their base and guidance").action(async () => {
   await runVariants();
 });
-program.command("diagram").description("Generate architecture diagrams from the spec tree \u2014 interactive canvas by default; Mermaid / draw.io / Excalidraw via --format").option("--subsystem <id>", "scope the component diagram to one subsystem (plus its external neighbors)").option("--sequence <component:method>", "emit a sequence diagram derived from the method's L5 narrative").option("--depth <n>", "max call-expansion depth for sequence diagrams (default 3)", (v) => parseInt(v, 10)).option("--all", "write the full diagram set: system, per-subsystem, entrypoint sequences, and the interactive canvas").option("--canvas", "emit the interactive self-contained HTML canvas (pan/zoom, collapse boundaries, detail panel, issue overlay)").option("--drawio", "emit an editable draw.io / diagrams.net file (same layout as the canvas)").option("--excalidraw", "emit an editable Excalidraw scene (same layout as the canvas)").option("--format <fmt>", "alias for the flags above: mermaid | canvas | drawio | excalidraw").option("--out <path>", "write to a file (or directory with --all; default .wai/docs/diagrams) instead of stdout").action(async (opts) => {
+program.command("diagram").description("Generate architecture diagrams from the spec tree \u2014 interactive canvas by default; Mermaid / draw.io / Excalidraw via --format").option("--subsystem <id>", "scope the component diagram to one subsystem (plus its external neighbors)").option("--sequence <component:method>", "emit a sequence diagram derived from the method's L5 narrative").option("--depth <n>", "max call-expansion depth for sequence diagrams (default 3)", (v) => parseInt(v, 10)).option("--all", "write the full diagram set: system, per-subsystem, entrypoint sequences, and the interactive canvas").option("--canvas", "emit the interactive self-contained HTML canvas (pan/zoom, collapse boundaries, detail panel, issue overlay)").option("--drawio", "emit an editable draw.io / diagrams.net file (same layout as the canvas)").option("--excalidraw", "emit an editable Excalidraw scene (same layout as the canvas)").option("--format <fmt>", "alias for the flags above: mermaid | canvas | drawio | excalidraw").option("--out <path>", "write to a file (or directory with --all; default .wai/docs/diagrams) instead of stdout").option("--no-health", "skip comparing each consumption relation with its live producer: the canvas draws those edges as not checked").action(async (opts) => {
   await runDiagram({
     subsystem: opts.subsystem,
     sequence: opts.sequence,
@@ -64210,7 +65044,8 @@ program.command("diagram").description("Generate architecture diagrams from the
     drawio: opts.drawio,
     excalidraw: opts.excalidraw,
     format: opts.format,
-    out: opts.out
+    out: opts.out,
+    health: opts.health
   });
 });
 program.command("list").alias("ls").description("List all dynamic agents resolved from the spec tree").action(async () => {
@@ -64372,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,