@wairon/cli 5.1.1-dev.12 → 5.1.1-dev.13

package/dist/index.js

@@ -1312,7 +1312,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.1.1-dev.12";
+    WAIRON_VERSION = "5.1.1-dev.13";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     ARCHITECT_AGENT_ID = "agent-architect";
     ARCHITECT_TEMPLATE_ID = "architect";
@@ -2884,17 +2884,43 @@ function isExternalNamespaceRef(ctx, ref) {
   if (sep6 === -1) return false;
   return !ctx.subsystemIds.has(ref.slice(0, sep6));
 }
+function isProvidedBy(snapshot, provider) {
+  return snapshot.projectName === provider || snapshot.projectName.split("::").pop() === provider;
+}
+function sameContract(a, b) {
+  return a.component.split("::").pop() === b.component.split("::").pop() && JSON.stringify(a.methods) === JSON.stringify(b.methods) && JSON.stringify(a.dispatch ?? []) === JSON.stringify(b.dispatch ?? []);
+}
 function resolveSurfaceRef(ctx, ref, fromSubsystem) {
-  const local = ref.split("::").filter((seg) => seg && seg !== "super").pop();
-  if (!local) return null;
+  const segments = ref.split("::").filter((seg) => seg && seg !== "super");
+  const local = segments.pop();
+  if (!local) return { kind: "unresolved" };
+  const provider = segments.pop();
   const mountPools = fromSubsystem ? enclosingMounts(ctx, fromSubsystem).reverse().map((ns) => ctx.mountSurfaceSnapshots.find((m) => m.namespace === ns)?.snapshots ?? []) : [];
   for (const pool of [...mountPools, ctx.surfaceSnapshots]) {
+    const candidates = [];
     for (const snapshot of pool) {
+      if (provider !== void 0 && !isProvidedBy(snapshot, provider)) continue;
       const entry = snapshot.interfaces.find((e) => e.component === local || e.id === local);
-      if (entry) return { snapshot, entry };
+      if (entry) candidates.push({ snapshot, entry });
+    }
+    if (candidates.length === 0) continue;
+    const [first] = candidates;
+    if (candidates.every((c) => sameContract(c.entry, first.entry))) {
+      return { kind: "resolved", ...first };
     }
+    return { kind: "ambiguous", providers: [...new Set(candidates.map((c) => c.snapshot.projectName))] };
   }
-  return null;
+  return { kind: "unresolved" };
+}
+function reportAmbiguousSurfaceRef(ctx, subject, ref, providers, specId, isDraftContext) {
+  const local = ref.split("::").filter((seg) => seg && seg !== "super").pop() ?? ref;
+  ctx.addIssue(
+    "error",
+    "SURFACE_REF_AMBIGUOUS",
+    `${subject} cross-tree component "${ref}", which the surface snapshots of ${providers.map((p) => `"${p}"`).join(", ")} expose with different contracts \u2014 the reference matches more than one declared contract, so none of them can judge it. Name the provider it means (super::<provider>::${local}), or remove the snapshot that no longer applies.`,
+    specId,
+    isDraftContext
+  );
 }
 function enclosingMounts(ctx, subsystemId) {
   const mounts = [];
@@ -2985,6 +3011,7 @@ var init_contracts = __esm({
         { code: "INVALID_TARGET_COMPONENT_REFERENCE", defaultSeverity: "error", summary: "Call/register step targets a non-existent component" },
         { code: "CROSS_TREE_REF_UNRESOLVED", defaultSeverity: "warning", summary: "Cross-tree reference (super::/:: form) with no surface snapshot covering it \u2014 only the parent project can verify it" },
         { code: "SURFACE_REF_NOT_EXPOSED", defaultSeverity: "error", summary: "Cross-tree reference resolves to a surface snapshot that does not expose the called method/capability" },
+        { code: "SURFACE_REF_AMBIGUOUS", defaultSeverity: "error", summary: "Cross-tree call/dispatch/register target matched by surface snapshots of several providers with different contracts" },
         { code: "UNDECLARED_DEPENDENCY_CALL", defaultSeverity: "error", summary: "Call step targets a component the caller does not depend on or own" },
         { code: "INVALID_TARGET_METHOD_REFERENCE", defaultSeverity: "error", summary: "Call step targets a method not on any target interface" },
         { code: "NARRATIVE_SEMANTIC_UNBACKED", defaultSeverity: "warning", summary: "Narrative asserts a guarantee the called contract does not declare" }
@@ -3039,7 +3066,18 @@ var init_contracts = __esm({
                 if (!dispatchTarget) {
                   if (isCrossTreeForm || isCollapsedForm) {
                     const resolved = resolveSurfaceRef(ctx, step.targetComponent, fromSubsystem);
-                    if (resolved) {
+                    if (resolved.kind === "ambiguous") {
+                      reportAmbiguousSurfaceRef(
+                        ctx,
+                        `Method "${implMethod.name}" in implementation "${impl.id}" dispatches (step ${step.stepNumber}) through`,
+                        step.targetComponent,
+                        resolved.providers,
+                        impl.id,
+                        isDraftCtx
+                      );
+                      continue;
+                    }
+                    if (resolved.kind === "resolved") {
                       if (step.capability && !(resolved.entry.dispatch ?? []).some((b) => b.capability === step.capability)) {
                         ctx.addIssue(
                           "error",
@@ -3099,7 +3137,18 @@ var init_contracts = __esm({
               if (!targetComp) {
                 if (isCrossTreeForm || isCollapsedForm) {
                   const resolved = resolveSurfaceRef(ctx, step.targetComponent, fromSubsystem);
-                  if (resolved) {
+                  if (resolved.kind === "ambiguous") {
+                    reportAmbiguousSurfaceRef(
+                      ctx,
+                      `Method "${implMethod.name}" in implementation "${impl.id}" ${verb} "${step.targetMethod}" (step ${step.stepNumber}) on`,
+                      step.targetComponent,
+                      resolved.providers,
+                      impl.id,
+                      isDraftCtx
+                    );
+                    continue;
+                  }
+                  if (resolved.kind === "resolved") {
                     const surfaceMethod = resolved.entry.methods.find((m) => m.name === step.targetMethod);
                     if (!surfaceMethod) {
                       ctx.addIssue(
@@ -4614,6 +4663,7 @@ var init_stereotype_deps = __esm({
       codes: [
         { code: "INVALID_DEPENDENCY_REFERENCE", defaultSeverity: "error", summary: "dependsOn names a non-existent component" },
         { code: "CROSS_TREE_REF_UNRESOLVED", defaultSeverity: "warning", summary: "Cross-tree dependsOn (super::/:: form) with no surface snapshot covering it" },
+        { code: "SURFACE_REF_AMBIGUOUS", defaultSeverity: "error", summary: "Cross-tree dependsOn matched by surface snapshots of several providers with different contracts" },
         { code: "CROSS_SUBSYSTEM_NON_ADAPTER", defaultSeverity: "error", summary: "Non-Adapter component crossing a subsystem boundary" },
         { code: "CROSS_SUBSYSTEM_PRIVATE_ACCESS", defaultSeverity: "error", summary: "Cross-subsystem dependency on an unpublished component" },
         { code: "CROSS_SUBSYSTEM_TARGET_NON_PORTAL", defaultSeverity: "error", summary: "Cross-subsystem hop entering through a non-Portal" },
@@ -4637,7 +4687,11 @@ var init_stereotype_deps = __esm({
               const external = isExternalNamespaceRef(ctx, depId);
               if (external || isCollapsedCrossTreeRef(ctx, depId, comp.subsystem)) {
                 const resolved = resolveSurfaceRef(ctx, depId, comp.subsystem);
-                if (resolved) {
+                if (resolved.kind === "ambiguous") {
+                  reportAmbiguousSurfaceRef(ctx, `Component "${comp.id}" depends on`, depId, resolved.providers, comp.id, isDraftCtx);
+                  continue;
+                }
+                if (resolved.kind === "resolved") {
                   if (comp.componentType !== "Adapter") {
                     ctx.addIssue(
                       "error",
@@ -8343,8 +8397,8 @@ function doctrineIdentity(doctrine, gate) {
     )
   };
 }
-function hashGateState(doctrine, gate = {}) {
-  const payload = { tree: loadTree(), doctrine: doctrineIdentity(doctrine, gate) };
+function hashGateState(doctrine, inputs, gate = {}) {
+  const payload = { tree: loadTree(), doctrine: doctrineIdentity(doctrine, gate), inputs: [...inputs].sort() };
   const digest2 = crypto2.createHash("sha256").update(canonicalize(payload)).digest("hex");
   return { algorithm: GATE_ALGORITHM, digest: digest2 };
 }
@@ -8375,7 +8429,7 @@ var init_statehash = __esm({
     init_specs2();
     init_rules();
     CONTENT_ALGORITHM = "sha256";
-    GATE_ALGORITHM = "sha256+doctrine";
+    GATE_ALGORITHM = "sha256+doctrine+inputs";
   }
 });
 
@@ -14138,15 +14192,18 @@ function importSurface(sourcePath, origin) {
   saveSnapshot(snapshot);
   return snapshot;
 }
-function pinFamilySurfaces() {
-  const parent = resolveChainingParent();
-  if (!parent) return null;
-  const childRoot = getProjectRoot();
-  const projected = runWithProjectRoot(parent.parentRoot, () => {
+function projectFamilySurfaces(parent) {
+  return runWithProjectRoot(parent.parentRoot, () => {
     invalidateSpecCache();
     const siblings = loadSubsystemSpecs().filter((s) => !s.id.includes("::") && s.id !== parent.subsystemId);
     return [projectChildSurface(), ...siblings.map((s) => projectSubsystemSurface(s.id))];
   });
+}
+function pinFamilySurfaces() {
+  const parent = resolveChainingParent();
+  if (!parent) return null;
+  const childRoot = getProjectRoot();
+  const projected = projectFamilySurfaces(parent);
   const before = new Map(listSnapshots(childRoot).map((s) => [s.projectName, surfaceContentKey(s)]));
   const changed = [];
   for (const snapshot of projected) {
@@ -14157,17 +14214,21 @@ function pinFamilySurfaces() {
   }
   return changed;
 }
-function computeParentStateId(parentRoot) {
-  return computeStateIdAt(parentRoot);
+function projectedFamilyContent(parent) {
+  try {
+    return new Map(projectFamilySurfaces(parent).map((s) => [s.projectName, surfaceContentKey(s)]));
+  } catch {
+    return null;
+  }
 }
 function listExternalInterfaces() {
   const snapshots = listSnapshots();
   const chainingParent = resolveChainingParent();
-  const parentStateId = chainingParent ? computeParentStateId(chainingParent.parentRoot) : null;
+  const projected = chainingParent ? projectedFamilyContent(chainingParent) : null;
   return snapshots.map((snapshot) => {
     const generated = snapshot.origin === "generated";
     const sourceKind = !generated ? "foreign" : snapshot.projectName.includes("::") ? "sibling" : "parent";
-    const freshness = generated && parentStateId ? snapshot.stateId === parentStateId ? "fresh" : "stale" : "unverifiable";
+    const freshness = generated && projected ? projected.get(snapshot.projectName) === surfaceContentKey(snapshot) ? "fresh" : "stale" : "unverifiable";
     return {
       projectName: snapshot.projectName,
       origin: snapshot.origin,
@@ -14505,7 +14566,7 @@ function validateSddTree(rulesOrOptions, projectType = "backend") {
       rule.check(ctx);
     }
     const unresolved = (i) => RESOLUTION_FAILURE_CODES.has(i.code) && !i.surfaceResolved;
-    const chainingParent = crossTree !== "off" && issues.some(unresolved) ? findChainingParent(getProjectRoot()) : null;
+    const chainingParent = crossTree !== "off" && issues.some(unresolved) ? resolveChainingParent() : null;
     const resolution = chainingParent ? resolveThroughParent(getProjectRoot(), treatAllAsComplete, rules) : null;
     if (resolution) {
       const judgedByParent = worstByKey(resolution.issues);
@@ -14543,7 +14604,7 @@ function resolveThroughParent(boundRoot, treatAllAsComplete, childRules) {
   const chain = [];
   let top = path14.resolve(boundRoot);
   while (top !== ceiling) {
-    const hop = findChainingParent(top);
+    const hop = findChainingParent(top, ceiling);
     if (!hop) break;
     const next = path14.resolve(hop.parentRoot);
     if (ceiling && !isWithinOrEqual(ceiling, next)) break;
@@ -15273,33 +15334,75 @@ function relativizeId(id, prefix) {
   if (common === idParts.length) common--;
   return `${"super::".repeat(prefixParts.length - common)}${idParts.slice(common).join("::")}`;
 }
+function rebaseReference(ref, mount, direction, isMoved = () => false) {
+  if (!ref || ref.startsWith("::")) return ref;
+  const segments = ref.split("::");
+  let hops = 0;
+  while (segments[hops] === "super") hops++;
+  if (hops === segments.length) return ref;
+  const outer = Array.from({ length: hops + 1 }, (_, i) => `<n${i}>`).join("::");
+  const inner = `${outer}::${mount}`;
+  const [from, to] = direction === "into" ? [outer, inner] : [inner, outer];
+  const target = qualifyId(ref, from, NO_ROOT_SUBSYSTEMS);
+  const left = relativizeId(target, from);
+  const travels = !left.startsWith("super::") && (direction === "outOf" || isMoved(left));
+  return relativizeId(travels ? qualifyId(left, to, NO_ROOT_SUBSYSTEMS) : target, to);
+}
 function isWithin(dir, file) {
   const d = path15.resolve(dir);
   const f = path15.resolve(file);
   return f === d || f.startsWith(d + path15.sep);
 }
+function canonicalPath(target) {
+  let existing = path15.resolve(target);
+  const rest = [];
+  for (; ; ) {
+    try {
+      fs9.lstatSync(existing);
+      break;
+    } catch {
+      const up = path15.dirname(existing);
+      if (up === existing) return path15.resolve(target);
+      rest.unshift(path15.basename(existing));
+      existing = up;
+    }
+  }
+  try {
+    return path15.join(fs9.realpathSync.native(existing), ...rest);
+  } catch {
+    return null;
+  }
+}
+function chainDirKey(dir) {
+  return canonicalPath(dir) ?? path15.resolve(dir);
+}
 function projectPathEscapesRoot(projectRoot, projectPath, resolvedChildDir) {
-  return path15.isAbsolute(projectPath) || !isWithin(projectRoot, resolvedChildDir);
+  if (path15.isAbsolute(projectPath) || !isWithin(projectRoot, resolvedChildDir)) return true;
+  const root = canonicalPath(projectRoot);
+  const child = canonicalPath(resolvedChildDir);
+  return root === null || child === null || !isWithin(root, child);
 }
 function assertContainedProjectPath(projectRoot, projectPath) {
   const root = path15.resolve(projectRoot);
   const resolved = path15.resolve(root, projectPath);
   if (projectPathEscapesRoot(root, projectPath, resolved)) {
     throw new Error(
-      `projectPath "${projectPath}" must resolve within the project root "${root}", but resolves to "${resolved}"; absolute paths and ../-escaping paths are rejected so a chained subproject is always contained by its parent.`
+      `projectPath "${projectPath}" must resolve within the project root "${root}", but resolves to "${resolved}"; absolute, ../-escaping and link-escaping paths are rejected so a chained subproject is always contained by its parent.`
     );
   }
   return resolved;
 }
-function findChainingParent(childRoot) {
+function findChainingParent(childRoot, ceiling) {
   let childResolved;
   try {
     childResolved = path15.resolve(childRoot);
   } catch {
     return null;
   }
+  const bound = ceiling ? path15.resolve(ceiling) : void 0;
   let dir = path15.dirname(childResolved);
   for (let hops = 0; hops < 32; hops++) {
+    if (bound && !isWithin(bound, dir)) break;
     const specsDir = aiPathsAt(dir).specsDir();
     if (pathExists(specsDir)) {
       for (const file of listFilesRecursive(specsDir, ".yaml")) {
@@ -15313,7 +15416,8 @@ function findChainingParent(childRoot) {
           const projectPath = raw.projectPath;
           if (typeof projectPath === "string" && projectPath.trim() !== "") {
             try {
-              if (path15.resolve(dir, projectPath) === childResolved) {
+              const mountDir = path15.resolve(dir, projectPath);
+              if (mountDir === childResolved && !projectPathEscapesRoot(dir, projectPath, mountDir)) {
                 const id = raw.id;
                 return { parentRoot: dir, subsystemId: typeof id === "string" ? id : "?" };
               }
@@ -15329,12 +15433,11 @@ function findChainingParent(childRoot) {
   }
   return null;
 }
-function listChainedRoots(rootDir = getProjectRoot()) {
+function inspectChainedRoots(rootDir = getProjectRoot()) {
   const root = path15.resolve(rootDir);
-  const found = [];
-  const visited = /* @__PURE__ */ new Set([root]);
-  const walk = (projectDir, depth) => {
-    if (depth > 32) return;
+  const inspection = { roots: [], skipped: [] };
+  const listed = /* @__PURE__ */ new Set();
+  const walk = (projectDir, prefix, ancestors, depth) => {
     const specsDir = aiPathsAt(projectDir).specsDir();
     if (!pathExists(specsDir)) return;
     for (const file of listFilesRecursive(specsDir, ".yaml")) {
@@ -15345,24 +15448,37 @@ function listChainedRoots(rootDir = getProjectRoot()) {
         continue;
       }
       if (!raw || typeof raw !== "object" || !("parentSystem" in raw)) continue;
-      const projectPath = raw.projectPath;
+      const { id, projectPath } = raw;
       if (typeof projectPath !== "string" || projectPath.trim() === "") continue;
+      const localId = typeof id === "string" ? id : "?";
       let childDir;
       try {
         childDir = path15.resolve(projectDir, projectPath);
       } catch {
         continue;
       }
-      if (projectPathEscapesRoot(root, projectPath, childDir)) continue;
-      if (visited.has(childDir)) continue;
-      if (!fs9.existsSync(childDir)) continue;
-      visited.add(childDir);
-      found.push(path15.relative(root, childDir).split(path15.sep).join("/"));
-      walk(childDir, depth + 1);
+      let reason;
+      if (projectPathEscapesRoot(projectDir, projectPath, childDir)) reason = "escapes";
+      else if (ancestors.has(chainDirKey(childDir))) reason = "cyclic";
+      else if (!fs9.existsSync(childDir)) reason = "missing";
+      else if (depth >= 32) reason = "too-deep";
+      if (reason) {
+        const mount = prefix ? qualifyDeclaredId(localId, prefix, true) : localId;
+        inspection.skipped.push({ mount, projectPath, reason });
+        continue;
+      }
+      const key = chainDirKey(childDir);
+      if (listed.has(key)) continue;
+      listed.add(key);
+      inspection.roots.push(path15.relative(root, childDir).split(path15.sep).join("/"));
+      walk(childDir, prefix ? `${prefix}::${localId}` : localId, /* @__PURE__ */ new Set([...ancestors, key]), depth + 1);
     }
   };
-  walk(root, 0);
-  return found;
+  walk(root, "", /* @__PURE__ */ new Set([chainDirKey(root)]), 0);
+  return inspection;
+}
+function listChainedRoots(rootDir = getProjectRoot()) {
+  return inspectChainedRoots(rootDir).roots;
 }
 function mergeMountRealizations(subs) {
   const result = [];
@@ -15645,12 +15761,24 @@ function buildProjectGraph(level) {
 function resolveChainingParent() {
   const reach = getRequestParentReach();
   if (reach && !reach.parentReach) return null;
-  const parent = findChainingParent(getProjectRoot());
-  if (parent && reach?.topRoot) {
-    const fromTop = path15.relative(path15.resolve(reach.topRoot), path15.resolve(parent.parentRoot));
-    if (fromTop === ".." || fromTop.startsWith(`..${path15.sep}`) || path15.isAbsolute(fromTop)) return null;
+  return findChainingParent(getProjectRoot(), reach?.topRoot);
+}
+function snapshotInputKey(snapshot) {
+  const { stateId, generatedAt, origin, ...content } = snapshot;
+  return canonicalize(content);
+}
+function consumedSurfaceInputsAt(rootDir) {
+  const dir = path15.join(rootDir, ".wai", "surfaces");
+  if (!pathExists(dir)) return [];
+  const keys = [];
+  for (const file of fs9.readdirSync(dir)) {
+    if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
+    try {
+      keys.push(snapshotInputKey(SurfaceSnapshotSchema.parse(readYamlFile(path15.join(dir, file)))));
+    } catch {
+    }
   }
-  return parent;
+  return keys;
 }
 function computeGateStateId() {
   let gate = {};
@@ -15659,7 +15787,10 @@ function computeGateStateId() {
     gate = { projectType: config.projectType, rules: config.rules };
   } catch {
   }
-  return hashGateState(loadProjectExtensions(), gate);
+  const root = getProjectRoot();
+  const roots = [root, ...listChainedRoots(root).map((rel2) => path15.join(root, rel2))];
+  const inputs = roots.flatMap(consumedSurfaceInputsAt);
+  return hashGateState(loadProjectExtensions(), inputs, gate);
 }
 function readLockState() {
   const record = readLockRecord();
@@ -15769,7 +15900,7 @@ var init_specs2 = __esm({
         this.rootSubsystems.clear();
         this.cachedRecursive = recursive;
         this.scanVisitedSpecDirs = [];
-        const visited = /* @__PURE__ */ new Set([path15.resolve(this.rootDir)]);
+        const visited = /* @__PURE__ */ new Set([chainDirKey(this.rootDir)]);
         const maxDepth = typeof recursive === "number" ? recursive : recursive ? Infinity : 0;
         this.cachedIndex = this.scanSpecsForProject(this.rootDir, "", visited, maxDepth, 0);
         this.cachedSpecDirs = this.scanVisitedSpecDirs;
@@ -15969,21 +16100,22 @@ var init_specs2 = __esm({
         if (currentDepth < maxDepth) {
           for (const subproj of localSubprojects) {
             const childDir = path15.resolve(projectDir, subproj.projectPath);
-            if (projectPathEscapesRoot(this.rootDir, subproj.projectPath, childDir)) {
+            const mountId = namespacePrefix ? qualifyDeclaredId(subproj.subsystemId, namespacePrefix, true) : subproj.subsystemId;
+            if (projectPathEscapesRoot(projectDir, subproj.projectPath, childDir)) {
               this.loaderIssues.push({
                 severity: "error",
                 code: "PROJECTPATH_ESCAPE",
-                message: `Subproject path "${subproj.projectPath}" declared by subsystem "${subproj.subsystemId}" escapes the project root "${this.rootDir}" (resolves to "${childDir}"); absolute and ../-escaping projectPaths are rejected. Skipping this subproject.`,
-                specId: subproj.subsystemId
+                message: `Subproject path "${subproj.projectPath}" declared by subsystem "${mountId}" escapes the root of the project declaring it, "${projectDir}" (resolves to "${childDir}"); absolute, ../-escaping and link-escaping projectPaths are rejected. Skipping this subproject.`,
+                specId: mountId
               });
               continue;
             }
-            if (visitedDirs.has(childDir)) {
+            if (visitedDirs.has(chainDirKey(childDir))) {
               this.loaderIssues.push({
                 severity: "error",
                 code: "CIRCULAR_SUBPROJECT_REFERENCE",
-                message: `Circular reference detected: Subsystem "${subproj.subsystemId}" refers to subproject "${childDir}" which is already loaded.`,
-                specId: subproj.subsystemId
+                message: `Circular reference detected: Subsystem "${mountId}" refers to subproject "${childDir}" which is already loaded.`,
+                specId: mountId
               });
               continue;
             }
@@ -15991,14 +16123,14 @@ var init_specs2 = __esm({
               this.loaderIssues.push({
                 severity: "error",
                 code: "SUBPROJECT_NOT_FOUND",
-                message: `Subproject directory "${childDir}" declared by subsystem "${subproj.subsystemId}" does not exist.`,
-                specId: subproj.subsystemId
+                message: `Subproject directory "${childDir}" declared by subsystem "${mountId}" does not exist.`,
+                specId: mountId
               });
               continue;
             }
             const childNamespace = namespacePrefix ? `${namespacePrefix}::${subproj.subsystemId}` : subproj.subsystemId;
             const newVisited = new Set(visitedDirs);
-            newVisited.add(childDir);
+            newVisited.add(chainDirKey(childDir));
             const childIndex = this.scanSpecsForProject(childDir, childNamespace, newVisited, maxDepth, currentDepth + 1);
             index.subsystems.push(...childIndex.subsystems);
             index.components.push(...childIndex.components);
@@ -16031,11 +16163,11 @@ var init_specs2 = __esm({
           const sub = index.subsystems.find((s) => s.id === currentPrefix);
           if (sub && sub.projectPath) {
             const nextDir = path15.resolve(currentDir, sub.projectPath);
-            if (projectPathEscapesRoot(this.rootDir, sub.projectPath, nextDir)) {
+            if (projectPathEscapesRoot(currentDir, sub.projectPath, nextDir)) {
               this.loaderIssues.push({
                 severity: "error",
                 code: "PROJECTPATH_ESCAPE",
-                message: `Subproject path "${sub.projectPath}" declared by subsystem "${currentPrefix}" escapes the project root "${this.rootDir}" (resolves to "${nextDir}"); absolute and ../-escaping projectPaths are rejected. Skipping this subproject.`,
+                message: `Subproject path "${sub.projectPath}" declared by subsystem "${currentPrefix}" escapes the root of the project declaring it, "${currentDir}" (resolves to "${nextDir}"); absolute, ../-escaping and link-escaping projectPaths are rejected. Skipping this subproject.`,
                 specId: currentPrefix
               });
               continue;
@@ -21508,6 +21640,7 @@ __export(src_exports, {
   buildRuleContext: () => buildRuleContext,
   buildServerInstructions: () => buildServerInstructions2,
   buildTreeArchive: () => buildTreeArchive2,
+  canonicalize: () => canonicalize,
   captureApprovedSpecs: () => captureApprovedSpecs,
   checkSkillFreshness: () => checkSkillFreshness,
   clearLoaderIssues: () => clearLoaderIssues,
@@ -21518,7 +21651,6 @@ __export(src_exports, {
   composeVariantGuidance: () => composeVariantGuidance,
   computeGateStateId: () => computeGateStateId,
   computePackDigest: () => computePackDigest,
-  computeParentStateId: () => computeParentStateId,
   computeStateId: () => computeStateId,
   computeStateIdAt: () => computeStateIdAt,
   contextDir: () => contextDir,
@@ -21595,6 +21727,7 @@ __export(src_exports, {
   hashGateState: () => hashGateState,
   importSpecTree: () => importSpecTree,
   importSurface: () => importSurface,
+  inspectChainedRoots: () => inspectChainedRoots,
   inspectTreeArchive: () => inspectTreeArchive2,
   installPackFromDirectory: () => installPackFromDirectory,
   internalizeSubsystem: () => internalizeSubsystem,
@@ -21673,6 +21806,7 @@ __export(src_exports, {
   readResource: () => readResource,
   readSkillResource: () => readSkillResource,
   readYamlFile: () => readYamlFile,
+  rebaseReference: () => rebaseReference,
   registerExporter: () => registerExporter,
   removeFreeStandingDomain: () => removeFreeStandingDomain,
   removeSnapshot: () => removeSnapshot,
@@ -22166,6 +22300,7 @@ function externalizeSubsystem(subsystemId, projectPath) {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
   rewriteRefsInDir(parentSpecsDir, renameMap, fooDir);
+  rebaseMovedRefs(childFooDir, subsystemId, "into");
   invalidateSpecCache();
 }
 function internalizeSubsystem(subsystemId) {
@@ -22205,6 +22340,7 @@ function internalizeSubsystem(subsystemId) {
   });
   fs13.rmSync(childWai, { recursive: true, force: true });
   rewriteRefsInDir(parentSpecsDir, renameMap, fooDir);
+  rebaseMovedRefs(fooDir, subsystemId, "outOf");
   invalidateSpecCache();
 }
 function buildRenameMap(subsystemId, externalize) {
@@ -22231,7 +22367,27 @@ function buildRenameMap(subsystemId, externalize) {
 }
 function rewriteRefsInDir(specsDir, renameMap, excludeDir) {
   if (renameMap.size === 0) return;
-  const remap = (id) => id !== void 0 && renameMap.has(id) ? renameMap.get(id) : id;
+  rewriteRefFields(specsDir, (ref) => renameMap.get(ref) ?? ref, excludeDir);
+}
+function rebaseMovedRefs(movedDir, mount, direction) {
+  const declared = componentIdsUnder(movedDir);
+  rewriteRefFields(movedDir, (ref, position) => position === "component" ? rebaseReference(ref, mount, direction, (id) => declared.has(id)) : ref);
+}
+function componentIdsUnder(dir) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const file of listFilesRecursive(dir, ".yaml")) {
+    let raw;
+    try {
+      raw = readYamlFile(file);
+    } catch {
+      continue;
+    }
+    if (raw && typeof raw === "object" && "componentType" in raw && typeof raw.id === "string") ids.add(raw.id);
+  }
+  return ids;
+}
+function rewriteRefFields(specsDir, remap, excludeDir) {
+  const at = (ref, position) => typeof ref === "string" ? remap(ref, position) : ref;
   for (const file of listFilesRecursive(specsDir, ".yaml")) {
     if (excludeDir && isWithinDir(excludeDir, file)) continue;
     let raw;
@@ -22243,14 +22399,14 @@ function rewriteRefsInDir(specsDir, renameMap, excludeDir) {
     if (!raw || typeof raw !== "object") continue;
     let changed = false;
     if ("componentType" in raw && Array.isArray(raw.dependsOn)) {
-      const next = raw.dependsOn.map((d) => remap(d));
+      const next = raw.dependsOn.map((d) => at(d, "component"));
       if (next.some((v, i) => v !== raw.dependsOn[i])) {
         raw.dependsOn = next;
         changed = true;
       }
       if (Array.isArray(raw.dispatch)) {
         for (const b of raw.dispatch) {
-          const nc = remap(b.component);
+          const nc = at(b.component, "component");
           if (nc !== b.component) {
             b.component = nc;
             changed = true;
@@ -22259,7 +22415,7 @@ function rewriteRefsInDir(specsDir, renameMap, excludeDir) {
       }
     } else if ("parentSystem" in raw && Array.isArray(raw.lifecycle)) {
       for (const le of raw.lifecycle) {
-        const nc = remap(le.component);
+        const nc = at(le.component, "component");
         if (nc !== le.component) {
           le.component = nc;
           changed = true;
@@ -22269,7 +22425,7 @@ function rewriteRefsInDir(specsDir, renameMap, excludeDir) {
       for (const m of raw.methods) {
         if (!Array.isArray(m.params)) continue;
         for (const p of m.params) {
-          const nt = remap(p.type);
+          const nt = at(p.type, "type");
           if (nt !== p.type) {
             p.type = nt;
             changed = true;
@@ -22280,7 +22436,7 @@ function rewriteRefsInDir(specsDir, renameMap, excludeDir) {
       for (const m of raw.methods) {
         if (!Array.isArray(m.narrative)) continue;
         for (const step of m.narrative) {
-          const nt = remap(step.targetComponent);
+          const nt = at(step.targetComponent, "component");
           if (nt !== step.targetComponent) {
             step.targetComponent = nt;
             changed = true;
@@ -22289,7 +22445,7 @@ function rewriteRefsInDir(specsDir, renameMap, excludeDir) {
       }
     } else if ("kind" in raw && Array.isArray(raw.fields)) {
       for (const f of raw.fields) {
-        const nt = remap(f.type);
+        const nt = at(f.type, "type");
         if (nt !== f.type) {
           f.type = nt;
           changed = true;
@@ -22885,18 +23041,29 @@ function discardStagingDir(stagingDir) {
   } catch {
   }
 }
-function exportSpecTree(includeDerived) {
+function exportSpecTree(includeDerived, allowPartial) {
   const system = loadSystemSpec();
   if (!system) {
     throw new Error("no spec tree to export at this project root");
   }
-  const chained = listChainedRoots();
+  const inspection = inspectChainedRoots();
   const root = getProjectRoot();
-  const candidates = [
-    { relativePath: ".", waiDir: aiPathsAt(root).root() },
-    ...chained.map((rel2) => ({ relativePath: rel2, waiDir: aiPathsAt(path22.resolve(root, rel2)).root() }))
-  ];
-  const roots = candidates.filter((source) => pathExists(source.waiDir));
+  const skipped = [...inspection.skipped];
+  const roots = [{ relativePath: ".", waiDir: aiPathsAt(root).root() }];
+  for (const rel2 of inspection.roots) {
+    const waiDir = aiPathsAt(path22.resolve(root, rel2)).root();
+    if (pathExists(waiDir)) {
+      roots.push({ relativePath: rel2, waiDir });
+    } else {
+      skipped.push({ mount: rel2, projectPath: rel2, reason: "no-spec-tree" });
+    }
+  }
+  if (skipped.length > 0 && !allowPartial) {
+    const detail = skipped.map((s) => `${s.mount} (${s.reason})`).join(", ");
+    throw new Error(
+      `cannot export the whole spec tree \u2014 skipped: ${detail}. Pass allowPartial to export the rest anyway.`
+    );
+  }
   const stateId = computeStateId();
   const built = buildTreeArchive2(roots, system.name, stateId.digest, includeDerived);
   const result = {
@@ -22905,7 +23072,8 @@ function exportSpecTree(includeDerived) {
     projectName: built.manifest.projectName,
     roots: built.manifest.roots,
     fileCount: built.fileCount,
-    stateId: stateId.digest
+    stateId: stateId.digest,
+    skipped
   };
   return result;
 }
@@ -23426,6 +23594,7 @@ init_yaml();
   buildRuleContext,
   buildServerInstructions,
   buildTreeArchive,
+  canonicalize,
   captureApprovedSpecs,
   checkSkillFreshness,
   clearLoaderIssues,
@@ -23436,7 +23605,6 @@ init_yaml();
   composeVariantGuidance,
   computeGateStateId,
   computePackDigest,
-  computeParentStateId,
   computeStateId,
   computeStateIdAt,
   contextDir,
@@ -23513,6 +23681,7 @@ init_yaml();
   hashGateState,
   importSpecTree,
   importSurface,
+  inspectChainedRoots,
   inspectTreeArchive,
   installPackFromDirectory,
   internalizeSubsystem,
@@ -23591,6 +23760,7 @@ init_yaml();
   readResource,
   readSkillResource,
   readYamlFile,
+  rebaseReference,
   registerExporter,
   removeFreeStandingDomain,
   removeSnapshot,