amalgm 0.1.154 → 0.1.155

package/runtime/scripts/amalgm-mcp/agent-bundles/graph.js

@@ -4,12 +4,9 @@ const crypto = require('crypto');
 
 const { normalizeAgentConfig } = require('../agent-config/schema');
 
-// Agent-only bundles keep the legacy kind so older runtimes can still install
-// them; bundles that carry automations or apps use the general kind so older
-// runtimes reject them outright instead of silently dropping primitives.
 const BUNDLE_KIND = 'amalgm.bundle';
-const LEGACY_AGENT_BUNDLE_KIND = 'amalgm.agent.bundle';
-const BUNDLE_SCHEMA_VERSION = 1;
+const BUNDLE_SCHEMA_VERSION = 2;
+const HEAD_TYPES = new Set(['agent', 'automation', 'app', 'tool']);
 const GRAPH_ELEMENT_ORDER = {
   agent: 0,
   automation: 1,
@@ -41,8 +38,7 @@ function uniqueStrings(values) {
 }
 
 function addUnique(target, value) {
-  if (!value) return;
-  if (!target.includes(value)) target.push(value);
+  if (value && !target.includes(value)) target.push(value);
 }
 
 function stableDigest(value) {
@@ -62,12 +58,12 @@ function skillFingerprint(skill) {
     return value ? `string:${value}` : '';
   }
   if (!isObject(skill)) return '';
-  const id = typeof skill.id === 'string' ? skill.id.trim() : '';
+  const id = cleanEntryId(skill.id);
   if (id) return `id:${id}`;
-  const path = typeof skill.path === 'string' ? skill.path.trim() : '';
+  const path = cleanEntryId(skill.path);
   if (path) return `path:${path}`;
-  const name = typeof skill.name === 'string' ? skill.name.trim() : '';
-  const content = typeof skill.content === 'string' ? skill.content.trim() : '';
+  const name = cleanEntryId(skill.name);
+  const content = cleanEntryId(skill.content);
   if (name && content) return `name-content:${name}:${content}`;
   if (name) return `name:${name}`;
   if (content) return `content:${content}`;
@@ -82,20 +78,18 @@ function skillElementId(skill) {
 function skillLabel(skill) {
   if (typeof skill === 'string') return skill.trim() || 'Skill';
   if (!isObject(skill)) return 'Skill';
-  const id = typeof skill.id === 'string' ? skill.id.trim() : '';
-  const name = typeof skill.name === 'string' ? skill.name.trim() : '';
-  const path = typeof skill.path === 'string' ? skill.path.trim() : '';
+  const name = cleanEntryId(skill.name);
   if (name) return name;
+  const path = cleanEntryId(skill.path);
   if (path) return path.split('/').filter(Boolean).pop() || path;
+  const id = cleanEntryId(skill.id);
   if (id) return id;
-  const content = typeof skill.content === 'string' ? skill.content.trim() : '';
-  return content.slice(0, 60) || 'Skill';
+  return cleanEntryId(skill.content).slice(0, 60) || 'Skill';
 }
 
 function compareGraphElements(left, right) {
-  const order = (GRAPH_ELEMENT_ORDER[left.type] || 99) - (GRAPH_ELEMENT_ORDER[right.type] || 99);
-  if (order !== 0) return order;
-  return String(left.id).localeCompare(String(right.id));
+  return (GRAPH_ELEMENT_ORDER[left.type] ?? 99) - (GRAPH_ELEMENT_ORDER[right.type] ?? 99)
+    || String(left.id).localeCompare(String(right.id));
 }
 
 function compareGraphEdges(left, right) {
@@ -104,38 +98,13 @@ function compareGraphEdges(left, right) {
     || String(left.to).localeCompare(String(right.to));
 }
 
-function pushGraphElement(elements, element) {
-  if (!element?.id) return;
-  if (!elements.has(element.id)) elements.set(element.id, element);
-}
-
-function pushGraphEdge(edges, edge) {
-  if (!edge?.from || !edge?.to || !edge?.kind) return;
-  const key = `${edge.from}::${edge.kind}::${edge.to}`;
-  if (!edges.has(key)) edges.set(key, edge);
-}
-
-function collectSkillRecords(bundleAgents) {
-  const byKey = new Map();
-  for (const entry of bundleAgents) {
-    for (const skill of entry.config.skills || []) {
-      const key = skillFingerprint(skill);
-      if (!key) continue;
-      byKey.set(key, cloneJson(skill));
-    }
-  }
-  return [...byKey.values()];
-}
-
 function cleanEntryId(value) {
   return typeof value === 'string' ? value.trim() : '';
 }
 
 function agentEntryId(entry) {
   if (!isObject(entry)) return '';
-  const sourceAgentId = typeof entry.sourceAgentId === 'string' ? entry.sourceAgentId.trim() : '';
-  if (sourceAgentId) return sourceAgentId;
-  return typeof entry.agent?.sourceAgentId === 'string' ? entry.agent.sourceAgentId.trim() : '';
+  return cleanEntryId(entry.sourceAgentId) || cleanEntryId(entry.agent?.sourceAgentId);
 }
 
 function automationEntryId(entry) {
@@ -146,294 +115,294 @@ function appEntryId(entry) {
   return isObject(entry) ? cleanEntryId(entry.sourceAppId) : '';
 }
 
-/**
- * Tools shared as top-level primitives (not just dependencies of agents or
- * automations). The bundle's explicit heads are the single source of truth.
- */
+function toolEntryId(entry) {
+  return isObject(entry) ? cleanEntryId(entry.id) : '';
+}
+
+function actionEntryId(entry) {
+  return isObject(entry) ? cleanEntryId(entry.id) : '';
+}
+
+function collectSkillRecords(bundleAgents) {
+  const byKey = new Map();
+  for (const entry of bundleAgents) {
+    const config = normalizeAgentConfig(entry?.config || {});
+    for (const skill of config.skills || []) {
+      const key = skillFingerprint(skill);
+      if (key && !byKey.has(key)) byKey.set(key, cloneJson(skill));
+    }
+  }
+  return [...byKey.values()];
+}
+
 function standaloneToolIds(bundle) {
-  const heads = Array.isArray(bundle?.heads) ? bundle.heads : [];
-  return uniqueStrings(heads
+  return uniqueStrings((Array.isArray(bundle?.heads) ? bundle.heads : [])
     .filter((head) => isObject(head) && cleanEntryId(head.type) === 'tool')
     .map((head) => cleanEntryId(head.id)));
 }
 
-/**
- * App elements carry the portable record and a file manifest; file contents
- * stay in bundle.apps[] so the graph remains cheap to render.
- */
-function appElementData(entry) {
-  return {
-    sourceAppId: appEntryId(entry),
-    manifest: cloneJson(entry.manifest || {}),
-    app: cloneJson(entry.app || {}),
-    files: (Array.isArray(entry.files) ? entry.files : []).map((file) => ({
-      path: file.path,
-      size: file.size,
-      encoding: file.encoding,
-      ...(file.executable ? { executable: true } : {}),
-    })),
-    totalBytes: entry.totalBytes || 0,
-    skipped: cloneJson(entry.skipped || []),
-  };
+function assertUniqueRecords(label, records, idForRecord) {
+  const seen = new Set();
+  for (const record of records) {
+    const id = idForRecord(record);
+    if (!id) throw new Error(`${label} entries must include ids`);
+    if (seen.has(id)) throw new Error(`Bundle contains duplicate ${label} id: ${id}`);
+    seen.add(id);
+  }
+}
+
+function assertCanonicalBundle(bundle) {
+  if (!isObject(bundle)) throw new Error('bundle must be an object');
+  if (bundle.kind !== BUNDLE_KIND) {
+    throw new Error(`Unsupported bundle kind: ${bundle.kind || 'unknown'}`);
+  }
+  if (bundle.schemaVersion !== BUNDLE_SCHEMA_VERSION) {
+    throw new Error(`Unsupported bundle schema version: ${bundle.schemaVersion || 'unknown'}`);
+  }
+
+  const agents = Array.isArray(bundle.agents) ? bundle.agents : [];
+  const automations = Array.isArray(bundle.automations) ? bundle.automations : [];
+  const apps = Array.isArray(bundle.apps) ? bundle.apps : [];
+  const tools = Array.isArray(bundle.tools) ? bundle.tools : [];
+  const actions = Array.isArray(bundle.toolActions) ? bundle.toolActions : [];
+  const skills = Array.isArray(bundle.skills) ? bundle.skills : [];
+  const heads = Array.isArray(bundle.heads) ? bundle.heads : [];
+
+  assertUniqueRecords('agent', agents, agentEntryId);
+  assertUniqueRecords('automation', automations, automationEntryId);
+  assertUniqueRecords('app', apps, appEntryId);
+  assertUniqueRecords('tool', tools, toolEntryId);
+  assertUniqueRecords('tool action', actions, actionEntryId);
+  assertUniqueRecords('skill', skills, skillFingerprint);
+  assertUniqueRecords('head', heads, (head) => {
+    const type = cleanEntryId(head?.type);
+    const id = cleanEntryId(head?.id);
+    if (!HEAD_TYPES.has(type)) return '';
+    return `${type}:${id}`;
+  });
+  if (heads.length === 0) throw new Error('bundle must include at least one head');
+
+  const missingTools = uniqueStrings(bundle.requires?.missingTools);
+  if (missingTools.length > 0) {
+    throw new Error(`Bundle is missing tools: ${missingTools.join(', ')}`);
+  }
 }
 
 function buildFlatAgentBundleGraph(bundle) {
+  assertCanonicalBundle(bundle);
+
+  const agents = bundle.agents || [];
+  const automations = bundle.automations || [];
+  const apps = bundle.apps || [];
+  const tools = bundle.tools || [];
+  const actions = bundle.toolActions || [];
+  const skills = bundle.skills || [];
   const elements = new Map();
   const edges = new Map();
-  const toolMap = new Map((Array.isArray(bundle.tools) ? bundle.tools : []).map((tool) => [tool.id, tool]));
-  const toolActionMap = new Map((Array.isArray(bundle.toolActions) ? bundle.toolActions : []).map((action) => [action.id, action]));
-  const systemToolIds = new Set(uniqueStrings(bundle.requires?.systemTools));
-  const missingToolIds = new Set(uniqueStrings(bundle.requires?.missingTools));
-  const skills = collectSkillRecords(bundle.agents || []);
-
-  for (const entry of bundle.agents || []) {
-    const currentAgentId = agentEntryId(entry);
-    if (!currentAgentId) continue;
-    pushGraphElement(elements, {
-      id: graphElementId('agent', currentAgentId),
-      type: 'agent',
-      label: entry.agent?.name || currentAgentId,
-      data: {
-        sourceAgentId: currentAgentId,
-        agent: cloneJson(entry.agent || {}),
-        config: cloneJson(normalizeAgentConfig(entry.config || {})),
-      },
-    });
-  }
+  const records = {
+    agent: new Map(agents.map((entry) => [agentEntryId(entry), entry])),
+    automation: new Map(automations.map((entry) => [automationEntryId(entry), entry])),
+    app: new Map(apps.map((entry) => [appEntryId(entry), entry])),
+    tool: new Map(tools.map((entry) => [toolEntryId(entry), entry])),
+    tool_action: new Map(actions.map((entry) => [actionEntryId(entry), entry])),
+    skill: new Map(skills.map((entry) => [skillElementId(entry), entry])),
+  };
 
-  for (const entry of bundle.automations || []) {
-    const currentAutomationId = automationEntryId(entry);
-    if (!currentAutomationId) continue;
-    pushGraphElement(elements, {
-      id: graphElementId('automation', currentAutomationId),
-      type: 'automation',
-      label: entry.automation?.name || currentAutomationId,
-      data: cloneJson(entry),
-    });
-  }
+  const addElement = (type, id, label) => {
+    const elementId = graphElementId(type, id);
+    elements.set(elementId, { id: elementId, type, label: label || id });
+  };
+  const addEdge = (fromType, fromId, toType, toId, kind) => {
+    const from = graphElementId(fromType, fromId);
+    const to = graphElementId(toType, toId);
+    const key = `${from}::${kind}::${to}`;
+    edges.set(key, { from, to, kind });
+  };
+  const requireRecord = (type, id, owner) => {
+    if (!records[type].has(id)) {
+      throw new Error(`${owner} references missing ${type.replace('_', ' ')}: ${id}`);
+    }
+  };
+  const addToolSelection = (ownerType, ownerId, selectedId) => {
+    if (records.tool_action.has(selectedId)) {
+      addEdge(ownerType, ownerId, 'tool_action', selectedId, 'uses-tool-action');
+      return;
+    }
+    requireRecord('tool', selectedId, `${ownerType} ${ownerId}`);
+    addEdge(ownerType, ownerId, 'tool', selectedId, 'uses-tool');
+  };
 
-  for (const entry of bundle.apps || []) {
-    const currentAppId = appEntryId(entry);
-    if (!currentAppId) continue;
-    pushGraphElement(elements, {
-      id: graphElementId('app', currentAppId),
-      type: 'app',
-      label: entry.app?.name || currentAppId,
-      data: appElementData(entry),
-    });
+  for (const entry of agents) {
+    const id = agentEntryId(entry);
+    addElement('agent', id, entry.agent?.name);
   }
-
+  for (const entry of automations) {
+    const id = automationEntryId(entry);
+    addElement('automation', id, entry.automation?.name);
+  }
+  for (const entry of apps) {
+    const id = appEntryId(entry);
+    addElement('app', id, entry.app?.name);
+  }
+  for (const tool of tools) addElement('tool', toolEntryId(tool), tool.name);
+  for (const action of actions) addElement('tool_action', actionEntryId(action), action.name);
   for (const skill of skills) {
     const elementId = skillElementId(skill);
-    if (!elementId) continue;
-    pushGraphElement(elements, {
-      id: elementId,
-      type: 'skill',
-      label: skillLabel(skill),
-      data: typeof skill === 'string' ? { value: skill } : cloneJson(skill),
-    });
+    elements.set(elementId, { id: elementId, type: 'skill', label: skillLabel(skill) });
   }
 
-  const includedToolIds = new Set();
-  const includedActionIds = new Set();
-
-  for (const entry of bundle.automations || []) {
-    const currentAutomationId = automationEntryId(entry);
-    if (!currentAutomationId) continue;
-    for (const toolId of uniqueStrings(entry.toolIds)) {
-      includedToolIds.add(toolId);
-      pushGraphEdge(edges, {
-        from: graphElementId('automation', currentAutomationId),
-        to: graphElementId('tool', toolId),
-        kind: 'uses-tool',
-      });
+  for (const entry of agents) {
+    const id = agentEntryId(entry);
+    const config = normalizeAgentConfig(entry.config || {});
+    for (const subagent of config.subagents || []) {
+      const subagentId = cleanEntryId(subagent?.agentId);
+      if (!subagentId) continue;
+      requireRecord('agent', subagentId, `agent ${id}`);
+      addEdge('agent', id, 'agent', subagentId, 'uses-subagent');
     }
-  }
-  // Tools that belong to an app render nested under it in the share sidebar;
-  // the canonical tool record still appears exactly once.
-  for (const entry of bundle.apps || []) {
-    const currentAppId = appEntryId(entry);
-    if (!currentAppId) continue;
-    for (const toolId of uniqueStrings(entry.toolIds)) {
-      includedToolIds.add(toolId);
-      pushGraphEdge(edges, {
-        from: graphElementId('app', currentAppId),
-        to: graphElementId('tool', toolId),
-        kind: 'uses-tool',
-      });
-    }
-  }
-  for (const entry of bundle.agents || []) {
-    const currentAgentId = agentEntryId(entry);
-    if (!currentAgentId) continue;
-    const currentConfig = normalizeAgentConfig(entry.config || {});
-
-    for (const subagent of currentConfig.subagents || []) {
-      if (!subagent?.agentId) continue;
-      pushGraphEdge(edges, {
-        from: graphElementId('agent', currentAgentId),
-        to: graphElementId('agent', subagent.agentId),
-        kind: 'uses-subagent',
-      });
+    for (const selectedId of uniqueStrings(config.loadout?.toolIds)) {
+      addToolSelection('agent', id, selectedId);
     }
-
-    for (const selectedId of uniqueStrings(currentConfig.loadout?.toolIds)) {
-      const selectedAction = toolActionMap.get(selectedId);
-      if (selectedAction) {
-        includedActionIds.add(selectedAction.id);
-        includedToolIds.add(selectedAction.toolId);
-        pushGraphEdge(edges, {
-          from: graphElementId('agent', currentAgentId),
-          to: graphElementId('tool_action', selectedAction.id),
-          kind: 'uses-tool-action',
-        });
-        continue;
+    for (const skill of config.skills || []) {
+      const elementId = skillElementId(skill);
+      if (!records.skill.has(elementId)) {
+        throw new Error(`agent ${id} references missing skill: ${skillLabel(skill)}`);
       }
+      const skillId = elementId.slice('skill:'.length);
+      addEdge('agent', id, 'skill', skillId, 'uses-skill');
+    }
+  }
 
-      includedToolIds.add(selectedId);
-      pushGraphEdge(edges, {
-        from: graphElementId('agent', currentAgentId),
-        to: graphElementId('tool', selectedId),
-        kind: 'uses-tool',
-      });
+  for (const entry of automations) {
+    const id = automationEntryId(entry);
+    for (const selectedId of uniqueStrings(entry.toolIds)) {
+      addToolSelection('automation', id, selectedId);
     }
+  }
 
-    for (const skill of currentConfig.skills || []) {
-      const targetId = skillElementId(skill);
-      if (!targetId) continue;
-      pushGraphEdge(edges, {
-        from: graphElementId('agent', currentAgentId),
-        to: targetId,
-        kind: 'uses-skill',
-      });
+  for (const entry of apps) {
+    const id = appEntryId(entry);
+    for (const toolId of uniqueStrings(entry.toolIds)) {
+      requireRecord('tool', toolId, `app ${id}`);
+      addEdge('app', id, 'tool', toolId, 'provides-tool');
     }
   }
 
-  // Every tool in bundle.tools gets an element — standalone tool heads are
-  // not referenced by any agent or automation edge but must still resolve.
-  const toolElementIds = new Set([...includedToolIds, ...toolMap.keys()]);
-  for (const toolId of toolElementIds) {
-    const tool = toolMap.get(toolId);
-    pushGraphElement(elements, {
-      id: graphElementId('tool', toolId),
-      type: 'tool',
-      label: tool?.name || toolId,
-      data: tool
-        ? cloneJson(tool)
-        : {
-            id: toolId,
-            name: toolId,
-            origin: systemToolIds.has(toolId) ? 'system' : missingToolIds.has(toolId) ? 'missing' : 'unknown',
-          },
-    });
+  for (const tool of tools) {
+    const toolId = toolEntryId(tool);
+    const appId = cleanEntryId(tool.appId);
+    if (appId) {
+      requireRecord('app', appId, `tool ${toolId}`);
+      addEdge('tool', toolId, 'app', appId, 'requires-app');
+    }
   }
 
-  for (const action of Array.isArray(bundle.toolActions) ? bundle.toolActions : []) {
-    if (!toolElementIds.has(action.toolId)) continue;
-    includedActionIds.add(action.id);
-    pushGraphElement(elements, {
-      id: graphElementId('tool_action', action.id),
-      type: 'tool_action',
-      label: action.name || action.id,
-      data: cloneJson(action),
-    });
-    pushGraphEdge(edges, {
-      from: graphElementId('tool_action', action.id),
-      to: graphElementId('tool', action.toolId),
-      kind: 'action-of',
-    });
+  for (const action of actions) {
+    const actionId = actionEntryId(action);
+    const toolId = cleanEntryId(action.toolId);
+    requireRecord('tool', toolId, `tool action ${actionId}`);
+    addEdge('tool', toolId, 'tool_action', actionId, 'has-action');
+    addEdge('tool_action', actionId, 'tool', toolId, 'action-of');
+    const appId = cleanEntryId(action.appId);
+    if (appId) {
+      requireRecord('app', appId, `tool action ${actionId}`);
+      addEdge('tool_action', actionId, 'app', appId, 'requires-app');
+    }
   }
 
+  const headIds = bundle.heads.map((head) => {
+    const elementId = graphElementId(cleanEntryId(head.type), cleanEntryId(head.id));
+    if (!elements.has(elementId)) throw new Error(`bundle head references missing element: ${elementId}`);
+    return elementId;
+  });
+
   return {
-    headIds: bundleHeadIds(bundle, elements),
+    headIds,
     elements: [...elements.values()].sort(compareGraphElements),
     edges: [...edges.values()].sort(compareGraphEdges),
   };
 }
 
-/**
- * Heads are the user-facing roots of the bundle. Explicit bundle.heads win;
- * otherwise fall back to the legacy single agent root plus every automation
- * and app entry (those are always top-level).
- */
-function bundleHeadIds(bundle, elements) {
-  const headIds = [];
-  const explicitHeads = Array.isArray(bundle.heads) ? bundle.heads : [];
-  for (const head of explicitHeads) {
-    const type = cleanEntryId(head?.type);
-    const id = cleanEntryId(head?.id);
-    if (!type || !id) continue;
-    const elementId = graphElementId(type, id);
-    if (elements.has(elementId) && !headIds.includes(elementId)) headIds.push(elementId);
+function reachableElementIds(bundle) {
+  const outgoing = new Map();
+  for (const edge of bundle.edges || []) {
+    const targets = outgoing.get(edge.from) || [];
+    targets.push(edge.to);
+    outgoing.set(edge.from, targets);
   }
-  if (headIds.length > 0) return headIds;
-
-  const firstAgentId = agentEntryId(bundle.agents?.[0]);
-  const rootAgentId = cleanEntryId(bundle.rootAgentId) || firstAgentId;
-  if (rootAgentId && elements.has(graphElementId('agent', rootAgentId))) {
-    headIds.push(graphElementId('agent', rootAgentId));
-  }
-  for (const entry of bundle.automations || []) {
-    const id = automationEntryId(entry);
-    if (id) headIds.push(graphElementId('automation', id));
-  }
-  for (const entry of bundle.apps || []) {
-    const id = appEntryId(entry);
-    if (id) headIds.push(graphElementId('app', id));
+  const reachable = new Set();
+  const pending = [...(bundle.headIds || [])];
+  while (pending.length > 0) {
+    const id = pending.pop();
+    if (reachable.has(id)) continue;
+    reachable.add(id);
+    pending.push(...(outgoing.get(id) || []));
   }
-  return [...new Set(headIds)];
+  return reachable;
 }
 
 function assertClosedFlatBundleGraph(bundle) {
   if (!Array.isArray(bundle.headIds) || bundle.headIds.length === 0) {
     throw new Error('bundle graph must include at least one head');
   }
-
   const elementIds = new Set();
   for (const element of Array.isArray(bundle.elements) ? bundle.elements : []) {
-    if (!isObject(element) || typeof element.id !== 'string' || !element.id.trim()) {
-      throw new Error('bundle graph elements must include non-empty ids');
+    if (!isObject(element) || !cleanEntryId(element.id) || !cleanEntryId(element.type)) {
+      throw new Error('bundle graph elements must include id and type');
     }
-    if (elementIds.has(element.id)) {
-      throw new Error(`bundle graph contains duplicate element id: ${element.id}`);
+    if (Object.prototype.hasOwnProperty.call(element, 'data')) {
+      throw new Error(`bundle graph element must not copy canonical payload data: ${element.id}`);
     }
+    if (elementIds.has(element.id)) throw new Error(`bundle graph contains duplicate element id: ${element.id}`);
     elementIds.add(element.id);
   }
-
   for (const headId of bundle.headIds) {
-    if (typeof headId !== 'string' || !elementIds.has(headId)) {
-      throw new Error(`bundle graph head is missing element: ${headId}`);
-    }
+    if (!elementIds.has(headId)) throw new Error(`bundle graph head is missing element: ${headId}`);
   }
-
+  const edgeKeys = new Set();
   for (const edge of Array.isArray(bundle.edges) ? bundle.edges : []) {
-    if (!isObject(edge) || typeof edge.from !== 'string' || typeof edge.to !== 'string' || typeof edge.kind !== 'string') {
+    if (!isObject(edge) || !cleanEntryId(edge.from) || !cleanEntryId(edge.to) || !cleanEntryId(edge.kind)) {
       throw new Error('bundle graph edges must include from, to, and kind');
     }
     if (!elementIds.has(edge.from)) throw new Error(`bundle graph edge source is missing element: ${edge.from}`);
     if (!elementIds.has(edge.to)) throw new Error(`bundle graph edge target is missing element: ${edge.to}`);
+    const key = `${edge.from}::${edge.kind}::${edge.to}`;
+    if (edgeKeys.has(key)) throw new Error(`bundle graph contains duplicate edge: ${key}`);
+    edgeKeys.add(key);
+  }
+  const reachable = reachableElementIds(bundle);
+  const unreachable = [...elementIds].filter((id) => !reachable.has(id));
+  if (unreachable.length > 0) {
+    throw new Error(`bundle graph contains unreachable elements: ${unreachable.join(', ')}`);
   }
 }
 
 function withBundleGraph(bundle) {
   const graph = buildFlatAgentBundleGraph(bundle);
-  const nextBundle = {
-    ...bundle,
-    headIds: graph.headIds,
-    elements: graph.elements,
-    edges: graph.edges,
-  };
+  const rootAgentId = cleanEntryId(bundle.heads.find((head) => head?.type === 'agent')?.id) || null;
+  const nextBundle = { ...bundle, rootAgentId, ...graph };
   assertClosedFlatBundleGraph(nextBundle);
   return nextBundle;
 }
 
+function assertBundleGraphMatches(bundle) {
+  const expected = withBundleGraph({ ...bundle, headIds: undefined, elements: undefined, edges: undefined });
+  for (const field of ['rootAgentId', 'headIds', 'elements', 'edges']) {
+    if (JSON.stringify(bundle[field]) !== JSON.stringify(expected[field])) {
+      throw new Error(`bundle ${field} does not match its canonical records and connections`);
+    }
+  }
+  return bundle;
+}
+
 module.exports = {
   BUNDLE_KIND,
   BUNDLE_SCHEMA_VERSION,
-  LEGACY_AGENT_BUNDLE_KIND,
   addUnique,
   agentEntryId,
   appEntryId,
+  assertBundleGraphMatches,
+  assertCanonicalBundle,
   assertClosedFlatBundleGraph,
   automationEntryId,
   buildFlatAgentBundleGraph,
@@ -442,6 +411,8 @@ module.exports = {
   collectSkillRecords,
   isObject,
   nowIso,
+  reachableElementIds,
+  skillElementId,
   standaloneToolIds,
   uniqueStrings,
   withBundleGraph,