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

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.92";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     SUPPORTED_ALIASES = ["wai"];
     SCAN_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
@@ -3229,6 +3229,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 +5591,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 +5612,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 +5773,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 +5914,7 @@ function buildCanvasModel(issues = []) {
     ],
     components: modelComponents,
     edges,
+    ...canvasRelations2 !== void 0 ? { relations: canvasRelations2 } : {},
     types: modelTypes,
     typeEdges,
     dataEdges,
@@ -6029,6 +6097,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 +6283,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 +6611,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 +6633,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 +6696,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 +6741,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 +6831,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 +7299,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 +7867,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 +8075,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 +8581,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 +8659,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 +9904,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 +10074,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 +10161,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 +10235,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 +11295,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 +11586,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 +11638,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 +11952,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 +23647,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 +23677,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 +23692,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 {
@@ -43240,7 +43551,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 +47427,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 +47458,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 +47473,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();
@@ -51468,6 +51786,7 @@ init_validation();
 init_errors();
 init_validation();
 init_validation();
+init_validation();
 function validateAsComplete2() {
   const config = loadProjectConfig();
   if (!config) throw new ProjectNotInitializedError();
@@ -57239,20 +57558,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");
@@ -57819,17 +58149,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 withMemberLinks(model, linkable) {
+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 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) {
@@ -64200,7 +64547,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 +64557,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 () => {