@wairon/cli 5.1.1-dev.10 → 5.1.1-dev.11

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.10";
+    WAIRON_VERSION = "5.1.1-dev.11";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     ARCHITECT_AGENT_ID = "agent-architect";
     ARCHITECT_TEMPLATE_ID = "architect";
@@ -186,11 +186,13 @@ __export(fs_exports, {
   fromProjectRoot: () => fromProjectRoot,
   getProjectRoot: () => getProjectRoot,
   getProjectRootOverride: () => getProjectRootOverride,
+  getRequestParentReach: () => getRequestParentReach,
   getRequestProjectRoot: () => getRequestProjectRoot,
   listFiles: () => listFiles,
   listFilesRecursive: () => listFilesRecursive,
   pathExists: () => pathExists,
   readFileOrNull: () => readFileOrNull,
+  runWithProjectBinding: () => runWithProjectBinding,
   runWithProjectRoot: () => runWithProjectRoot,
   setProjectRoot: () => setProjectRoot,
   writeFile: () => writeFile,
@@ -241,10 +243,21 @@ function listFilesRecursive(dirPath, ext) {
   return files;
 }
 function runWithProjectRoot(dir, fn) {
-  return requestRootStore.run(path4.resolve(dir), fn);
+  return requestRootStore.run({ ...requestRootStore.getStore(), root: path4.resolve(dir) }, fn);
+}
+function runWithProjectBinding(dir, reach, fn) {
+  return requestRootStore.run(
+    { root: path4.resolve(dir), topRoot: path4.resolve(reach.topRoot), parentReach: reach.parentReach },
+    fn
+  );
 }
 function getRequestProjectRoot() {
-  return requestRootStore.getStore() ?? null;
+  return requestRootStore.getStore()?.root ?? null;
+}
+function getRequestParentReach() {
+  const scope = requestRootStore.getStore();
+  if (!scope || scope.parentReach === void 0) return null;
+  return { topRoot: scope.topRoot, parentReach: scope.parentReach };
 }
 function setProjectRoot(dir) {
   projectRootOverride = dir === null ? null : path4.resolve(dir);
@@ -269,7 +282,7 @@ function findSystemRoot(startDir) {
   }
 }
 function getProjectRoot() {
-  const scoped = requestRootStore.getStore();
+  const scoped = requestRootStore.getStore()?.root;
   if (scoped) return scoped;
   if (projectRootOverride) return projectRootOverride;
   const systemRoot = findSystemRoot(process.cwd());
@@ -3534,733 +3547,6 @@ var init_type_references = __esm({
   }
 });
 
-// src/utils/filenames.ts
-function safeFilenamePart(value) {
-  return value.replace(/[^a-zA-Z0-9._-]/g, "-");
-}
-var init_filenames = __esm({
-  "src/utils/filenames.ts"() {
-    "use strict";
-  }
-});
-
-// src/core/openapi.ts
-function schemaFor(typeRef, closureIds) {
-  const trimmed = typeRef.trim().replace(/^promise\s*<(.+)>$/i, "$1").trim();
-  const arrayMatch = /^(.+)\[\]$/.exec(trimmed);
-  if (arrayMatch) {
-    return { type: "array", items: schemaFor(arrayMatch[1], closureIds) };
-  }
-  const lower = trimmed.toLowerCase();
-  if (lower in PRIMITIVES) {
-    const p = PRIMITIVES[lower];
-    return p.type ? { ...p } : {};
-  }
-  const local = trimmed.split(/::|\./).pop().toLowerCase().replace(/[^a-z0-9_-]/g, "");
-  const hit = [...closureIds].find((id) => id.toLowerCase() === local);
-  if (hit) return { $ref: `#/components/schemas/${hit}` };
-  return { type: "object", description: `Unresolved type: ${trimmed}` };
-}
-function operationFor(method2, closureIds) {
-  const endpoint = method2.endpoint;
-  const httpVerb = endpoint && endpoint.transport === "HTTP" ? endpoint.method.toLowerCase() : "post";
-  const bodyVerbs = /* @__PURE__ */ new Set(["post", "put", "patch"]);
-  const params = method2.params ?? [];
-  const op = {
-    operationId: method2.name,
-    summary: method2.description,
-    responses: {
-      "200": {
-        description: method2.returns || "Success",
-        ...method2.returns && method2.returns.toLowerCase() !== "void" ? { content: { "application/json": { schema: schemaFor(method2.returns, closureIds) } } } : {}
-      }
-    }
-  };
-  if (method2.guarantees?.length) op["x-wairon-guarantees"] = method2.guarantees;
-  if (method2.effect) op["x-wairon-effect"] = method2.effect;
-  if (method2.ext && Object.keys(method2.ext).length) op["x-wairon-ext"] = method2.ext;
-  if (params.length) {
-    if (bodyVerbs.has(httpVerb)) {
-      op.requestBody = {
-        required: true,
-        content: {
-          "application/json": {
-            schema: {
-              type: "object",
-              properties: Object.fromEntries(params.map((p) => [p.name, schemaFor(p.type, closureIds)])),
-              required: params.filter((p) => !p.optional).map((p) => p.name)
-            }
-          }
-        }
-      };
-    } else {
-      op.parameters = params.map((p) => ({
-        name: p.name,
-        in: "query",
-        required: !p.optional,
-        ...p.description ? { description: p.description } : {},
-        schema: schemaFor(p.type, closureIds)
-      }));
-    }
-  }
-  return op;
-}
-function securitySchemeObject(auth) {
-  if (auth.scheme === "none") return null;
-  const desc = auth.description ? { description: auth.description } : {};
-  switch (auth.scheme) {
-    case "apiKey":
-      return { type: "apiKey", in: auth.in ?? "header", name: auth.name ?? "X-API-Key", ...desc };
-    case "bearer":
-      return { type: "http", scheme: "bearer", ...auth.bearerFormat ? { bearerFormat: auth.bearerFormat } : {}, ...desc };
-    case "basic":
-      return { type: "http", scheme: "basic", ...desc };
-    case "oauth2": {
-      const flow = { scopes: Object.fromEntries((auth.scopes ?? []).map((s) => [s.name, s.description])) };
-      if (auth.authorizationUrl) flow.authorizationUrl = auth.authorizationUrl;
-      if (auth.tokenUrl) flow.tokenUrl = auth.tokenUrl;
-      if (auth.refreshUrl) flow.refreshUrl = auth.refreshUrl;
-      return { type: "oauth2", flows: { [auth.flow ?? "authorizationCode"]: flow }, ...desc };
-    }
-    case "openIdConnect":
-      return { type: "openIdConnect", openIdConnectUrl: auth.openIdConnectUrl ?? "", ...desc };
-    case "custom":
-      return { type: "apiKey", in: auth.in ?? "header", name: auth.name ?? "Authorization", description: auth.description ?? auth.example ?? "Custom authentication scheme." };
-    default:
-      return null;
-  }
-}
-function schemeBaseName(scheme) {
-  return { apiKey: "ApiKeyAuth", bearer: "BearerAuth", basic: "BasicAuth", oauth2: "OAuth2", openIdConnect: "OpenIdConnect", custom: "CustomAuth" }[scheme] ?? "Auth";
-}
-function buildSecurity(entries) {
-  const schemes = {};
-  const nameByContent = /* @__PURE__ */ new Map();
-  const securityByEntry = /* @__PURE__ */ new Map();
-  for (const entry of entries) {
-    if (!entry.auth) continue;
-    const obj = securitySchemeObject(entry.auth);
-    if (!obj) continue;
-    const content = JSON.stringify(obj);
-    let name = nameByContent.get(content);
-    if (!name) {
-      name = schemeBaseName(entry.auth.scheme);
-      for (let n = 2; schemes[name]; n++) name = schemeBaseName(entry.auth.scheme) + n;
-      schemes[name] = obj;
-      nameByContent.set(content, name);
-    }
-    const scopeNames = entry.auth.scheme === "oauth2" ? (entry.auth.scopes ?? []).map((s) => s.name) : [];
-    securityByEntry.set(entry.id, { [name]: scopeNames });
-  }
-  return { schemes, securityByEntry };
-}
-function httpEntriesOf(snapshot) {
-  return snapshot.interfaces.filter((e) => e.type === "REST" || e.methods.some((m) => m.endpoint?.transport === "HTTP"));
-}
-function renderDoc(snapshot, entries, closureIds, opts = {}) {
-  const { schemes, securityByEntry } = buildSecurity(entries);
-  const paths = {};
-  for (const entry of entries) {
-    const security = securityByEntry.get(entry.id);
-    for (const method2 of entry.methods) {
-      const endpoint = method2.endpoint;
-      if (!endpoint || endpoint.transport !== "HTTP") continue;
-      const p = endpoint.path.startsWith("/") ? endpoint.path : `/${endpoint.path}`;
-      paths[p] = paths[p] ?? {};
-      paths[p][endpoint.method.toLowerCase()] = {
-        tags: [entry.id],
-        ...operationFor(method2, closureIds),
-        ...security ? { security: [security] } : {}
-      };
-    }
-  }
-  const schemas = {};
-  for (const t of snapshot.types) {
-    schemas[t.id] = {
-      type: "object",
-      title: t.name,
-      properties: Object.fromEntries(t.fields.map((f) => [f.name, schemaFor(f.type, closureIds)])),
-      required: t.fields.filter((f) => !f.optional).map((f) => f.name)
-    };
-  }
-  const components = {};
-  if (Object.keys(schemas).length) components.schemas = schemas;
-  if (Object.keys(schemes).length) components.securitySchemes = schemes;
-  const basePaths = [...new Set(entries.map((e) => e.basePath).filter((b) => !!b))];
-  const servers = opts.servers && basePaths.length === 1 ? [{ url: basePaths[0] }] : void 0;
-  return {
-    openapi: "3.1.0",
-    info: {
-      title: opts.title ?? snapshot.projectName,
-      version: snapshot.version ?? "0.0.0",
-      ...snapshot.stateId ? { "x-wairon-state-id": snapshot.stateId } : {},
-      "x-wairon-origin": snapshot.origin,
-      "x-wairon-generated-at": snapshot.generatedAt
-    },
-    ...servers ? { servers } : {},
-    paths,
-    ...Object.keys(components).length ? { components } : {}
-  };
-}
-function toOpenApiSet(snapshot) {
-  const closureIds = new Set(snapshot.types.map((t) => t.id));
-  const byPortal = /* @__PURE__ */ new Map();
-  const order = [];
-  for (const entry of httpEntriesOf(snapshot)) {
-    if (!byPortal.has(entry.component)) {
-      byPortal.set(entry.component, []);
-      order.push(entry.component);
-    }
-    byPortal.get(entry.component).push(entry);
-  }
-  return order.map((portalId) => {
-    const entries = byPortal.get(portalId);
-    const name = entries[0]?.name ?? portalId;
-    return { portalId, name, document: JSON.stringify(renderDoc(snapshot, entries, closureIds, { title: name, servers: true }), null, 2) };
-  });
-}
-function isOpenApiDocument(body) {
-  try {
-    const parsed = yaml2.load(body);
-    return !!parsed && typeof parsed === "object" && typeof parsed.openapi === "string";
-  } catch {
-    return false;
-  }
-}
-function typeRefFromSchema(schema) {
-  if (!schema) return "json";
-  const ref = schema.$ref;
-  if (typeof ref === "string") return ref.split("/").pop() ?? "json";
-  if (schema.type === "array") {
-    return `${typeRefFromSchema(schema.items)}[]`;
-  }
-  const t = schema.type;
-  if (t === "integer") return "int";
-  if (typeof t === "string" && t !== "object") return t;
-  return "json";
-}
-function authFromSecurityScheme(scheme) {
-  const desc = typeof scheme.description === "string" ? { description: scheme.description } : {};
-  if (scheme.type === "apiKey") {
-    return {
-      scheme: "apiKey",
-      ...scheme.in === "header" || scheme.in === "query" || scheme.in === "cookie" ? { in: scheme.in } : {},
-      ...typeof scheme.name === "string" ? { name: scheme.name } : {},
-      ...desc
-    };
-  }
-  if (scheme.type === "http") {
-    if (scheme.scheme === "bearer") return { scheme: "bearer", ...typeof scheme.bearerFormat === "string" ? { bearerFormat: scheme.bearerFormat } : {}, ...desc };
-    if (scheme.scheme === "basic") return { scheme: "basic", ...desc };
-  }
-  if (scheme.type === "oauth2") {
-    const flows = scheme.flows ?? {};
-    const flowKey = Object.keys(flows)[0];
-    const f = flows[flowKey] ?? {};
-    return {
-      scheme: "oauth2",
-      ...flowKey === "authorizationCode" || flowKey === "clientCredentials" || flowKey === "implicit" || flowKey === "password" ? { flow: flowKey } : {},
-      ...typeof f.authorizationUrl === "string" ? { authorizationUrl: f.authorizationUrl } : {},
-      ...typeof f.tokenUrl === "string" ? { tokenUrl: f.tokenUrl } : {},
-      ...typeof f.refreshUrl === "string" ? { refreshUrl: f.refreshUrl } : {},
-      scopes: Object.entries(f.scopes ?? {}).map(([name, description]) => ({ name, description })),
-      ...desc
-    };
-  }
-  if (scheme.type === "openIdConnect") {
-    return { scheme: "openIdConnect", openIdConnectUrl: typeof scheme.openIdConnectUrl === "string" ? scheme.openIdConnectUrl : "", ...desc };
-  }
-  return void 0;
-}
-function fromOpenApi(document, projectName) {
-  let parsed;
-  try {
-    parsed = yaml2.load(document);
-  } catch (e) {
-    throw new Error(`Invalid surface document: not parseable as JSON/YAML (${e instanceof Error ? e.message : String(e)})`);
-  }
-  if (!parsed || typeof parsed !== "object" || typeof parsed.openapi !== "string" || typeof parsed.paths !== "object") {
-    throw new Error('Invalid surface document: missing OpenAPI "openapi"/"paths" structure.');
-  }
-  const info = parsed.info ?? {};
-  const methods = [];
-  for (const [rawPath, ops] of Object.entries(parsed.paths)) {
-    for (const [verb, opRaw] of Object.entries(ops ?? {})) {
-      if (!["get", "post", "put", "delete", "patch", "options", "head"].includes(verb)) continue;
-      const op = opRaw ?? {};
-      const name = typeof op.operationId === "string" && /^[a-zA-Z0-9_]+$/.test(op.operationId) ? op.operationId : `${verb}_${rawPath.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
-      const params = [];
-      for (const p of op.parameters ?? []) {
-        if (typeof p.name !== "string") continue;
-        params.push({
-          name: p.name,
-          type: typeRefFromSchema(p.schema),
-          ...p.required === true ? {} : { optional: true },
-          ...typeof p.description === "string" ? { description: p.description } : {}
-        });
-      }
-      const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
-      if (bodySchema) {
-        const props = bodySchema.properties ?? {};
-        const required = new Set(bodySchema.required ?? []);
-        if (Object.keys(props).length) {
-          for (const [pname, pschema] of Object.entries(props)) {
-            params.push({ name: pname, type: typeRefFromSchema(pschema), ...required.has(pname) ? {} : { optional: true } });
-          }
-        } else {
-          params.push({ name: "body", type: typeRefFromSchema(bodySchema) });
-        }
-      }
-      const okResponse = op.responses?.["200"] ?? op.responses?.["201"];
-      const responseSchema = okResponse?.content?.["application/json"]?.schema;
-      const returns = responseSchema ? typeRefFromSchema(responseSchema) : "void";
-      const rawGuarantees = op["x-wairon-guarantees"];
-      const guarantees = Array.isArray(rawGuarantees) ? rawGuarantees.filter((g) => typeof g === "string" && g.length > 0) : [];
-      const rawEffect = op["x-wairon-effect"];
-      const effect = rawEffect === "read" || rawEffect === "write" ? rawEffect : void 0;
-      const rawExt = op["x-wairon-ext"];
-      const ext = rawExt && typeof rawExt === "object" && !Array.isArray(rawExt) ? rawExt : void 0;
-      methods.push({
-        name,
-        description: typeof op.summary === "string" ? op.summary : typeof op.description === "string" ? op.description : name,
-        signature: `${name}(${params.map((p) => `${p.name}: ${p.type}`).join(", ")}): ${returns}`,
-        returns,
-        params,
-        endpoint: { transport: "HTTP", method: verb.toUpperCase(), path: rawPath },
-        ...guarantees.length ? { guarantees } : {},
-        ...effect ? { effect } : {},
-        ...ext ? { ext } : {}
-      });
-    }
-  }
-  const types = [];
-  const schemas = parsed.components?.schemas ?? {};
-  for (const [id, schema] of Object.entries(schemas)) {
-    const props = schema.properties ?? {};
-    const required = new Set(schema.required ?? []);
-    types.push({
-      id,
-      name: typeof schema.title === "string" ? schema.title : id,
-      kind: "value-object",
-      fields: Object.entries(props).map(([fname, fschema]) => ({
-        name: fname,
-        type: typeRefFromSchema(fschema),
-        ...required.has(fname) ? {} : { optional: true }
-      }))
-    });
-  }
-  const securitySchemes = parsed.components?.securitySchemes ?? {};
-  const firstScheme = Object.values(securitySchemes)[0];
-  const importedAuth = firstScheme ? authFromSecurityScheme(firstScheme) : void 0;
-  const entry = {
-    id: `${projectName}-api`,
-    name: typeof info.title === "string" ? info.title : projectName,
-    audience: "external",
-    type: "REST",
-    component: `${projectName}-api`,
-    methods,
-    details: typeof info.description === "string" ? info.description : `Imported OpenAPI surface of ${projectName}.`,
-    ...typeof info.version === "string" ? { version: info.version } : {},
-    ...importedAuth ? { auth: importedAuth } : {}
-  };
-  return SurfaceSnapshotSchema.parse({
-    projectName,
-    origin: "authored",
-    ...typeof info.version === "string" ? { version: info.version } : {},
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    interfaces: [entry],
-    types
-  });
-}
-var yaml2, PRIMITIVES;
-var init_openapi = __esm({
-  "src/core/openapi.ts"() {
-    "use strict";
-    yaml2 = __toESM(require("js-yaml"));
-    init_models();
-    PRIMITIVES = {
-      string: { type: "string" },
-      number: { type: "number" },
-      float: { type: "number" },
-      decimal: { type: "number" },
-      int: { type: "integer" },
-      integer: { type: "integer" },
-      boolean: { type: "boolean" },
-      bool: { type: "boolean" },
-      date: { type: "string", format: "date-time" },
-      datetime: { type: "string", format: "date-time" },
-      uuid: { type: "string", format: "uuid" },
-      json: { type: "object" },
-      object: { type: "object" },
-      any: {},
-      unknown: {},
-      void: {}
-    };
-  }
-});
-
-// src/core/surfaces.ts
-function surfacesDir(rootDir) {
-  return path11.join(rootDir, ".wai", SURFACES_DIRNAME);
-}
-function audienceRank(audience) {
-  const idx = SURFACE_AUDIENCES.indexOf(audience ?? "instance");
-  return idx === -1 ? SURFACE_AUDIENCES.indexOf("instance") : idx;
-}
-function stateIdString() {
-  const s = computeStateId();
-  return `${s.algorithm}:${s.digest}`;
-}
-function computeTypeClosure(entries, types) {
-  const included = /* @__PURE__ */ new Map();
-  const queue = [];
-  const enqueueRef = (ref) => {
-    if (BUILTIN_TYPES.has(ref.toLowerCase())) return;
-    for (const spec of types) {
-      const qualifiedId2 = spec.subsystem && !spec.id.startsWith(`${spec.subsystem}::`) ? `${spec.subsystem}::${spec.id}` : spec.id;
-      if (matchTypeRef(ref, qualifiedId2) && !included.has(spec.id)) {
-        included.set(spec.id, spec);
-        queue.push(spec.id);
-      }
-    }
-  };
-  for (const entry of entries) {
-    for (const m of entry.methods) {
-      for (const ref of methodTypeRefs(m)) enqueueRef(ref);
-    }
-  }
-  while (queue.length) {
-    const spec = included.get(queue.shift());
-    for (const field of spec.fields) {
-      for (const ref of extractTypeIdentifiers(field.type)) enqueueRef(ref);
-    }
-  }
-  return [...included.values()].map((t) => ({
-    id: t.id,
-    name: t.name,
-    kind: t.kind,
-    fields: t.fields.map((f) => ({
-      name: f.name,
-      type: f.type,
-      ...f.description ? { description: f.description } : {},
-      ...f.optional ? { optional: true } : {}
-    }))
-  }));
-}
-function projectOwnSurface(maxAudience) {
-  const system = loadSystemSpec();
-  if (!system) {
-    throw new Error("Cannot project a surface: the L0 system spec is missing.");
-  }
-  const subsystems = loadSubsystemSpecs();
-  const components = loadComponentSpecs();
-  const interfaces = loadInterfaceSpecs();
-  const types = loadTypeSpecs();
-  const floor = audienceRank(maxAudience);
-  const rawEntries = system.publicInterfaces ?? [];
-  const entries = [];
-  for (const raw of rawEntries) {
-    const audience = raw.audience ?? "instance";
-    if (audienceRank(audience) < floor) continue;
-    if (!raw.component) continue;
-    const comp = components.find((c) => c.id === raw.component);
-    if (!comp) continue;
-    const compInterfaces = interfaces.filter((i) => i.component === comp.id && (!raw.interface || i.id === raw.interface));
-    const methods = compInterfaces.flatMap((i) => i.methods);
-    const subsystemType = subsystems.find((s) => s.id === comp.subsystem)?.publicInterfaces.find((pi) => pi.component === comp.id)?.type;
-    entries.push({
-      id: raw.id ?? raw.interface ?? comp.id,
-      name: raw.name ?? comp.name,
-      audience,
-      type: raw.type ?? subsystemType ?? "Custom",
-      component: comp.id,
-      methods,
-      ...comp.dispatch && comp.dispatch.length ? { dispatch: comp.dispatch } : {},
-      // Project the backing Portal's auth + basePath so the codec can emit
-      // OpenAPI security + per-portal servers self-contained from the snapshot.
-      ...comp.auth && comp.auth.scheme !== "none" ? { auth: comp.auth } : {},
-      ...comp.basePath ? { basePath: comp.basePath } : {},
-      details: raw.details ?? "",
-      ...raw.version ? { version: raw.version } : {},
-      ...raw.stability ? { stability: raw.stability } : {}
-    });
-  }
-  return SurfaceSnapshotSchema.parse({
-    projectName: system.name,
-    origin: "generated",
-    stateId: stateIdString(),
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    interfaces: entries,
-    types: computeTypeClosure(entries, types)
-  });
-}
-function projectChildSurface() {
-  return projectOwnSurface("project");
-}
-function localName(id) {
-  return id.split("::").pop();
-}
-function projectSubsystemSurface(subsystemId) {
-  const system = loadSystemSpec();
-  if (!system) {
-    throw new Error("Cannot project a subsystem surface: the L0 system spec is missing.");
-  }
-  const subsystems = loadSubsystemSpecs();
-  const target = subsystems.find((s) => s.id === subsystemId);
-  if (!target) {
-    throw new Error(`Cannot project a subsystem surface: subsystem "${subsystemId}" does not exist.`);
-  }
-  const components = loadComponentSpecs();
-  const interfaces = loadInterfaceSpecs();
-  const types = loadTypeSpecs();
-  const entries = [];
-  const unprojectable = [];
-  for (const pub of target.publicInterfaces ?? []) {
-    if (!pub.component) continue;
-    const comp = components.find((c) => c.id === pub.component || c.id === `${subsystemId}::${pub.component}`);
-    if (!comp) continue;
-    if (!CROSS_BOUNDARY_TARGETS.has(comp.componentType)) {
-      unprojectable.push({ component: pub.component, componentType: comp.componentType });
-      continue;
-    }
-    const compInterfaces = interfaces.filter((i) => i.component === comp.id && (!pub.interface || i.id === pub.interface || i.id === `${subsystemId}::${pub.interface}`));
-    const methods = compInterfaces.flatMap((i) => i.methods);
-    entries.push({
-      id: localName(pub.interface ?? comp.id),
-      name: comp.name,
-      // Family ceiling: a sibling surface is consumable by the system family only.
-      audience: "project",
-      type: pub.type ?? "Custom",
-      // The snapshot carries the LOCAL portal name — consumers resolve cross-tree
-      // refs by their final segment.
-      component: localName(comp.id),
-      methods,
-      ...comp.dispatch && comp.dispatch.length ? { dispatch: comp.dispatch } : {},
-      // Project the backing component's auth + basePath so the codec can emit
-      // OpenAPI security + per-portal servers self-contained from the snapshot.
-      ...comp.auth && comp.auth.scheme !== "none" ? { auth: comp.auth } : {},
-      ...comp.basePath ? { basePath: comp.basePath } : {},
-      details: pub.details ?? ""
-    });
-  }
-  for (const skipped of unprojectable) {
-    console.error(
-      `[surfaces] skipped "${subsystemId}::${skipped.component}": a published ${skipped.componentType} can never serve a cross-boundary caller, so it stays out of every chained child's sibling surface \u2014 publish this surface through a Portal, a Gateway, or an Observer (for events).`
-    );
-  }
-  return SurfaceSnapshotSchema.parse({
-    projectName: `${system.name}::${subsystemId}`,
-    origin: "generated",
-    stateId: stateIdString(),
-    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    interfaces: entries,
-    types: computeTypeClosure(entries, types)
-  });
-}
-function listSnapshots(rootDir = getProjectRoot()) {
-  const dir = surfacesDir(rootDir);
-  if (!fs9.existsSync(dir)) return [];
-  const out = [];
-  for (const file of fs9.readdirSync(dir)) {
-    if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
-    try {
-      out.push(SurfaceSnapshotSchema.parse(readYamlFile(path11.join(dir, file))));
-    } catch {
-    }
-  }
-  return out;
-}
-function getSnapshot(projectName, rootDir = getProjectRoot()) {
-  return listSnapshots(rootDir).find((s) => s.projectName === projectName) ?? null;
-}
-function snapshotFilename(projectName) {
-  return `${safeFilenamePart(projectName)}.yaml`;
-}
-function writeSnapshotIfChanged(snapshot, rootDir) {
-  const dir = surfacesDir(rootDir);
-  fs9.mkdirSync(dir, { recursive: true });
-  const p = path11.join(dir, snapshotFilename(snapshot.projectName));
-  const next = SurfaceSnapshotSchema.parse(snapshot);
-  if (fs9.existsSync(p)) {
-    try {
-      const existing = SurfaceSnapshotSchema.parse(readYamlFile(p));
-      if (surfaceContentKey(existing) === surfaceContentKey(next)) {
-        return { path: p, changed: false };
-      }
-    } catch {
-    }
-  }
-  writeYamlFile(p, next);
-  return { path: p, changed: true };
-}
-function saveSnapshot(snapshot, rootDir = getProjectRoot()) {
-  return writeSnapshotIfChanged(snapshot, rootDir).path;
-}
-function loadSurfaceSnapshots() {
-  return listSnapshots();
-}
-function selectPortalSpec(renderedSet, portalId) {
-  const hit = renderedSet.find((spec) => spec.portalId === portalId);
-  if (!hit) {
-    const known = renderedSet.map((s) => s.portalId).join(", ");
-    throw new Error(`Unknown portal "${portalId}" \u2014 this surface renders: ${known || "(no portals)"}.`);
-  }
-  return [hit];
-}
-function perPortalPath(resolvedOut, portalId) {
-  const ext = path11.extname(resolvedOut);
-  const stem2 = ext ? resolvedOut.slice(0, -ext.length) : resolvedOut;
-  return `${stem2}.${safeFilenamePart(portalId)}${ext}`;
-}
-function writeSurfaceFile(outPath, snapshot, renderedSet) {
-  const resolved = path11.resolve(outPath);
-  fs9.mkdirSync(path11.dirname(resolved), { recursive: true });
-  if (!renderedSet || renderedSet.length === 0) {
-    writeYamlFile(resolved, snapshot);
-    return [resolved];
-  }
-  if (renderedSet.length === 1) {
-    fs9.writeFileSync(resolved, renderedSet[0].document);
-    return [resolved];
-  }
-  return renderedSet.map((spec) => {
-    const target = perPortalPath(resolved, spec.portalId);
-    fs9.writeFileSync(target, spec.document);
-    return target;
-  });
-}
-function exportResult(snapshot, renderedSet, writtenPaths) {
-  const rendered = renderedSet?.length === 1 ? renderedSet[0].document : void 0;
-  return {
-    snapshot,
-    ...rendered !== void 0 ? { rendered } : {},
-    ...renderedSet ? { renderedSet } : {},
-    ...writtenPaths.length === 1 ? { writtenTo: writtenPaths[0] } : {},
-    ...writtenPaths.length ? { writtenPaths } : {}
-  };
-}
-function exportSurface(maxAudience, format, outPath, portalId) {
-  const snapshot = projectOwnSurface(maxAudience);
-  let renderedSet = format === "openapi" ? toOpenApiSet(snapshot) : void 0;
-  if (renderedSet && portalId) renderedSet = selectPortalSpec(renderedSet, portalId);
-  const writtenPaths = outPath ? writeSurfaceFile(outPath, snapshot, renderedSet) : [];
-  return exportResult(snapshot, renderedSet, writtenPaths);
-}
-function importSurface(sourcePath, origin) {
-  const resolved = path11.resolve(sourcePath);
-  if (!fs9.existsSync(resolved)) {
-    throw new Error(`Surface document not found: ${resolved}`);
-  }
-  const body = fs9.readFileSync(resolved, "utf8");
-  let snapshot;
-  if (isOpenApiDocument(body)) {
-    const projectName = path11.basename(resolved).replace(/\.(json|ya?ml)$/i, "");
-    snapshot = fromOpenApi(body, projectName);
-    snapshot = { ...snapshot, origin };
-  } else {
-    snapshot = SurfaceSnapshotSchema.parse(readYamlFile(resolved));
-    snapshot = { ...snapshot, origin };
-  }
-  saveSnapshot(snapshot);
-  return snapshot;
-}
-function generateChildSnapshots(rootDir = getProjectRoot()) {
-  const topLevel = loadSubsystemSpecs().filter((s) => !s.id.includes("::"));
-  const children = topLevel.filter((s) => s.projectPath);
-  if (!children.length) return [];
-  const familySnapshot = projectChildSurface();
-  const siblingSnapshots = /* @__PURE__ */ new Map();
-  const siblingSurface = (subsystemId) => {
-    let snap = siblingSnapshots.get(subsystemId);
-    if (!snap) {
-      snap = projectSubsystemSurface(subsystemId);
-      siblingSnapshots.set(subsystemId, snap);
-    }
-    return snap;
-  };
-  const written = [];
-  const record2 = (r) => {
-    if (r.changed) written.push(r.path);
-  };
-  for (const child of children) {
-    const childDir = path11.resolve(rootDir, child.projectPath);
-    if (!fs9.existsSync(childDir)) continue;
-    record2(writeSnapshotIfChanged(familySnapshot, childDir));
-    for (const sibling of topLevel) {
-      if (sibling.id === child.id) continue;
-      record2(writeSnapshotIfChanged(siblingSurface(sibling.id), childDir));
-    }
-  }
-  return written;
-}
-function computeParentStateId(parentRoot) {
-  return computeStateIdAt(parentRoot);
-}
-function listExternalInterfaces() {
-  const snapshots = listSnapshots();
-  const chainingParent = resolveChainingParent();
-  const parentStateId = chainingParent ? computeParentStateId(chainingParent.parentRoot) : 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";
-    return {
-      projectName: snapshot.projectName,
-      origin: snapshot.origin,
-      sourceKind,
-      generatedAt: snapshot.generatedAt,
-      ...snapshot.stateId ? { stateId: snapshot.stateId } : {},
-      ...snapshot.version ? { version: snapshot.version } : {},
-      freshness,
-      interfaceIds: snapshot.interfaces.map((e) => e.id)
-    };
-  });
-}
-function surfaceContentKey(snapshot) {
-  const { stateId, generatedAt, origin, ...content } = snapshot;
-  return JSON.stringify(content);
-}
-function checkChildSurfaceFreshness(rootDir = getProjectRoot()) {
-  const system = loadSystemSpec();
-  if (!system) return [];
-  const children = loadSubsystemSpecs().filter((s) => s.projectPath && !s.id.includes("::"));
-  if (!children.length) return [];
-  const current2 = surfaceContentKey(projectChildSurface());
-  const issues = [];
-  for (const child of children) {
-    const childDir = path11.resolve(rootDir, child.projectPath);
-    const held = getSnapshot(system.name, childDir);
-    if (!held || held.origin !== "generated") continue;
-    if (surfaceContentKey(held) !== current2) {
-      issues.push({
-        severity: "warning",
-        code: "SURFACE_STALE",
-        message: `Chained child "${child.id}" holds a parent surface snapshot whose contracts no longer match the current tree \u2014 rerun \`wairon surface generate-children\` so the child validates against the current surface.`,
-        specId: child.id
-      });
-    }
-  }
-  return issues;
-}
-var fs9, path11, SURFACES_DIRNAME, CROSS_BOUNDARY_TARGETS;
-var init_surfaces = __esm({
-  "src/core/surfaces.ts"() {
-    "use strict";
-    fs9 = __toESM(require("fs"));
-    path11 = __toESM(require("path"));
-    init_fs();
-    init_yaml();
-    init_filenames();
-    init_models();
-    init_specs2();
-    init_statehash();
-    init_type_analysis();
-    init_openapi();
-    SURFACES_DIRNAME = "surfaces";
-    CROSS_BOUNDARY_TARGETS = /* @__PURE__ */ new Set(["Portal", "Gateway", "Observer"]);
-  }
-});
-
 // src/core/rules/namespace.ts
 function isExternalNamespaceRef(ctx, ref) {
   if (ref.startsWith("::") || ref.startsWith("super::")) return true;
@@ -4268,21 +3554,36 @@ function isExternalNamespaceRef(ctx, ref) {
   if (sep9 === -1) return false;
   return !ctx.subsystemIds.has(ref.slice(0, sep9));
 }
-function resolveSurfaceRef(ctx, ref) {
+function resolveSurfaceRef(ctx, ref, fromSubsystem) {
   const local = ref.split("::").filter((seg) => seg && seg !== "super").pop();
   if (!local) return null;
-  for (const snapshot of ctx.surfaceSnapshots) {
-    const entry = snapshot.interfaces.find((e) => e.component === local || e.id === local);
-    if (entry) return { snapshot, entry };
+  const mountPools = fromSubsystem ? enclosingMounts(ctx, fromSubsystem).reverse().map((ns) => ctx.mountSurfaceSnapshots.find((m) => m.namespace === ns)?.snapshots ?? []) : [];
+  for (const pool of [...mountPools, ctx.surfaceSnapshots]) {
+    for (const snapshot of pool) {
+      const entry = snapshot.interfaces.find((e) => e.component === local || e.id === local);
+      if (entry) return { snapshot, entry };
+    }
   }
   return null;
 }
-var roundtripRule, surfaceFreshnessRule, namespaceHygieneRule;
+function enclosingMounts(ctx, subsystemId) {
+  const mounts = [];
+  let prefix = "";
+  for (const segment of subsystemId.split("::")) {
+    prefix = prefix ? `${prefix}::${segment}` : segment;
+    if (ctx.subsystems.some((s) => s.id === prefix && s.projectPath)) mounts.push(prefix);
+  }
+  return mounts;
+}
+function isCollapsedCrossTreeRef(ctx, ref, fromSubsystem) {
+  const nearest = enclosingMounts(ctx, fromSubsystem).pop();
+  return nearest !== void 0 && ref !== nearest && !ref.startsWith(`${nearest}::`);
+}
+var roundtripRule, namespaceHygieneRule;
 var init_namespace = __esm({
   "src/core/rules/namespace.ts"() {
     "use strict";
     init_specs2();
-    init_surfaces();
     roundtripRule = {
       name: "roundtrip-serialization",
       description: "Every loaded spec must re-serialize through the exact writer pipeline (same relativization, same schema, no I/O) \u2014 validate must predict every refusal that lock's status promotion or any later save would otherwise raise mid-write.",
@@ -4295,18 +3596,6 @@ var init_namespace = __esm({
         }
       }
     };
-    surfaceFreshnessRule = {
-      name: "surface-freshness",
-      description: "Every chained child's stored parent-surface snapshot must match the parent's CURRENT exported contracts \u2014 a drifted snapshot means the child validates standalone against a stale truth. Regenerate with `wairon surface generate-children`.",
-      codes: [
-        { code: "SURFACE_STALE", defaultSeverity: "warning", summary: "A chained child holds a parent surface snapshot whose contracts no longer match the current tree" }
-      ],
-      check(ctx) {
-        for (const issue2 of checkChildSurfaceFreshness()) {
-          ctx.addIssue("warning", "SURFACE_STALE", issue2.message, issue2.specId);
-        }
-      }
-    };
     namespaceHygieneRule = {
       name: "namespace-hygiene",
       description: 'Ids must stay resolvable in the :: namespace grammar: no id segment may be the reserved keyword "super", and a subproject-local name must not shadow a root-level subsystem id \u2014 a bare reference to a shadowed name silently anchors to the ROOT subsystem, so the local spec becomes unaddressable.',
@@ -4413,11 +3702,13 @@ var init_contracts = __esm({
                 continue;
               }
               const isCrossTreeForm = isExternalNamespaceRef(ctx, step.targetComponent);
+              const fromSubsystem = ctx.componentMap.get(contract.component)?.subsystem;
+              const isCollapsedForm = !isCrossTreeForm && fromSubsystem !== void 0 && isCollapsedCrossTreeRef(ctx, step.targetComponent, fromSubsystem);
               if (step.type === "dispatch") {
                 const dispatchTarget = ctx.componentMap.get(step.targetComponent);
                 if (!dispatchTarget) {
-                  if (isCrossTreeForm) {
-                    const resolved = resolveSurfaceRef(ctx, step.targetComponent);
+                  if (isCrossTreeForm || isCollapsedForm) {
+                    const resolved = resolveSurfaceRef(ctx, step.targetComponent, fromSubsystem);
                     if (resolved) {
                       if (step.capability && !(resolved.entry.dispatch ?? []).some((b) => b.capability === step.capability)) {
                         ctx.addIssue(
@@ -4431,10 +3722,12 @@ var init_contracts = __esm({
                       }
                       continue;
                     }
+                  }
+                  if (isCrossTreeForm) {
                     ctx.addIssue(
                       "warning",
                       "CROSS_TREE_REF_UNRESOLVED",
-                      `Method "${implMethod.name}" in implementation "${impl.id}" dispatches through cross-tree component "${step.targetComponent}" (step ${step.stepNumber}), and no surface snapshot covers it \u2014 validate from the parent project, or import/generate the producing project's surface.`,
+                      `Method "${implMethod.name}" in implementation "${impl.id}" dispatches through cross-tree component "${step.targetComponent}" (step ${step.stepNumber}), and no surface snapshot covers it \u2014 validate from the parent project, pin the family surfaces ("wairon surface pin"), or import the producing project's surface.`,
                       impl.id,
                       isDraftCtx
                     );
@@ -4474,8 +3767,8 @@ var init_contracts = __esm({
               }
               const targetComp = ctx.componentMap.get(step.targetComponent);
               if (!targetComp) {
-                if (isCrossTreeForm) {
-                  const resolved = resolveSurfaceRef(ctx, step.targetComponent);
+                if (isCrossTreeForm || isCollapsedForm) {
+                  const resolved = resolveSurfaceRef(ctx, step.targetComponent, fromSubsystem);
                   if (resolved) {
                     const surfaceMethod = resolved.entry.methods.find((m) => m.name === step.targetMethod);
                     if (!surfaceMethod) {
@@ -4504,10 +3797,12 @@ var init_contracts = __esm({
                     }
                     continue;
                   }
+                }
+                if (isCrossTreeForm) {
                   ctx.addIssue(
                     "warning",
                     "CROSS_TREE_REF_UNRESOLVED",
-                    `Method "${implMethod.name}" in implementation "${impl.id}" ${verb} cross-tree component "${step.targetComponent}" (step ${step.stepNumber}), and no surface snapshot covers it \u2014 validate from the parent project, or import/generate the producing project's surface.`,
+                    `Method "${implMethod.name}" in implementation "${impl.id}" ${verb} cross-tree component "${step.targetComponent}" (step ${step.stepNumber}), and no surface snapshot covers it \u2014 validate from the parent project, pin the family surfaces ("wairon surface pin"), or import the producing project's surface.`,
                     impl.id,
                     isDraftCtx
                   );
@@ -4995,7 +4290,7 @@ function resolveTypeScript(projectRoot2) {
     return cached.ts;
   }
   let ts = null;
-  const bases = [path12.join(projectRoot2, "package.json"), __filename];
+  const bases = [path11.join(projectRoot2, "package.json"), __filename];
   for (const base of bases) {
     try {
       const req = (0, import_module2.createRequire)(base);
@@ -5151,7 +4446,7 @@ function walkExact(ts, sourceText, fileName) {
 }
 function resolveRelativeModule(fromFile, specifier) {
   if (!specifier.startsWith(".")) return null;
-  const base = path12.resolve(path12.dirname(fromFile), specifier);
+  const base = path11.resolve(path11.dirname(fromFile), specifier);
   const candidates = [
     base,
     base.replace(/\.js$/, ".ts"),
@@ -5159,12 +4454,12 @@ function resolveRelativeModule(fromFile, specifier) {
     `${base}.ts`,
     `${base}.tsx`,
     `${base}.js`,
-    path12.join(base, "index.ts"),
-    path12.join(base, "index.js")
+    path11.join(base, "index.ts"),
+    path11.join(base, "index.js")
   ];
   for (const c of candidates) {
     try {
-      if (fs10.statSync(c).isFile()) return c;
+      if (fs9.statSync(c).isFile()) return c;
     } catch {
     }
   }
@@ -5174,12 +4469,12 @@ function chaseStarExports(ts, facts, filePath, projectRoot2, visited, exactCache
   for (const spec of facts.starExports) {
     const target = resolveRelativeModule(filePath, spec);
     if (!target || visited.has(target)) continue;
-    if (path12.relative(projectRoot2, target).startsWith("..")) continue;
+    if (path11.relative(projectRoot2, target).startsWith("..")) continue;
     visited.add(target);
     let targetFacts = exactCache.get(target);
     if (targetFacts === void 0) {
       try {
-        targetFacts = walkExact(ts, fs10.readFileSync(target, "utf8"), target);
+        targetFacts = walkExact(ts, fs9.readFileSync(target, "utf8"), target);
       } catch {
         targetFacts = null;
       }
@@ -5219,23 +4514,23 @@ function buildCodeModel(implementations, projectRoot2) {
     if (seen.has(sourcePath)) continue;
     seen.add(sourcePath);
     const empty = { declaredNames: [], anchoredNames: [], exportedNames: [], imports: [], reexports: [] };
-    if (path12.isAbsolute(sourcePath) || path12.normalize(sourcePath).split(path12.sep)[0] === "..") {
+    if (path11.isAbsolute(sourcePath) || path11.normalize(sourcePath).split(path11.sep)[0] === "..") {
       files.push({ path: sourcePath, status: "escaped", ...empty });
       continue;
     }
-    const absolute = path12.resolve(projectRoot2, sourcePath);
-    if (path12.relative(projectRoot2, absolute).startsWith("..")) {
+    const absolute = path11.resolve(projectRoot2, sourcePath);
+    if (path11.relative(projectRoot2, absolute).startsWith("..")) {
       files.push({ path: sourcePath, status: "escaped", ...empty });
       continue;
     }
     let buffer;
     try {
-      const stat = fs10.statSync(absolute);
+      const stat = fs9.statSync(absolute);
       if (!stat.isFile()) {
         files.push({ path: sourcePath, status: "missing", ...empty });
         continue;
       }
-      buffer = fs10.readFileSync(absolute);
+      buffer = fs9.readFileSync(absolute);
     } catch {
       files.push({ path: sourcePath, status: "missing", ...empty });
       continue;
@@ -5245,7 +4540,7 @@ function buildCodeModel(implementations, projectRoot2) {
       continue;
     }
     const text2 = buffer.toString("utf8");
-    const language = EXTENSION_LANGUAGE[path12.extname(sourcePath).toLowerCase()];
+    const language = EXTENSION_LANGUAGE[path11.extname(sourcePath).toLowerCase()];
     let analyzed;
     if (language === "typescript" || language === "javascript") {
       const ts = resolveTypeScript(projectRoot2);
@@ -5279,12 +4574,12 @@ function buildCodeModel(implementations, projectRoot2) {
   }
   return { files, projectRoot: projectRoot2 };
 }
-var fs10, path12, import_module2, EXTENSION_LANGUAGE, C_FAMILY_COMMENTS, JS_PATTERNS, LANGUAGE_PATTERNS, PATTERN_ANALYSIS_MAX_BYTES, IDENTIFIER_RE, STRING_RE, tsResolutionCache, TS_RESOLUTION_RETRY_MS;
+var fs9, path11, import_module2, EXTENSION_LANGUAGE, C_FAMILY_COMMENTS, JS_PATTERNS, LANGUAGE_PATTERNS, PATTERN_ANALYSIS_MAX_BYTES, IDENTIFIER_RE, STRING_RE, tsResolutionCache, TS_RESOLUTION_RETRY_MS;
 var init_source_analysis = __esm({
   "src/core/source-analysis.ts"() {
     "use strict";
-    fs10 = __toESM(require("fs"));
-    path12 = __toESM(require("path"));
+    fs9 = __toESM(require("fs"));
+    path11 = __toESM(require("path"));
     import_module2 = require("module");
     EXTENSION_LANGUAGE = {
       ".ts": "typescript",
@@ -6009,8 +5304,9 @@ var init_stereotype_deps = __esm({
           for (const depId of dependencies) {
             const depComp = ctx.componentMap.get(depId);
             if (!depComp) {
-              if (isExternalNamespaceRef(ctx, depId)) {
-                const resolved = resolveSurfaceRef(ctx, depId);
+              const external = isExternalNamespaceRef(ctx, depId);
+              if (external || isCollapsedCrossTreeRef(ctx, depId, comp.subsystem)) {
+                const resolved = resolveSurfaceRef(ctx, depId, comp.subsystem);
                 if (resolved) {
                   if (comp.componentType !== "Adapter") {
                     ctx.addIssue(
@@ -6024,14 +5320,16 @@ var init_stereotype_deps = __esm({
                   }
                   continue;
                 }
-                ctx.addIssue(
-                  "warning",
-                  "CROSS_TREE_REF_UNRESOLVED",
-                  `Component "${comp.id}" depends on cross-tree component "${depId}", and no surface snapshot covers it \u2014 validate from the parent project, or import/generate the producing project's surface.`,
-                  comp.id,
-                  isDraftCtx
-                );
-                continue;
+                if (external) {
+                  ctx.addIssue(
+                    "warning",
+                    "CROSS_TREE_REF_UNRESOLVED",
+                    `Component "${comp.id}" depends on cross-tree component "${depId}", and no surface snapshot covers it \u2014 validate from the parent project, pin the family surfaces ("wairon surface pin"), or import the producing project's surface.`,
+                    comp.id,
+                    isDraftCtx
+                  );
+                  continue;
+                }
               }
               ctx.addIssue(
                 "error",
@@ -8652,7 +7950,7 @@ var init_naming = __esm({
 // src/core/rules/integration-conformance.ts
 function resolveAgainst(mapped, fromFile, specifier) {
   if (!specifier.startsWith(".")) return null;
-  const joined = normalizePath(path13.posix.normalize(path13.posix.join(path13.posix.dirname(fromFile), specifier)));
+  const joined = normalizePath(path12.posix.normalize(path12.posix.join(path12.posix.dirname(fromFile), specifier)));
   const candidates = [
     joined,
     joined.replace(/\.js$/, ".ts"),
@@ -8668,11 +7966,11 @@ function resolveAgainst(mapped, fromFile, specifier) {
   }
   return null;
 }
-var path13, normalizePath, integrationConformanceRule;
+var path12, normalizePath, integrationConformanceRule;
 var init_integration_conformance = __esm({
   "src/core/rules/integration-conformance.ts"() {
     "use strict";
-    path13 = __toESM(require("path"));
+    path12 = __toESM(require("path"));
     init_source_analysis();
     init_conformance();
     normalizePath = normalizeSourcePath;
@@ -8876,7 +8174,7 @@ var init_hidden_state = __esm({
 // src/core/rules/dependency-conformance.ts
 function resolveAgainst2(mapped, fromFile, specifier) {
   if (!specifier.startsWith(".")) return null;
-  const joined = normalizePath2(path14.posix.normalize(path14.posix.join(path14.posix.dirname(fromFile), specifier)));
+  const joined = normalizePath2(path13.posix.normalize(path13.posix.join(path13.posix.dirname(fromFile), specifier)));
   const candidates = [
     joined,
     joined.replace(/\.js$/, ".ts"),
@@ -8892,11 +8190,11 @@ function resolveAgainst2(mapped, fromFile, specifier) {
   }
   return null;
 }
-var path14, normalizePath2, dependencyConformanceRule;
+var path13, normalizePath2, dependencyConformanceRule;
 var init_dependency_conformance = __esm({
   "src/core/rules/dependency-conformance.ts"() {
     "use strict";
-    path14 = __toESM(require("path"));
+    path13 = __toESM(require("path"));
     init_source_analysis();
     init_conformance();
     normalizePath2 = normalizeSourcePath;
@@ -9382,13 +8680,7 @@ function buildRuleContext(opts) {
     ...[...SDD_RULES, ...extensions.rules].flatMap((r) => r.codes.map((c) => c.code)),
     // Declarative assertions bring their own namespaced codes — lint.allow
     // and severity overrides treat them exactly like builtins.
-    ...extensions.assertions.map((a) => a.fullCode),
-    // Entry-point emitted codes: validateSddTree's chained-subproject pass
-    // raises these AFTER the rule run (it post-processes the aggregated issue
-    // list), so no registered rule declares them — but lint.allow validation
-    // must still recognize them as real codes.
-    "CHAINED_SUBPROJECT_CONTEXT",
-    "UNVERIFIED_EXTERNAL_REF"
+    ...extensions.assertions.map((a) => a.fullCode)
   ]);
   const addIssue = (defaultSeverity, code, message, specId, isDraftContext, surfaceResolved) => {
     if (scopeSubsystem && specId && !isSpecInScope(specId)) {
@@ -9444,6 +8736,7 @@ function buildRuleContext(opts) {
     ext: { profiles: extensions.profiles, languages: extensions.languages, patterns: extensions.patterns, guarantees: extensions.guarantees, assertions: extensions.assertions, packSelections: opts.packSelections ?? [], selectionFailures: extensions.selectionFailures ?? [] },
     variants: opts.variants ?? [],
     surfaceSnapshots: opts.surfaceSnapshots ?? [],
+    mountSurfaceSnapshots: opts.mountSurfaceSnapshots ?? [],
     codeModel: opts.codeModel ?? emptyCodeModel(),
     lintAllows,
     knownIssueCodes,
@@ -9501,7 +8794,6 @@ var init_rules = __esm({
       // explain many downstream findings, so surface them early in the list.
       namespaceHygieneRule,
       roundtripRule,
-      surfaceFreshnessRule,
       typeReferencesRule,
       contractsRule,
       // Vocabulary check right after contracts: an unknown token explains why the
@@ -9771,14 +9063,14 @@ function describeApprover(who) {
 }
 function readLockRecord() {
   try {
-    return normalizeRecord(JSON.parse(fs11.readFileSync(lockPath(), "utf8")));
+    return normalizeRecord(JSON.parse(fs10.readFileSync(lockPath(), "utf8")));
   } catch {
     return null;
   }
 }
 function readLockRecordAt(root) {
   try {
-    return normalizeRecord(JSON.parse(fs11.readFileSync(aiDirAt(root, "lock.json"), "utf8")));
+    return normalizeRecord(JSON.parse(fs10.readFileSync(aiDirAt(root, "lock.json"), "utf8")));
   } catch {
     return null;
   }
@@ -9789,10 +9081,10 @@ function normalizeRecord(raw) {
 }
 function writeLockRecord(record2) {
   const p = lockPath();
-  fs11.mkdirSync(path15.dirname(p), { recursive: true });
+  fs10.mkdirSync(path14.dirname(p), { recursive: true });
   const tmp = `${p}.tmp`;
-  fs11.writeFileSync(tmp, JSON.stringify(withSortedMaps(record2), null, 2) + "\n");
-  fs11.renameSync(tmp, p);
+  fs10.writeFileSync(tmp, JSON.stringify(withSortedMaps(record2), null, 2) + "\n");
+  fs10.renameSync(tmp, p);
 }
 function withSortedMaps(record2) {
   const sorted = (m) => {
@@ -9809,12 +9101,12 @@ function withSortedMaps(record2) {
     ...children ? { children } : {}
   };
 }
-var fs11, path15;
+var fs10, path14;
 var init_lockfile = __esm({
   "src/core/lockfile.ts"() {
     "use strict";
-    fs11 = __toESM(require("fs"));
-    path15 = __toESM(require("path"));
+    fs10 = __toESM(require("fs"));
+    path14 = __toESM(require("path"));
     init_fs();
   }
 });
@@ -10547,14 +9839,14 @@ function embedJson(value) {
 }
 function loadCytoscapeLib() {
   const candidates = [
-    path16.resolve(__dirname, "..", "templates", "canvas", "cytoscape.min.js"),
+    path15.resolve(__dirname, "..", "templates", "canvas", "cytoscape.min.js"),
     // src/core & dist/cli
-    path16.resolve(__dirname, "templates", "canvas", "cytoscape.min.js")
+    path15.resolve(__dirname, "templates", "canvas", "cytoscape.min.js")
     // dist (library entry)
   ];
   for (const p of candidates) {
-    if (fs12.existsSync(p)) {
-      return fs12.readFileSync(p, "utf-8").replace(/<\/script/gi, "<\\/script");
+    if (fs11.existsSync(p)) {
+      return fs11.readFileSync(p, "utf-8").replace(/<\/script/gi, "<\\/script");
     }
   }
   throw new Error("Vendored cytoscape bundle not found (templates/canvas/cytoscape.min.js) \u2014 the wairon installation is incomplete.");
@@ -10566,12 +9858,12 @@ function renderCanvasHtml(model) {
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-var fs12, path16, CANVAS_TEMPLATE;
+var fs11, path15, CANVAS_TEMPLATE;
 var init_canvas = __esm({
   "src/core/canvas.ts"() {
     "use strict";
-    fs12 = __toESM(require("fs"));
-    path16 = __toESM(require("path"));
+    fs11 = __toESM(require("fs"));
+    path15 = __toESM(require("path"));
     init_specs2();
     init_type_analysis();
     init_diagram_export();
@@ -14657,93 +13949,799 @@ var MODEL = __MODEL_JSON__;
         b.addEventListener('click', function () { navigateTo(b.getAttribute('data-open-kind'), b.getAttribute('data-open-id')); });
       })(opens[k]);
     }
-    var typesOpen = document.getElementById('openTypesBtn');
-    if (typesOpen && typesOpen.addEventListener && panel.innerHTML.indexOf('openTypesBtn') >= 0) {
-      typesOpen.addEventListener('click', function () { navigateTo('types', null); });
+    var typesOpen = document.getElementById('openTypesBtn');
+    if (typesOpen && typesOpen.addEventListener && panel.innerHTML.indexOf('openTypesBtn') >= 0) {
+      typesOpen.addEventListener('click', function () { navigateTo('types', null); });
+    }
+    var oapis = panel.querySelectorAll('[data-openapi-tag]');
+    for (var oi = 0; oi < oapis.length; oi++) {
+      (function (b) {
+        b.addEventListener('click', function () {
+          var tag = b.getAttribute('data-openapi-tag') || '';
+          if (typeof opts !== 'undefined' && opts && opts.onOpenApi) { opts.onOpenApi(tag); return; }
+          var href = openApiSiblingHref();
+          if (href) window.open(href + (tag ? '#/' + tag : ''), '_blank', 'noopener');
+        });
+      })(oapis[oi]);
+    }
+    var ospecs = panel.querySelectorAll('[data-openspec-kind]');
+    for (var si = 0; si < ospecs.length; si++) {
+      (function (b) {
+        b.addEventListener('click', function () {
+          if (typeof opts !== 'undefined' && opts && typeof opts.onOpenSpec === 'function') {
+            opts.onOpenSpec(b.getAttribute('data-openspec-kind'), b.getAttribute('data-openspec-id') || '');
+          }
+        });
+      })(ospecs[si]);
+    }
+    var flows = panel.querySelectorAll('[data-flow-comp]');
+    for (var j = 0; j < flows.length; j++) {
+      (function (b) {
+        b.addEventListener('click', function (ev) {
+          if (ev && ev.stopPropagation) ev.stopPropagation();
+          openFlow(b.getAttribute('data-flow-comp'), b.getAttribute('data-flow-method'), b.getAttribute('data-flow-mode') || 'flow');
+        });
+      })(flows[j]);
+    }
+  }
+
+  renderPanel();
+  // Stage G: a deep link may focus a component and/or open a method's narrative
+  // modal once the seeded view + DOM + cy graph exist. The host parses the URL hash
+  // into opts.initialSelect / opts.initialFlow \u2014 both carry the component id, so this
+  // works whether the seeded view is the component itself or its parent subsystem
+  // (a leaf component has no meaningful "inside", so Specs deep-links open the parent
+  // and focus the component here).
+  (function () {
+    if (typeof opts === 'undefined' || !opts) return;
+    var f = opts.initialFlow, s = opts.initialSelect;
+    var focusComp = (f && f.comp) || (s && s.comp);
+    if (focusComp && compById[focusComp]) {
+      try { select('component', focusComp, true); } catch (e) { /* ignore */ }
+    }
+    if (f && f.comp && f.method && compById[f.comp]) {
+      try { openFlow(f.comp, f.method, f.mode === 'steps' ? 'steps' : 'flow'); } catch (e) { /* ignore */ }
+    }
+  })();
+})();
+</script>
+</body>
+</html>
+`;
+  }
+});
+
+// src/core/rules/repository.ts
+function addRule(rule) {
+  ruleSet.push(rule);
+}
+function registerBuiltinRules() {
+  ruleSet = [];
+  for (const rule of SDD_RULES) addRule(rule);
+}
+function registerPackRules(packRules) {
+  for (const rule of packRules) addRule(rule);
+}
+function ruleSequence() {
+  const base = ruleSet.filter((r) => r !== lintAllowsRule);
+  return ruleSet.includes(lintAllowsRule) ? [...base, lintAllowsRule] : base;
+}
+function specScopedRules() {
+  return ruleSequence().filter((r) => r.scope === "spec");
+}
+var ruleSet;
+var init_repository = __esm({
+  "src/core/rules/repository.ts"() {
+    "use strict";
+    init_rules();
+    init_lint_allows();
+    ruleSet = [];
+  }
+});
+
+// src/utils/filenames.ts
+function safeFilenamePart(value) {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "-");
+}
+var init_filenames = __esm({
+  "src/utils/filenames.ts"() {
+    "use strict";
+  }
+});
+
+// src/core/openapi.ts
+function schemaFor(typeRef, closureIds) {
+  const trimmed = typeRef.trim().replace(/^promise\s*<(.+)>$/i, "$1").trim();
+  const arrayMatch = /^(.+)\[\]$/.exec(trimmed);
+  if (arrayMatch) {
+    return { type: "array", items: schemaFor(arrayMatch[1], closureIds) };
+  }
+  const lower = trimmed.toLowerCase();
+  if (lower in PRIMITIVES) {
+    const p = PRIMITIVES[lower];
+    return p.type ? { ...p } : {};
+  }
+  const local = trimmed.split(/::|\./).pop().toLowerCase().replace(/[^a-z0-9_-]/g, "");
+  const hit = [...closureIds].find((id) => id.toLowerCase() === local);
+  if (hit) return { $ref: `#/components/schemas/${hit}` };
+  return { type: "object", description: `Unresolved type: ${trimmed}` };
+}
+function operationFor(method2, closureIds) {
+  const endpoint = method2.endpoint;
+  const httpVerb = endpoint && endpoint.transport === "HTTP" ? endpoint.method.toLowerCase() : "post";
+  const bodyVerbs = /* @__PURE__ */ new Set(["post", "put", "patch"]);
+  const params = method2.params ?? [];
+  const op = {
+    operationId: method2.name,
+    summary: method2.description,
+    responses: {
+      "200": {
+        description: method2.returns || "Success",
+        ...method2.returns && method2.returns.toLowerCase() !== "void" ? { content: { "application/json": { schema: schemaFor(method2.returns, closureIds) } } } : {}
+      }
+    }
+  };
+  if (method2.guarantees?.length) op["x-wairon-guarantees"] = method2.guarantees;
+  if (method2.effect) op["x-wairon-effect"] = method2.effect;
+  if (method2.ext && Object.keys(method2.ext).length) op["x-wairon-ext"] = method2.ext;
+  if (params.length) {
+    if (bodyVerbs.has(httpVerb)) {
+      op.requestBody = {
+        required: true,
+        content: {
+          "application/json": {
+            schema: {
+              type: "object",
+              properties: Object.fromEntries(params.map((p) => [p.name, schemaFor(p.type, closureIds)])),
+              required: params.filter((p) => !p.optional).map((p) => p.name)
+            }
+          }
+        }
+      };
+    } else {
+      op.parameters = params.map((p) => ({
+        name: p.name,
+        in: "query",
+        required: !p.optional,
+        ...p.description ? { description: p.description } : {},
+        schema: schemaFor(p.type, closureIds)
+      }));
+    }
+  }
+  return op;
+}
+function securitySchemeObject(auth) {
+  if (auth.scheme === "none") return null;
+  const desc = auth.description ? { description: auth.description } : {};
+  switch (auth.scheme) {
+    case "apiKey":
+      return { type: "apiKey", in: auth.in ?? "header", name: auth.name ?? "X-API-Key", ...desc };
+    case "bearer":
+      return { type: "http", scheme: "bearer", ...auth.bearerFormat ? { bearerFormat: auth.bearerFormat } : {}, ...desc };
+    case "basic":
+      return { type: "http", scheme: "basic", ...desc };
+    case "oauth2": {
+      const flow = { scopes: Object.fromEntries((auth.scopes ?? []).map((s) => [s.name, s.description])) };
+      if (auth.authorizationUrl) flow.authorizationUrl = auth.authorizationUrl;
+      if (auth.tokenUrl) flow.tokenUrl = auth.tokenUrl;
+      if (auth.refreshUrl) flow.refreshUrl = auth.refreshUrl;
+      return { type: "oauth2", flows: { [auth.flow ?? "authorizationCode"]: flow }, ...desc };
+    }
+    case "openIdConnect":
+      return { type: "openIdConnect", openIdConnectUrl: auth.openIdConnectUrl ?? "", ...desc };
+    case "custom":
+      return { type: "apiKey", in: auth.in ?? "header", name: auth.name ?? "Authorization", description: auth.description ?? auth.example ?? "Custom authentication scheme." };
+    default:
+      return null;
+  }
+}
+function schemeBaseName(scheme) {
+  return { apiKey: "ApiKeyAuth", bearer: "BearerAuth", basic: "BasicAuth", oauth2: "OAuth2", openIdConnect: "OpenIdConnect", custom: "CustomAuth" }[scheme] ?? "Auth";
+}
+function buildSecurity(entries) {
+  const schemes = {};
+  const nameByContent = /* @__PURE__ */ new Map();
+  const securityByEntry = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (!entry.auth) continue;
+    const obj = securitySchemeObject(entry.auth);
+    if (!obj) continue;
+    const content = JSON.stringify(obj);
+    let name = nameByContent.get(content);
+    if (!name) {
+      name = schemeBaseName(entry.auth.scheme);
+      for (let n = 2; schemes[name]; n++) name = schemeBaseName(entry.auth.scheme) + n;
+      schemes[name] = obj;
+      nameByContent.set(content, name);
+    }
+    const scopeNames = entry.auth.scheme === "oauth2" ? (entry.auth.scopes ?? []).map((s) => s.name) : [];
+    securityByEntry.set(entry.id, { [name]: scopeNames });
+  }
+  return { schemes, securityByEntry };
+}
+function httpEntriesOf(snapshot) {
+  return snapshot.interfaces.filter((e) => e.type === "REST" || e.methods.some((m) => m.endpoint?.transport === "HTTP"));
+}
+function renderDoc(snapshot, entries, closureIds, opts = {}) {
+  const { schemes, securityByEntry } = buildSecurity(entries);
+  const paths = {};
+  for (const entry of entries) {
+    const security = securityByEntry.get(entry.id);
+    for (const method2 of entry.methods) {
+      const endpoint = method2.endpoint;
+      if (!endpoint || endpoint.transport !== "HTTP") continue;
+      const p = endpoint.path.startsWith("/") ? endpoint.path : `/${endpoint.path}`;
+      paths[p] = paths[p] ?? {};
+      paths[p][endpoint.method.toLowerCase()] = {
+        tags: [entry.id],
+        ...operationFor(method2, closureIds),
+        ...security ? { security: [security] } : {}
+      };
+    }
+  }
+  const schemas = {};
+  for (const t of snapshot.types) {
+    schemas[t.id] = {
+      type: "object",
+      title: t.name,
+      properties: Object.fromEntries(t.fields.map((f) => [f.name, schemaFor(f.type, closureIds)])),
+      required: t.fields.filter((f) => !f.optional).map((f) => f.name)
+    };
+  }
+  const components = {};
+  if (Object.keys(schemas).length) components.schemas = schemas;
+  if (Object.keys(schemes).length) components.securitySchemes = schemes;
+  const basePaths = [...new Set(entries.map((e) => e.basePath).filter((b) => !!b))];
+  const servers = opts.servers && basePaths.length === 1 ? [{ url: basePaths[0] }] : void 0;
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: opts.title ?? snapshot.projectName,
+      version: snapshot.version ?? "0.0.0",
+      ...snapshot.stateId ? { "x-wairon-state-id": snapshot.stateId } : {},
+      "x-wairon-origin": snapshot.origin,
+      "x-wairon-generated-at": snapshot.generatedAt
+    },
+    ...servers ? { servers } : {},
+    paths,
+    ...Object.keys(components).length ? { components } : {}
+  };
+}
+function toOpenApiSet(snapshot) {
+  const closureIds = new Set(snapshot.types.map((t) => t.id));
+  const byPortal = /* @__PURE__ */ new Map();
+  const order = [];
+  for (const entry of httpEntriesOf(snapshot)) {
+    if (!byPortal.has(entry.component)) {
+      byPortal.set(entry.component, []);
+      order.push(entry.component);
+    }
+    byPortal.get(entry.component).push(entry);
+  }
+  return order.map((portalId) => {
+    const entries = byPortal.get(portalId);
+    const name = entries[0]?.name ?? portalId;
+    return { portalId, name, document: JSON.stringify(renderDoc(snapshot, entries, closureIds, { title: name, servers: true }), null, 2) };
+  });
+}
+function isOpenApiDocument(body) {
+  try {
+    const parsed = yaml2.load(body);
+    return !!parsed && typeof parsed === "object" && typeof parsed.openapi === "string";
+  } catch {
+    return false;
+  }
+}
+function typeRefFromSchema(schema) {
+  if (!schema) return "json";
+  const ref = schema.$ref;
+  if (typeof ref === "string") return ref.split("/").pop() ?? "json";
+  if (schema.type === "array") {
+    return `${typeRefFromSchema(schema.items)}[]`;
+  }
+  const t = schema.type;
+  if (t === "integer") return "int";
+  if (typeof t === "string" && t !== "object") return t;
+  return "json";
+}
+function authFromSecurityScheme(scheme) {
+  const desc = typeof scheme.description === "string" ? { description: scheme.description } : {};
+  if (scheme.type === "apiKey") {
+    return {
+      scheme: "apiKey",
+      ...scheme.in === "header" || scheme.in === "query" || scheme.in === "cookie" ? { in: scheme.in } : {},
+      ...typeof scheme.name === "string" ? { name: scheme.name } : {},
+      ...desc
+    };
+  }
+  if (scheme.type === "http") {
+    if (scheme.scheme === "bearer") return { scheme: "bearer", ...typeof scheme.bearerFormat === "string" ? { bearerFormat: scheme.bearerFormat } : {}, ...desc };
+    if (scheme.scheme === "basic") return { scheme: "basic", ...desc };
+  }
+  if (scheme.type === "oauth2") {
+    const flows = scheme.flows ?? {};
+    const flowKey = Object.keys(flows)[0];
+    const f = flows[flowKey] ?? {};
+    return {
+      scheme: "oauth2",
+      ...flowKey === "authorizationCode" || flowKey === "clientCredentials" || flowKey === "implicit" || flowKey === "password" ? { flow: flowKey } : {},
+      ...typeof f.authorizationUrl === "string" ? { authorizationUrl: f.authorizationUrl } : {},
+      ...typeof f.tokenUrl === "string" ? { tokenUrl: f.tokenUrl } : {},
+      ...typeof f.refreshUrl === "string" ? { refreshUrl: f.refreshUrl } : {},
+      scopes: Object.entries(f.scopes ?? {}).map(([name, description]) => ({ name, description })),
+      ...desc
+    };
+  }
+  if (scheme.type === "openIdConnect") {
+    return { scheme: "openIdConnect", openIdConnectUrl: typeof scheme.openIdConnectUrl === "string" ? scheme.openIdConnectUrl : "", ...desc };
+  }
+  return void 0;
+}
+function fromOpenApi(document, projectName) {
+  let parsed;
+  try {
+    parsed = yaml2.load(document);
+  } catch (e) {
+    throw new Error(`Invalid surface document: not parseable as JSON/YAML (${e instanceof Error ? e.message : String(e)})`);
+  }
+  if (!parsed || typeof parsed !== "object" || typeof parsed.openapi !== "string" || typeof parsed.paths !== "object") {
+    throw new Error('Invalid surface document: missing OpenAPI "openapi"/"paths" structure.');
+  }
+  const info = parsed.info ?? {};
+  const methods = [];
+  for (const [rawPath, ops] of Object.entries(parsed.paths)) {
+    for (const [verb, opRaw] of Object.entries(ops ?? {})) {
+      if (!["get", "post", "put", "delete", "patch", "options", "head"].includes(verb)) continue;
+      const op = opRaw ?? {};
+      const name = typeof op.operationId === "string" && /^[a-zA-Z0-9_]+$/.test(op.operationId) ? op.operationId : `${verb}_${rawPath.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
+      const params = [];
+      for (const p of op.parameters ?? []) {
+        if (typeof p.name !== "string") continue;
+        params.push({
+          name: p.name,
+          type: typeRefFromSchema(p.schema),
+          ...p.required === true ? {} : { optional: true },
+          ...typeof p.description === "string" ? { description: p.description } : {}
+        });
+      }
+      const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+      if (bodySchema) {
+        const props = bodySchema.properties ?? {};
+        const required = new Set(bodySchema.required ?? []);
+        if (Object.keys(props).length) {
+          for (const [pname, pschema] of Object.entries(props)) {
+            params.push({ name: pname, type: typeRefFromSchema(pschema), ...required.has(pname) ? {} : { optional: true } });
+          }
+        } else {
+          params.push({ name: "body", type: typeRefFromSchema(bodySchema) });
+        }
+      }
+      const okResponse = op.responses?.["200"] ?? op.responses?.["201"];
+      const responseSchema = okResponse?.content?.["application/json"]?.schema;
+      const returns = responseSchema ? typeRefFromSchema(responseSchema) : "void";
+      const rawGuarantees = op["x-wairon-guarantees"];
+      const guarantees = Array.isArray(rawGuarantees) ? rawGuarantees.filter((g) => typeof g === "string" && g.length > 0) : [];
+      const rawEffect = op["x-wairon-effect"];
+      const effect = rawEffect === "read" || rawEffect === "write" ? rawEffect : void 0;
+      const rawExt = op["x-wairon-ext"];
+      const ext = rawExt && typeof rawExt === "object" && !Array.isArray(rawExt) ? rawExt : void 0;
+      methods.push({
+        name,
+        description: typeof op.summary === "string" ? op.summary : typeof op.description === "string" ? op.description : name,
+        signature: `${name}(${params.map((p) => `${p.name}: ${p.type}`).join(", ")}): ${returns}`,
+        returns,
+        params,
+        endpoint: { transport: "HTTP", method: verb.toUpperCase(), path: rawPath },
+        ...guarantees.length ? { guarantees } : {},
+        ...effect ? { effect } : {},
+        ...ext ? { ext } : {}
+      });
+    }
+  }
+  const types = [];
+  const schemas = parsed.components?.schemas ?? {};
+  for (const [id, schema] of Object.entries(schemas)) {
+    const props = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+    types.push({
+      id,
+      name: typeof schema.title === "string" ? schema.title : id,
+      kind: "value-object",
+      fields: Object.entries(props).map(([fname, fschema]) => ({
+        name: fname,
+        type: typeRefFromSchema(fschema),
+        ...required.has(fname) ? {} : { optional: true }
+      }))
+    });
+  }
+  const securitySchemes = parsed.components?.securitySchemes ?? {};
+  const firstScheme = Object.values(securitySchemes)[0];
+  const importedAuth = firstScheme ? authFromSecurityScheme(firstScheme) : void 0;
+  const entry = {
+    id: `${projectName}-api`,
+    name: typeof info.title === "string" ? info.title : projectName,
+    audience: "external",
+    type: "REST",
+    component: `${projectName}-api`,
+    methods,
+    details: typeof info.description === "string" ? info.description : `Imported OpenAPI surface of ${projectName}.`,
+    ...typeof info.version === "string" ? { version: info.version } : {},
+    ...importedAuth ? { auth: importedAuth } : {}
+  };
+  return SurfaceSnapshotSchema.parse({
+    projectName,
+    origin: "authored",
+    ...typeof info.version === "string" ? { version: info.version } : {},
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    interfaces: [entry],
+    types
+  });
+}
+var yaml2, PRIMITIVES;
+var init_openapi = __esm({
+  "src/core/openapi.ts"() {
+    "use strict";
+    yaml2 = __toESM(require("js-yaml"));
+    init_models();
+    PRIMITIVES = {
+      string: { type: "string" },
+      number: { type: "number" },
+      float: { type: "number" },
+      decimal: { type: "number" },
+      int: { type: "integer" },
+      integer: { type: "integer" },
+      boolean: { type: "boolean" },
+      bool: { type: "boolean" },
+      date: { type: "string", format: "date-time" },
+      datetime: { type: "string", format: "date-time" },
+      uuid: { type: "string", format: "uuid" },
+      json: { type: "object" },
+      object: { type: "object" },
+      any: {},
+      unknown: {},
+      void: {}
+    };
+  }
+});
+
+// src/core/surfaces.ts
+function surfacesDir(rootDir) {
+  return path16.join(rootDir, ".wai", SURFACES_DIRNAME);
+}
+function audienceRank(audience) {
+  const idx = SURFACE_AUDIENCES.indexOf(audience ?? "instance");
+  return idx === -1 ? SURFACE_AUDIENCES.indexOf("instance") : idx;
+}
+function stateIdString() {
+  const s = computeStateId();
+  return `${s.algorithm}:${s.digest}`;
+}
+function computeTypeClosure(entries, types) {
+  const included = /* @__PURE__ */ new Map();
+  const queue = [];
+  const enqueueRef = (ref) => {
+    if (BUILTIN_TYPES.has(ref.toLowerCase())) return;
+    for (const spec of types) {
+      const qualifiedId2 = spec.subsystem && !spec.id.startsWith(`${spec.subsystem}::`) ? `${spec.subsystem}::${spec.id}` : spec.id;
+      if (matchTypeRef(ref, qualifiedId2) && !included.has(spec.id)) {
+        included.set(spec.id, spec);
+        queue.push(spec.id);
+      }
     }
-    var oapis = panel.querySelectorAll('[data-openapi-tag]');
-    for (var oi = 0; oi < oapis.length; oi++) {
-      (function (b) {
-        b.addEventListener('click', function () {
-          var tag = b.getAttribute('data-openapi-tag') || '';
-          if (typeof opts !== 'undefined' && opts && opts.onOpenApi) { opts.onOpenApi(tag); return; }
-          var href = openApiSiblingHref();
-          if (href) window.open(href + (tag ? '#/' + tag : ''), '_blank', 'noopener');
-        });
-      })(oapis[oi]);
+  };
+  for (const entry of entries) {
+    for (const m of entry.methods) {
+      for (const ref of methodTypeRefs(m)) enqueueRef(ref);
     }
-    var ospecs = panel.querySelectorAll('[data-openspec-kind]');
-    for (var si = 0; si < ospecs.length; si++) {
-      (function (b) {
-        b.addEventListener('click', function () {
-          if (typeof opts !== 'undefined' && opts && typeof opts.onOpenSpec === 'function') {
-            opts.onOpenSpec(b.getAttribute('data-openspec-kind'), b.getAttribute('data-openspec-id') || '');
-          }
-        });
-      })(ospecs[si]);
+  }
+  while (queue.length) {
+    const spec = included.get(queue.shift());
+    for (const field of spec.fields) {
+      for (const ref of extractTypeIdentifiers(field.type)) enqueueRef(ref);
     }
-    var flows = panel.querySelectorAll('[data-flow-comp]');
-    for (var j = 0; j < flows.length; j++) {
-      (function (b) {
-        b.addEventListener('click', function (ev) {
-          if (ev && ev.stopPropagation) ev.stopPropagation();
-          openFlow(b.getAttribute('data-flow-comp'), b.getAttribute('data-flow-method'), b.getAttribute('data-flow-mode') || 'flow');
-        });
-      })(flows[j]);
+  }
+  return [...included.values()].map((t) => ({
+    id: t.id,
+    name: t.name,
+    kind: t.kind,
+    fields: t.fields.map((f) => ({
+      name: f.name,
+      type: f.type,
+      ...f.description ? { description: f.description } : {},
+      ...f.optional ? { optional: true } : {}
+    }))
+  }));
+}
+function projectOwnSurface(maxAudience) {
+  const system = loadSystemSpec();
+  if (!system) {
+    throw new Error("Cannot project a surface: the L0 system spec is missing.");
+  }
+  const subsystems = loadSubsystemSpecs();
+  const components = loadComponentSpecs();
+  const interfaces = loadInterfaceSpecs();
+  const types = loadTypeSpecs();
+  const floor = audienceRank(maxAudience);
+  const rawEntries = system.publicInterfaces ?? [];
+  const entries = [];
+  for (const raw of rawEntries) {
+    const audience = raw.audience ?? "instance";
+    if (audienceRank(audience) < floor) continue;
+    if (!raw.component) continue;
+    const comp = components.find((c) => c.id === raw.component);
+    if (!comp) continue;
+    const compInterfaces = interfaces.filter((i) => i.component === comp.id && (!raw.interface || i.id === raw.interface));
+    const methods = compInterfaces.flatMap((i) => i.methods);
+    const subsystemType = subsystems.find((s) => s.id === comp.subsystem)?.publicInterfaces.find((pi) => pi.component === comp.id)?.type;
+    entries.push({
+      id: raw.id ?? raw.interface ?? comp.id,
+      name: raw.name ?? comp.name,
+      audience,
+      type: raw.type ?? subsystemType ?? "Custom",
+      component: comp.id,
+      methods,
+      ...comp.dispatch && comp.dispatch.length ? { dispatch: comp.dispatch } : {},
+      // Project the backing Portal's auth + basePath so the codec can emit
+      // OpenAPI security + per-portal servers self-contained from the snapshot.
+      ...comp.auth && comp.auth.scheme !== "none" ? { auth: comp.auth } : {},
+      ...comp.basePath ? { basePath: comp.basePath } : {},
+      details: raw.details ?? "",
+      ...raw.version ? { version: raw.version } : {},
+      ...raw.stability ? { stability: raw.stability } : {}
+    });
+  }
+  return SurfaceSnapshotSchema.parse({
+    projectName: system.name,
+    origin: "generated",
+    stateId: stateIdString(),
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    interfaces: entries,
+    types: computeTypeClosure(entries, types)
+  });
+}
+function projectChildSurface() {
+  return projectOwnSurface("project");
+}
+function localName(id) {
+  return id.split("::").pop();
+}
+function projectSubsystemSurface(subsystemId) {
+  const system = loadSystemSpec();
+  if (!system) {
+    throw new Error("Cannot project a subsystem surface: the L0 system spec is missing.");
+  }
+  const subsystems = loadSubsystemSpecs();
+  const target = subsystems.find((s) => s.id === subsystemId);
+  if (!target) {
+    throw new Error(`Cannot project a subsystem surface: subsystem "${subsystemId}" does not exist.`);
+  }
+  const components = loadComponentSpecs();
+  const interfaces = loadInterfaceSpecs();
+  const types = loadTypeSpecs();
+  const entries = [];
+  const unprojectable = [];
+  for (const pub of target.publicInterfaces ?? []) {
+    if (!pub.component) continue;
+    const comp = components.find((c) => c.id === pub.component || c.id === `${subsystemId}::${pub.component}`);
+    if (!comp) continue;
+    if (!CROSS_BOUNDARY_TARGETS.has(comp.componentType)) {
+      unprojectable.push({ component: pub.component, componentType: comp.componentType });
+      continue;
     }
+    const compInterfaces = interfaces.filter((i) => i.component === comp.id && (!pub.interface || i.id === pub.interface || i.id === `${subsystemId}::${pub.interface}`));
+    const methods = compInterfaces.flatMap((i) => i.methods);
+    entries.push({
+      id: localName(pub.interface ?? comp.id),
+      name: comp.name,
+      // Family ceiling: a sibling surface is consumable by the system family only.
+      audience: "project",
+      type: pub.type ?? "Custom",
+      // The snapshot carries the LOCAL portal name — consumers resolve cross-tree
+      // refs by their final segment.
+      component: localName(comp.id),
+      methods,
+      ...comp.dispatch && comp.dispatch.length ? { dispatch: comp.dispatch } : {},
+      // Project the backing component's auth + basePath so the codec can emit
+      // OpenAPI security + per-portal servers self-contained from the snapshot.
+      ...comp.auth && comp.auth.scheme !== "none" ? { auth: comp.auth } : {},
+      ...comp.basePath ? { basePath: comp.basePath } : {},
+      details: pub.details ?? ""
+    });
   }
-
-  renderPanel();
-  // Stage G: a deep link may focus a component and/or open a method's narrative
-  // modal once the seeded view + DOM + cy graph exist. The host parses the URL hash
-  // into opts.initialSelect / opts.initialFlow \u2014 both carry the component id, so this
-  // works whether the seeded view is the component itself or its parent subsystem
-  // (a leaf component has no meaningful "inside", so Specs deep-links open the parent
-  // and focus the component here).
-  (function () {
-    if (typeof opts === 'undefined' || !opts) return;
-    var f = opts.initialFlow, s = opts.initialSelect;
-    var focusComp = (f && f.comp) || (s && s.comp);
-    if (focusComp && compById[focusComp]) {
-      try { select('component', focusComp, true); } catch (e) { /* ignore */ }
+  for (const skipped of unprojectable) {
+    console.error(
+      `[surfaces] skipped "${subsystemId}::${skipped.component}": a published ${skipped.componentType} can never serve a cross-boundary caller, so it stays out of every chained child's sibling surface \u2014 publish this surface through a Portal, a Gateway, or an Observer (for events).`
+    );
+  }
+  return SurfaceSnapshotSchema.parse({
+    projectName: `${system.name}::${subsystemId}`,
+    origin: "generated",
+    stateId: stateIdString(),
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    interfaces: entries,
+    types: computeTypeClosure(entries, types)
+  });
+}
+function listSnapshots(rootDir = getProjectRoot()) {
+  const dir = surfacesDir(rootDir);
+  if (!fs12.existsSync(dir)) return [];
+  const out = [];
+  for (const file of fs12.readdirSync(dir)) {
+    if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
+    try {
+      out.push(SurfaceSnapshotSchema.parse(readYamlFile(path16.join(dir, file))));
+    } catch {
     }
-    if (f && f.comp && f.method && compById[f.comp]) {
-      try { openFlow(f.comp, f.method, f.mode === 'steps' ? 'steps' : 'flow'); } catch (e) { /* ignore */ }
+  }
+  return out;
+}
+function snapshotFilename(projectName) {
+  return `${safeFilenamePart(projectName)}.yaml`;
+}
+function writeSnapshotIfChanged(snapshot, rootDir) {
+  const dir = surfacesDir(rootDir);
+  fs12.mkdirSync(dir, { recursive: true });
+  const p = path16.join(dir, snapshotFilename(snapshot.projectName));
+  const next = SurfaceSnapshotSchema.parse(snapshot);
+  if (fs12.existsSync(p)) {
+    try {
+      const existing = SurfaceSnapshotSchema.parse(readYamlFile(p));
+      if (surfaceContentKey(existing) === surfaceContentKey(next)) {
+        return { path: p, changed: false };
+      }
+    } catch {
     }
-  })();
-})();
-</script>
-</body>
-</html>
-`;
   }
-});
-
-// src/core/rules/repository.ts
-function addRule(rule) {
-  ruleSet.push(rule);
+  writeYamlFile(p, next);
+  return { path: p, changed: true };
 }
-function registerBuiltinRules() {
-  ruleSet = [];
-  for (const rule of SDD_RULES) addRule(rule);
+function saveSnapshot(snapshot, rootDir = getProjectRoot()) {
+  return writeSnapshotIfChanged(snapshot, rootDir).path;
 }
-function registerPackRules(packRules) {
-  for (const rule of packRules) addRule(rule);
+function loadSurfaceSnapshots() {
+  return listSnapshots();
 }
-function ruleSequence() {
-  const base = ruleSet.filter((r) => r !== lintAllowsRule);
-  return ruleSet.includes(lintAllowsRule) ? [...base, lintAllowsRule] : base;
+function listMountSnapshots(mounts) {
+  const bound = path16.resolve(getProjectRoot());
+  const out = [];
+  for (const namespace of mounts) {
+    const dir = resolveSubprojectForNamespace(namespace);
+    if (!dir || path16.resolve(dir) === bound) continue;
+    const snapshots = listSnapshots(dir);
+    if (snapshots.length > 0) out.push({ namespace, snapshots });
+  }
+  return out;
 }
-function specScopedRules() {
-  return ruleSequence().filter((r) => r.scope === "spec");
+function loadMountSurfaceSnapshots(mounts) {
+  return listMountSnapshots(mounts);
 }
-var ruleSet;
-var init_repository = __esm({
-  "src/core/rules/repository.ts"() {
+function selectPortalSpec(renderedSet, portalId) {
+  const hit = renderedSet.find((spec) => spec.portalId === portalId);
+  if (!hit) {
+    const known = renderedSet.map((s) => s.portalId).join(", ");
+    throw new Error(`Unknown portal "${portalId}" \u2014 this surface renders: ${known || "(no portals)"}.`);
+  }
+  return [hit];
+}
+function perPortalPath(resolvedOut, portalId) {
+  const ext = path16.extname(resolvedOut);
+  const stem2 = ext ? resolvedOut.slice(0, -ext.length) : resolvedOut;
+  return `${stem2}.${safeFilenamePart(portalId)}${ext}`;
+}
+function writeSurfaceFile(outPath, snapshot, renderedSet) {
+  const resolved = path16.resolve(outPath);
+  fs12.mkdirSync(path16.dirname(resolved), { recursive: true });
+  if (!renderedSet || renderedSet.length === 0) {
+    writeYamlFile(resolved, snapshot);
+    return [resolved];
+  }
+  if (renderedSet.length === 1) {
+    fs12.writeFileSync(resolved, renderedSet[0].document);
+    return [resolved];
+  }
+  return renderedSet.map((spec) => {
+    const target = perPortalPath(resolved, spec.portalId);
+    fs12.writeFileSync(target, spec.document);
+    return target;
+  });
+}
+function exportResult(snapshot, renderedSet, writtenPaths) {
+  const rendered = renderedSet?.length === 1 ? renderedSet[0].document : void 0;
+  return {
+    snapshot,
+    ...rendered !== void 0 ? { rendered } : {},
+    ...renderedSet ? { renderedSet } : {},
+    ...writtenPaths.length === 1 ? { writtenTo: writtenPaths[0] } : {},
+    ...writtenPaths.length ? { writtenPaths } : {}
+  };
+}
+function exportSurface(maxAudience, format, outPath, portalId) {
+  const snapshot = projectOwnSurface(maxAudience);
+  let renderedSet = format === "openapi" ? toOpenApiSet(snapshot) : void 0;
+  if (renderedSet && portalId) renderedSet = selectPortalSpec(renderedSet, portalId);
+  const writtenPaths = outPath ? writeSurfaceFile(outPath, snapshot, renderedSet) : [];
+  return exportResult(snapshot, renderedSet, writtenPaths);
+}
+function importSurface(sourcePath, origin) {
+  const resolved = path16.resolve(sourcePath);
+  if (!fs12.existsSync(resolved)) {
+    throw new Error(`Surface document not found: ${resolved}`);
+  }
+  const body = fs12.readFileSync(resolved, "utf8");
+  let snapshot;
+  if (isOpenApiDocument(body)) {
+    const projectName = path16.basename(resolved).replace(/\.(json|ya?ml)$/i, "");
+    snapshot = fromOpenApi(body, projectName);
+    snapshot = { ...snapshot, origin };
+  } else {
+    snapshot = SurfaceSnapshotSchema.parse(readYamlFile(resolved));
+    snapshot = { ...snapshot, origin };
+  }
+  saveSnapshot(snapshot);
+  return snapshot;
+}
+function pinFamilySurfaces() {
+  const parent = resolveChainingParent();
+  if (!parent) return null;
+  const childRoot = getProjectRoot();
+  const projected = runWithProjectRoot(parent.parentRoot, () => {
+    invalidateSpecCache();
+    const siblings = loadSubsystemSpecs().filter((s) => !s.id.includes("::") && s.id !== parent.subsystemId);
+    return [projectChildSurface(), ...siblings.map((s) => projectSubsystemSurface(s.id))];
+  });
+  const before = new Map(listSnapshots(childRoot).map((s) => [s.projectName, surfaceContentKey(s)]));
+  const changed = [];
+  for (const snapshot of projected) {
+    const stored = saveSnapshot(snapshot, childRoot);
+    if (before.get(snapshot.projectName) !== surfaceContentKey(SurfaceSnapshotSchema.parse(snapshot))) {
+      changed.push(stored);
+    }
+  }
+  return changed;
+}
+function computeParentStateId(parentRoot) {
+  return computeStateIdAt(parentRoot);
+}
+function listExternalInterfaces() {
+  const snapshots = listSnapshots();
+  const chainingParent = resolveChainingParent();
+  const parentStateId = chainingParent ? computeParentStateId(chainingParent.parentRoot) : 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";
+    return {
+      projectName: snapshot.projectName,
+      origin: snapshot.origin,
+      sourceKind,
+      generatedAt: snapshot.generatedAt,
+      ...snapshot.stateId ? { stateId: snapshot.stateId } : {},
+      ...snapshot.version ? { version: snapshot.version } : {},
+      freshness,
+      interfaceIds: snapshot.interfaces.map((e) => e.id)
+    };
+  });
+}
+function surfaceContentKey(snapshot) {
+  const { stateId, generatedAt, origin, ...content } = snapshot;
+  return JSON.stringify(content);
+}
+var fs12, path16, SURFACES_DIRNAME, CROSS_BOUNDARY_TARGETS;
+var init_surfaces = __esm({
+  "src/core/surfaces.ts"() {
     "use strict";
-    init_rules();
-    init_lint_allows();
-    ruleSet = [];
+    fs12 = __toESM(require("fs"));
+    path16 = __toESM(require("path"));
+    init_fs();
+    init_yaml();
+    init_filenames();
+    init_models();
+    init_specs2();
+    init_statehash();
+    init_type_analysis();
+    init_openapi();
+    SURFACES_DIRNAME = "surfaces";
+    CROSS_BOUNDARY_TARGETS = /* @__PURE__ */ new Set(["Portal", "Gateway", "Observer"]);
   }
 });
 
@@ -14956,7 +14954,8 @@ function validateSddTree(rulesOrOptions, projectType = "backend") {
   let recursive = true;
   let extensions;
   let treatAllAsComplete = false;
-  if (rulesOrOptions && ("scopeSubsystem" in rulesOrOptions || "recursive" in rulesOrOptions || "rules" in rulesOrOptions || "projectType" in rulesOrOptions || "extensions" in rulesOrOptions || "treatAllAsComplete" in rulesOrOptions)) {
+  let crossTree;
+  if (rulesOrOptions && ("scopeSubsystem" in rulesOrOptions || "recursive" in rulesOrOptions || "rules" in rulesOrOptions || "projectType" in rulesOrOptions || "extensions" in rulesOrOptions || "treatAllAsComplete" in rulesOrOptions || "crossTree" in rulesOrOptions)) {
     const opts = rulesOrOptions;
     rules = opts.rules;
     projectType = opts.projectType ?? "backend";
@@ -14964,6 +14963,7 @@ function validateSddTree(rulesOrOptions, projectType = "backend") {
     recursive = opts.recursive ?? true;
     extensions = opts.extensions;
     treatAllAsComplete = opts.treatAllAsComplete ?? false;
+    crossTree = opts.crossTree;
   }
   extensions ??= loadProjectExtensions();
   scanAllSpecs({ recursive });
@@ -15015,6 +15015,9 @@ function validateSddTree(rulesOrOptions, projectType = "backend") {
     for (const err of extensions.errors) {
       issues.push(issue("error", "EXTENSION_LOAD_ERROR", err));
     }
+    const mountSurfaceSnapshots = loadMountSurfaceSnapshots(
+      subsystems.filter((s) => s.projectPath).map((s) => s.id)
+    );
     const ctx = buildRuleContext({
       system,
       subsystems,
@@ -15030,6 +15033,7 @@ function validateSddTree(rulesOrOptions, projectType = "backend") {
       // By-name selections only: a legacy path ref pins nothing to check.
       packSelections: projectPackSelections(),
       surfaceSnapshots,
+      mountSurfaceSnapshots,
       codeModel,
       issues
     });
@@ -15038,56 +15042,26 @@ function validateSddTree(rulesOrOptions, projectType = "backend") {
     for (const rule of ruleSequence()) {
       rule.check(ctx);
     }
-    const hasCrossTreeSuspects = issues.some(
-      (i) => SUBPROJECT_REFERENCE_CODES.has(i.code) || SUBPROJECT_CONFORMANCE_CODES.has(i.code)
-    );
-    const chainingParent = hasCrossTreeSuspects ? findChainingParent(getProjectRoot()) : null;
-    if (chainingParent) {
-      let unverified = 0;
-      let downgraded = 0;
-      for (let at = 0; at < issues.length; at++) {
-        const iss = issues[at];
-        if (SUBPROJECT_REFERENCE_CODES.has(iss.code) && !iss.surfaceResolved) {
-          issues[at] = {
-            severity: "warning",
-            code: "UNVERIFIED_EXTERNAL_REF",
-            crossTreeContext: true,
-            // --ci waives it (parent root is authoritative)
-            specId: iss.specId,
-            ...iss.agentId ? { agentId: iss.agentId } : {},
-            ...iss.draftContext ? { draftContext: true } : {},
-            message: `Unverified external reference (${iss.code}): ${iss.message} No vendored surface snapshot covers this reference, so it cannot be verified from this chained subproject standalone \u2014 re-lock the parent so fresh family/sibling snapshots ship, or inspect what this project can consume via \`wairon surface externals\` / sdd_list_external_interfaces.`
-          };
-          unverified++;
-          continue;
-        }
-        if (SUBPROJECT_CONFORMANCE_CODES.has(iss.code)) {
-          if (iss.severity === "error") {
-            iss.severity = "warning";
-            downgraded++;
-          }
-          iss.crossTreeContext = true;
-        }
-      }
-      if (unverified > 0 || downgraded > 0) {
-        const notes = [];
-        if (unverified > 0) {
-          notes.push(
-            `${unverified} cross-tree reference(s) have no vendored surface snapshot covering them and were reported as UNVERIFIED_EXTERNAL_REF warnings \u2014 re-lock the parent so fresh family/sibling snapshots ship, or inspect via \`wairon surface externals\` / sdd_list_external_interfaces.`
-          );
-        }
-        if (downgraded > 0) {
-          notes.push(
-            `${downgraded} code\u2194spec conformance finding(s) (parent-root-relative source paths) were downgraded to warnings.`
-          );
-        }
-        issues.unshift({
-          severity: "warning",
-          code: "CHAINED_SUBPROJECT_CONTEXT",
-          crossTreeContext: true,
-          message: `This project is a chained subproject ("${chainingParent.subsystemId}") of the parent project at "${chainingParent.parentRoot}". ${notes.join(" ")} Full cross-tree verification runs from the parent root.`
-        });
-      }
+    const uncovered = (i) => SUBPROJECT_REFERENCE_CODES.has(i.code) && !i.surfaceResolved;
+    const chainingParent = crossTree !== "off" && issues.some(uncovered) ? findChainingParent(getProjectRoot()) : null;
+    const resolution = chainingParent ? resolveThroughParent(getProjectRoot(), treatAllAsComplete) : null;
+    if (resolution) {
+      const parentSeverity = /* @__PURE__ */ new Map();
+      for (const i of resolution.issues) {
+        const key = `${i.code}|${i.specId ?? ""}`;
+        if (i.severity === "error" || !parentSeverity.has(key)) parentSeverity.set(key, i.severity);
+      }
+      const rejudged = (i) => {
+        const judged = parentSeverity.get(`${i.code}|${i.specId ?? ""}`);
+        return judged === "error" || judged === "warning" && i.severity === "warning";
+      };
+      const kept = issues.filter((i) => !uncovered(i) && !(i.surfaceResolved && rejudged(i)));
+      const merged = dedupeIssues([...kept, ...resolution.issues]);
+      return {
+        valid: merged.every((i) => i.severity !== "error"),
+        issues: merged,
+        resolvedThrough: { root: resolution.root, scope: resolution.scope }
+      };
     }
     return {
       valid: issues.every((i) => i.severity !== "error"),
@@ -15099,6 +15073,74 @@ function validateSddTree(rulesOrOptions, projectType = "backend") {
     });
   }
 }
+function resolveThroughParent(boundRoot, treatAllAsComplete) {
+  const reach = getRequestParentReach();
+  if (reach && !reach.parentReach) return null;
+  const ceiling = reach?.topRoot ? path18.resolve(reach.topRoot) : void 0;
+  const chain = [];
+  let top = path18.resolve(boundRoot);
+  while (top !== ceiling) {
+    const hop = findChainingParent(top);
+    if (!hop) break;
+    const next = path18.resolve(hop.parentRoot);
+    if (ceiling && !isWithinOrEqual(ceiling, next)) break;
+    chain.unshift(hop.subsystemId);
+    top = next;
+  }
+  if (chain.length === 0) return null;
+  const scope = chain.join("::");
+  const inner = runWithProjectRoot(top, () => {
+    invalidateSpecCache();
+    let governing = {};
+    try {
+      const config = loadProjectConfig();
+      governing = { rules: config.rules, projectType: config.projectType };
+    } catch {
+    }
+    return validateSddTree({
+      ...governing,
+      scopeSubsystem: scope,
+      recursive: true,
+      crossTree: "off",
+      treatAllAsComplete
+    });
+  });
+  if (inner.issues.some((i) => i.code === "MISSING_SYSTEM_SPEC" || i.code === "SUBSYSTEM_NOT_FOUND")) return null;
+  const local = scope.split("::").pop();
+  const issues = inner.issues.map((i) => ({
+    ...i,
+    message: stripNamespace(i.message, scope),
+    ...i.specId !== void 0 ? { specId: i.specId === scope ? local : stripNamespace(i.specId, scope) } : {}
+  }));
+  return { root: top, scope, issues };
+}
+function stripNamespace(text2, scope) {
+  const prefix = `${scope}::`;
+  let out = "";
+  let from = 0;
+  for (let at = text2.indexOf(prefix); at !== -1; at = text2.indexOf(prefix, from)) {
+    const atBoundary = at === 0 || !isIdChar(text2[at - 1]);
+    out += text2.slice(from, at) + (atBoundary ? "" : prefix);
+    from = at + prefix.length;
+  }
+  return out + text2.slice(from);
+}
+function isIdChar(ch) {
+  return ch >= "a" && ch <= "z" || ch >= "A" && ch <= "Z" || ch >= "0" && ch <= "9" || ch === "_" || ch === "-" || ch === "." || ch === ":";
+}
+function isWithinOrEqual(dir, target) {
+  const rel2 = path18.relative(dir, target);
+  return rel2 === "" || !rel2.startsWith("..") && !path18.isAbsolute(rel2);
+}
+function dedupeIssues(list2) {
+  const seen = /* @__PURE__ */ new Set();
+  return list2.filter((i) => {
+    const key = `${i.code}|${i.specId ?? ""}|${i.message}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
 function settledStatusBearing(loaded) {
   let settled;
   try {
@@ -15126,7 +15168,7 @@ function settledStatusBearing(loaded) {
 function validateAsComplete(options) {
   return validateSddTree({ ...options ?? {}, treatAllAsComplete: true });
 }
-var path18, SUBPROJECT_REFERENCE_CODES, SUBPROJECT_CONFORMANCE_CODES;
+var path18, SUBPROJECT_REFERENCE_CODES;
 var init_validation = __esm({
   "src/core/validation.ts"() {
     "use strict";
@@ -15152,16 +15194,6 @@ var init_validation = __esm({
       "CROSS_SUBSYSTEM_NON_ADAPTER",
       "CROSS_TREE_REF_UNRESOLVED"
     ]);
-    SUBPROJECT_CONFORMANCE_CODES = /* @__PURE__ */ new Set([
-      "MISSING_SOURCE_FILE",
-      "SOURCE_PATH_ESCAPES_ROOT",
-      "MISSING_SOURCE_PATH",
-      "UNREALIZED_METHOD",
-      "CONFORMANCE_ANALYSIS_SKIPPED",
-      "CONFORMANCE_DEGRADED",
-      "UNDECLARED_DEPENDENCY",
-      "UNREALIZED_DEPENDENCY"
-    ]);
   }
 });
 
@@ -15991,6 +16023,19 @@ function stripNamespaceFromImplementation(spec, prefix) {
     }))
   };
 }
+function childRelativeFilePaths(spec, authoringRoot, childRoot) {
+  const reexpress = (p) => {
+    if (path19.isAbsolute(p)) return p;
+    const rel2 = path19.relative(childRoot, path19.resolve(authoringRoot, p));
+    const inside = rel2 !== "" && rel2 !== ".." && !rel2.startsWith(`..${path19.sep}`) && !path19.isAbsolute(rel2);
+    return inside ? rel2.replace(/\\/g, "/") : p;
+  };
+  return {
+    ...spec,
+    ...spec.sourcePath ? { sourcePath: reexpress(spec.sourcePath) } : {},
+    ...spec.simPath ? { simPath: reexpress(spec.simPath) } : {}
+  };
+}
 function stripNamespaceFromType(spec, prefix) {
   return {
     ...spec,
@@ -16309,6 +16354,18 @@ var init_specs2 = __esm({
         this.lastSignatureCheckMs = Date.now();
         return this.cachedIndex;
       }
+      /**
+       * The id a scan-time loader issue is anchored to: the refused spec's own id
+       * when the file got far enough to carry one, else its name on disk (the
+       * containing directory in the nested layout, where every file is `.index` /
+       * `.interface`), qualified into the mount's namespace exactly as the loader
+       * qualifies the spec itself — so scoping a validate to a mount keeps it.
+       */
+      loaderIssueSpecId(file, rawId, namespacePrefix) {
+        const stem2 = path19.basename(file, ".yaml");
+        const local = rawId ?? (stem2.startsWith(".") ? path19.basename(path19.dirname(file)) : stem2);
+        return namespacePrefix ? qualifyId(local, namespacePrefix, this.rootSubsystems) : local;
+      }
       scanSpecsForProject(projectDir, namespacePrefix, visitedDirs, maxDepth, currentDepth) {
         const index = emptyIndex();
         const projectPaths = aiPathsAt(projectDir);
@@ -16322,6 +16379,7 @@ var init_specs2 = __esm({
           const normFile = path19.normalize(file);
           if (normFile === systemYaml) continue;
           let detectedType = "spec";
+          let rawId;
           try {
             const raw = readYamlFile(file);
             if (raw === null || typeof raw !== "object") {
@@ -16329,10 +16387,12 @@ var init_specs2 = __esm({
                 severity: "error",
                 code: "INVALID_YAML",
                 message: `Spec file "${file}" is not a valid YAML object or is empty.`,
-                specId: path19.basename(file, ".yaml")
+                specId: this.loaderIssueSpecId(file, void 0, namespacePrefix)
               });
               continue;
             }
+            const idField = raw.id;
+            if (typeof idField === "string" && idField) rawId = idField;
             if ("parentSystem" in raw) {
               detectedType = "subsystem";
               const parsed = SubsystemSpecSchema.parse(raw);
@@ -16384,16 +16444,15 @@ var init_specs2 = __esm({
                 severity: "error",
                 code: "UNKNOWN_SPEC_TYPE",
                 message: `Spec file "${file}" does not match any recognized L1-L4 schema structure.`,
-                specId: path19.basename(file, ".yaml")
+                specId: this.loaderIssueSpecId(file, rawId, namespacePrefix)
               });
             }
           } catch (e) {
-            const filename = path19.basename(file, ".yaml");
             this.loaderIssues.push({
               severity: "error",
               code: "SCHEMA_VALIDATION_ERROR",
               message: `Failed to parse ${detectedType} spec "${file}": ${e.message || String(e)}`,
-              specId: filename
+              specId: this.loaderIssueSpecId(file, rawId, namespacePrefix)
             });
           }
         }
@@ -16875,7 +16934,11 @@ var init_specs2 = __esm({
       }
       prepareImplementationForWrite(spec) {
         const prefix = this.writePrefixFor(spec.id);
-        return prefix ? stripNamespaceFromImplementation(spec, prefix) : spec;
+        if (!prefix) return spec;
+        const stripped = stripNamespaceFromImplementation(spec, prefix);
+        const mount = this.getSubprojectPrefix(spec.id);
+        const childRoot = mount ? this.resolveSubprojectForNamespace(mount) : null;
+        return childRoot ? childRelativeFilePaths(stripped, this.rootDir, childRoot) : stripped;
       }
       prepareTypeForWrite(spec) {
         const prefix = this.writePrefixFor(spec.id);
@@ -18174,6 +18237,7 @@ function externalizeSubsystem(subsystemId, projectPath) {
   });
   ensureDir(path20.dirname(childFooDir));
   fs14.renameSync(fooDir, childFooDir);
+  rebaseImplementationPaths(childFooDir, parentRoot, childDir);
   patchSubsystemIndex(path20.join(childFooDir, ".index.yaml"), (s) => {
     s.parentSystem = childSystemName;
     delete s.projectPath;
@@ -18224,6 +18288,7 @@ function internalizeSubsystem(subsystemId) {
   fs14.rmSync(fooDir, { recursive: true, force: true });
   ensureDir(path20.dirname(fooDir));
   fs14.renameSync(childFooDir, fooDir);
+  rebaseImplementationPaths(fooDir, childDir, parentRoot);
   patchSubsystemIndex(path20.join(fooDir, ".index.yaml"), (s) => {
     s.parentSystem = parentSystemName;
     delete s.projectPath;
@@ -18324,6 +18389,28 @@ function rewriteRefsInDir(specsDir, renameMap, excludeDir) {
     if (changed) writeYamlFile(file, raw);
   }
 }
+function rebaseImplementationPaths(specsDir, fromRoot, toRoot) {
+  for (const file of listFilesRecursive(specsDir, ".yaml")) {
+    let raw;
+    try {
+      raw = readYamlFile(file);
+    } catch {
+      continue;
+    }
+    if (!raw || typeof raw !== "object" || !("contract" in raw)) continue;
+    let changed = false;
+    for (const key of ["sourcePath", "simPath"]) {
+      const p = raw[key];
+      if (typeof p !== "string" || p === "" || path20.isAbsolute(p)) continue;
+      const next = toPosixPath(path20.relative(toRoot, path20.resolve(fromRoot, p)));
+      if (next !== p) {
+        raw[key] = next;
+        changed = true;
+      }
+    }
+    if (changed) writeYamlFile(file, raw);
+  }
+}
 function patchSubsystemIndex(indexPath, mutate) {
   if (!fs14.existsSync(indexPath)) return;
   const raw = readYamlFile(indexPath);
@@ -23578,7 +23665,7 @@ NOTICE:
     name: import_zod10.z.string().describe("Human-readable implementation name"),
     description: import_zod10.z.string().describe("Implementation details"),
     contract: import_zod10.z.string().describe("The L3 Interface contract ID this implements"),
-    sourcePath: import_zod10.z.string().optional().describe("Optional: target source code file path relative to project root"),
+    sourcePath: import_zod10.z.string().optional().describe("Optional: target source code file path relative to project root \u2014 for a chained subproject's implementation (qualified id), relative to that subproject's root; a path given relative to this root that lands inside the subproject is re-expressed for you"),
     simPath: import_zod10.z.string().optional().describe("Optional: the committed integration-sim harness file (project-relative; N:1 sharing allowed). The validator proves it exists and its import graph wires the REAL modules (this component + each direct dependency; technology adapters may stay faked) \u2014 running it is CI's job. Declaring the first simPath in a subsystem activates MISSING_INTEGRATION_SIM for its other complete non-leaf implementations"),
     technologies: import_zod10.z.array(import_zod10.z.string()).optional().describe(`External technologies this implementation binds to (e.g. ["mysql"]) \u2014 declares this component's ownership tree as the technology's home; references outside it are flagged (TECH_LEAKAGE) and contract identifiers must stay intent-language. Only for Adapter/Store/Registry/Index components.`),
     detail: detailEnum.optional().describe("Spec-level narrative detail default for all methods"),
@@ -23767,7 +23854,8 @@ NOTICE:
         return json({
           valid: result.valid,
           errors: result.issues.filter((i) => i.severity === "error"),
-          warnings: result.issues.filter((i) => i.severity === "warning")
+          warnings: result.issues.filter((i) => i.severity === "warning"),
+          ...result.resolvedThrough ? { resolvedThrough: result.resolvedThrough } : {}
         });
       } catch (e) {
         return errText(String(e));
@@ -25189,19 +25277,19 @@ function commitStagedTree(stagingDir, destDir, roots, backupExisting) {
   const backupDir = path28.join(root, BACKUP_DIR, timestampSlug());
   let backedUp = false;
   for (const rootRel of roots) {
-    const relative14 = rootRel === "." ? "" : rootRel;
-    const stagedSpecDir = path28.join(stagingDir, relative14, ".wai");
+    const relative15 = rootRel === "." ? "" : rootRel;
+    const stagedSpecDir = path28.join(stagingDir, relative15, ".wai");
     if (!fs18.existsSync(stagedSpecDir)) continue;
-    const liveSpecDir = liveSpecDirFor(path28.join(root, relative14));
+    const liveSpecDir = liveSpecDirFor(path28.join(root, relative15));
     if (backupExisting && liveSpecDir && fs18.existsSync(liveSpecDir)) {
-      const backupTarget = path28.join(backupDir, relative14, path28.basename(liveSpecDir));
+      const backupTarget = path28.join(backupDir, relative15, path28.basename(liveSpecDir));
       fs18.mkdirSync(path28.dirname(backupTarget), { recursive: true });
       fs18.renameSync(liveSpecDir, backupTarget);
       backedUp = true;
     } else if (liveSpecDir && fs18.existsSync(liveSpecDir)) {
       fs18.rmSync(liveSpecDir, { recursive: true, force: true });
     }
-    const target = path28.join(root, relative14, ".wai");
+    const target = path28.join(root, relative15, ".wai");
     fs18.mkdirSync(path28.dirname(target), { recursive: true });
     if (fs18.existsSync(target)) fs18.rmSync(target, { recursive: true, force: true });
     fs18.renameSync(stagedSpecDir, target);
@@ -26168,7 +26256,6 @@ function isCiDraftWaivable(issue2) {
   if (issue2.severity !== "warning") return false;
   if (issue2.code === "DRAFT_COMPONENT_WARNING") return true;
   if (issue2.code === "UNUSED_COMPONENT") return issue2.draftContext === true;
-  if (issue2.crossTreeContext === true) return true;
   return false;
 }
 async function runValidate(options = {}) {
@@ -26233,6 +26320,11 @@ async function runValidate(options = {}) {
       scopeSubsystem: options.subsystem,
       recursive: options.recursive ?? true
     });
+    if (sddResult.resolvedThrough) {
+      logger.info(
+        `Chained subproject \u2014 verified through the parent project at ${sddResult.resolvedThrough.root} (mount "${sddResult.resolvedThrough.scope}").`
+      );
+    }
     if (sddResult.issues.length === 0) {
       logger.success("Spec tree is valid and component type boundaries are enforced.");
     } else {
@@ -26427,14 +26519,14 @@ var http = __toESM(require("http"));
 var https = __toESM(require("https"));
 init_defaults();
 function downloadFile(url, dest) {
-  return new Promise((resolve29, reject) => {
+  return new Promise((resolve30, reject) => {
     const file = fs22.createWriteStream(dest);
     const get4 = url.startsWith("https://") ? https.get : http.get;
     get4(url, { headers: { "User-Agent": `wairon/${WAIRON_VERSION}` }, agent: false }, (res) => {
       if (res.statusCode === 301 || res.statusCode === 302) {
         file.close();
         res.destroy();
-        downloadFile(res.headers.location, dest).then(resolve29).catch(reject);
+        downloadFile(res.headers.location, dest).then(resolve30).catch(reject);
         return;
       }
       if (res.statusCode !== 200) {
@@ -26446,7 +26538,7 @@ function downloadFile(url, dest) {
       res.pipe(file);
       file.on("finish", () => {
         res.destroy();
-        file.close(() => resolve29());
+        file.close(() => resolve30());
       });
       file.on("error", (err) => {
         res.destroy();
@@ -26623,7 +26715,7 @@ function releaseChannelLabel(tag) {
   return version.slice(dash + 1).replace(/\.\d+$/, "") || "stable";
 }
 function fetchReleases(repo) {
-  return new Promise((resolve29, reject) => {
+  return new Promise((resolve30, reject) => {
     const url = `https://api.github.com/repos/${repo}/releases?per_page=100`;
     const options = {
       headers: {
@@ -26643,7 +26735,7 @@ function fetchReleases(repo) {
           return;
         }
         try {
-          resolve29(JSON.parse(data));
+          resolve30(JSON.parse(data));
         } catch {
           reject(new Error("Failed to parse GitHub API response"));
         }
@@ -26818,7 +26910,7 @@ async function filteredCheckbox(config) {
     32,
     Math.max(...items.map((i) => i.label.length))
   );
-  return new Promise((resolve29) => {
+  return new Promise((resolve30) => {
     const checked = /* @__PURE__ */ new Set();
     let cursor = 0;
     let filterIdx = 0;
@@ -26885,7 +26977,7 @@ async function filteredCheckbox(config) {
       );
       teardown();
       const result = items.filter((_, idx) => checked.has(idx)).map((i) => i.value);
-      resolve29(result);
+      resolve30(result);
     }
     function abort() {
       process.stdout.write("\n");
@@ -35085,7 +35177,7 @@ async function awaitApproval(cfg, credential, requestId, timeoutSeconds) {
   let current2 = req;
   while (current2.status === "pending" && Date.now() < deadline) {
     const remaining = deadline - Date.now();
-    await new Promise((resolve29) => setTimeout(resolve29, Math.min(AWAIT_POLL_INTERVAL_MS, remaining)));
+    await new Promise((resolve30) => setTimeout(resolve30, Math.min(AWAIT_POLL_INTERVAL_MS, remaining)));
     expirePendingApprovals(cfg.dataDir, (/* @__PURE__ */ new Date()).toISOString());
     current2 = getApprovalRequestById(cfg.dataDir, requestId) ?? current2;
   }
@@ -36312,7 +36404,7 @@ var ShareSnapshotIndex = class {
 function putSnapshot(dataDir, snapshot) {
   return new ShareSnapshotRegistry(new ShareSnapshotStore(dataDir)).put(snapshot);
 }
-function getSnapshot2(dataDir, snapshotId) {
+function getSnapshot(dataDir, snapshotId) {
   return new ShareSnapshotIndex(new ShareSnapshotStore(dataDir)).get(snapshotId);
 }
 function getSnapshotArtifact(dataDir, snapshotId, kind, portalId) {
@@ -40043,7 +40135,9 @@ async function handleMcpRequest(cfg, req, res, body, credential) {
     });
     return;
   }
-  await runWithProjectRoot(binding.rootPath, async () => {
+  const topRoot = existingProjectRoot(cfg.dataDir, binding.projectId) ?? binding.rootPath;
+  const parentReach = principal.projects.includes("*") || principal.projects.includes(binding.projectId);
+  await runWithProjectBinding(binding.rootPath, { topRoot, parentReach }, async () => {
     const projectId = binding.projectId;
     const subproject = binding.subproject;
     const confinementError = subprojectConfinementError(projectId, subproject, body);
@@ -40134,7 +40228,7 @@ function resolveSharedView(cfg, token, meta) {
     record(cfg.dataDir, link?.id ?? "", meta, check.outcome);
     return { found: false, outcome: check.outcome };
   }
-  const snapshot = getSnapshot2(cfg.dataDir, check.link.snapshotId);
+  const snapshot = getSnapshot(cfg.dataDir, check.link.snapshotId);
   record(cfg.dataDir, check.link.id, meta, "served");
   return {
     found: true,
@@ -41343,11 +41437,11 @@ async function runServe(options = {}) {
   logger.info(`  data dir:    ${import_chalk17.default.gray(cfg.dataDir)}`);
   logger.blank();
   logger.info("Press Ctrl+C to stop.");
-  await new Promise((resolve29) => {
+  await new Promise((resolve30) => {
     const shutdown = () => {
       logger.info("Shutting down\u2026");
       handle.close();
-      resolve29();
+      resolve30();
     };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
@@ -41412,11 +41506,11 @@ async function runDev(options = {}) {
   logger.blank();
   logger.info("An agent edits specs; refresh the page to see the live graph. Press Ctrl+C to stop.");
   if (options.open) openBrowser(url);
-  await new Promise((resolve29) => {
+  await new Promise((resolve30) => {
     const shutdown = () => {
       logger.info("Shutting down\u2026");
       handle.close();
-      resolve29();
+      resolve30();
     };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
@@ -41967,16 +42061,6 @@ async function runSurface(action, options = {}) {
       }
       return;
     }
-    case "generate-children": {
-      const written = generateChildSnapshots();
-      if (!written.length) {
-        logger.info("Delivered surfaces are already up to date \u2014 nothing rewritten.");
-        return;
-      }
-      logger.success(`Updated ${written.length} delivered surface(s):`);
-      for (const p of written) logger.info(`  ${p}`);
-      return;
-    }
     case "externals": {
       const entries = listExternalInterfaces();
       if (!entries.length) {
@@ -41991,8 +42075,22 @@ async function runSurface(action, options = {}) {
       }
       return;
     }
+    case "pin": {
+      const written = pinFamilySurfaces();
+      if (written === null) {
+        logger.info("This project is not a chained subproject \u2014 there is no parent family to pin.");
+        return;
+      }
+      if (!written.length) {
+        logger.info("Pinned family surfaces are already up to date \u2014 nothing rewritten.");
+        return;
+      }
+      logger.success(`Pinned ${written.length} family surface(s) from the parent:`);
+      for (const p of written) logger.info(`  ${p}`);
+      return;
+    }
     default:
-      throw new WaironError(`Unknown surface action "${action}" (supported: export, import, list, generate-children, externals).`);
+      throw new WaironError(`Unknown surface action "${action}" (supported: export, import, list, externals, pin).`);
   }
 }
 
@@ -42732,12 +42830,6 @@ async function runLock2(options) {
     logger.info("Cancelled. Nothing was changed.");
     return;
   }
-  const childPaths = generateChildSnapshots();
-  if (childPaths.length > 0) {
-    logger.blank();
-    logger.success(`Updated ${childPaths.length} delivered surface(s) in the chained children:`);
-    for (const p of childPaths) logger.info(`  ${p}`);
-  }
   logger.blank();
   await runGenerate({ domain: options.subsystem });
   logger.blank();
@@ -43000,7 +43092,7 @@ mcpCmd.command("status").description("Show whether the wairon MCP server is regi
 program.command("produce <target>").description("project the local project's specs to a producer target (notion | miro)").option("--page <id>", "parent page/board id in the target").option("--token <token>", "integration token (else env, else interactive prompt)").action(async (target, opts) => {
   await runProduce(target, { page: opts.page, token: opts.token });
 });
-program.command("surface <action>").description("public surface exchange: export | import | list | generate-children | externals").option("--audience <level>", "export ceiling: project | department | instance | partner | external (default instance)").option("--format <fmt>", "export format: native | openapi (default native)").option("--out <path>", "export output path (else print)").option("--portal <id>", "export: select one portal's OpenAPI spec (a multi-portal project renders one document per portal)").option("--source <path>", "import: the surface document (native snapshot YAML or OpenAPI)").option("--origin <origin>", "import provenance: exchanged | authored (default authored)").action(async (action, opts) => {
+program.command("surface <action>").description("public surface exchange: export | import | list | externals | pin").option("--audience <level>", "export ceiling: project | department | instance | partner | external (default instance)").option("--format <fmt>", "export format: native | openapi (default native)").option("--out <path>", "export output path (else print)").option("--portal <id>", "export: select one portal's OpenAPI spec (a multi-portal project renders one document per portal)").option("--source <path>", "import: the surface document (native snapshot YAML or OpenAPI)").option("--origin <origin>", "import provenance: exchanged | authored (default authored)").action(async (action, opts) => {
   await runSurface(action, {
     audience: opts.audience,
     format: opts.format,