elanous 0.2.32 → 0.2.34

package/src/self-implement/goal-author-preservation-obligation.ts

@@ -0,0 +1,35 @@
+const EXPLICIT_OBLIGATION_MODAL = /\b(?:must|should|needs?\s+to|is\s+required\s+to)\s+/gi;
+const OBLIGATION_HARD_BOUNDARY = /[.;!?]|\s+but\s+|\s+(?:although|because|while)\s+/i;
+const COORDINATED_OBLIGATION = /\s+(?:and|or)\s+|,\s*(?:(?:and|or)\s+)?/i;
+const PRESERVATION_OBLIGATION_VERB = /^(?:preserve|remain|retain|keep|maintain)$/i;
+// ⛔⭐ 수동태 보존(`must be preserved` · `should be unchanged`)은 동사가 `be` 라 위 배제를 빠져나간다.
+//    실측 2026-08-03: `this behavior should be preserved across releases` 가 요구로 오탐됐다.
+//    ⚠️ 오탐 비용이 낮지 않다 — 이 판정은 clarification 을 만들고, 미답 clarification 은
+//    발사 전 도달 경로를 태운다(`RUN-S13`). ⇒ `be` 뒤의 분사만 좁게 더 본다.
+const PRESERVATION_PARTICIPLE = /^(?:preserved|retained|kept|maintained|unchanged|intact|stable)$/i;
+
+/** Persistent evidence remains a preservation contract; only preservation verbs are excluded from explicit modal obligations. */
+/** ⭐ 테스트가 **배포 코드**를 물게 export 한다 — 종전 회귀는 정규식을 복사해 vacuous 였다(`[T]` 반증 자기검증). */
+export function hasUnmetRequirementOutsidePreservationClause(evidence: string): boolean {
+  return explicitObligationPhrases(evidence).some((phrase) => {
+    const [verb, next] = phrase.trim().split(/\s+/, 2);
+    if (!verb) return false;
+    if (PRESERVATION_OBLIGATION_VERB.test(verb)) return false;
+    // `be preserved` / `be unchanged` 처럼 수동태로 쓴 보존은 요구가 아니다.
+    if (/^be$/i.test(verb) && next && PRESERVATION_PARTICIPLE.test(next)) return false;
+    return true;
+  });
+}
+
+/** 배제 판정에 `be <분사>` 를 보려면 동사 하나가 아니라 구가 필요하다. */
+function explicitObligationPhrases(evidence: string): string[] {
+  const modals = Array.from(evidence.matchAll(EXPLICIT_OBLIGATION_MODAL));
+  return modals.flatMap((modal, index) => {
+    const start = (modal.index ?? 0) + modal[0].length;
+    const nextModal = modals[index + 1]?.index ?? evidence.length;
+    const remaining = evidence.slice(start, nextModal);
+    const boundary = remaining.search(OBLIGATION_HARD_BOUNDARY);
+    const obligation = remaining.slice(0, boundary === -1 ? remaining.length : boundary);
+    return obligation.split(COORDINATED_OBLIGATION).map((phrase) => phrase.trim()).filter(Boolean);
+  });
+}

package/src/self-implement/goal-author.ts

@@ -54,6 +54,10 @@ import { targetScopedGoalText } from './goal-text-path-scope.js';
 import { parseReleaseNoteSection } from '../release-loop/release-note.js';
 import { declaredNewFilePaths } from './goal-new-paths.js';
 import { classifyGoalCommandExecution, type GoalCommandExecutionResult } from './goal-command-execution.js';
+import { identityLines, repositoryIdentifiers } from './goal-author-identity.js';
+export { formatSubmittedAt } from './goal-author-identity.js';
+import { hasUnmetRequirementOutsidePreservationClause } from './goal-author-preservation-obligation.js';
+export { hasUnmetRequirementOutsidePreservationClause } from './goal-author-preservation-obligation.js';
 export { classifyGoalCommandExecution } from './goal-command-execution.js';
 export type { GoalCommandExecutionKind, GoalCommandExecutionResult, GoalCommandExecutionClassification } from './goal-command-execution.js';
 
@@ -4902,59 +4906,6 @@ function preservationClarification(
   return renderedClarification(clarificationQuestions, PRESERVATION_CONTRACT_QUESTION_ID, clarificationResponses);
 }
 
-const EXPLICIT_OBLIGATION_MODAL = /\b(?:must|should|needs?\s+to|is\s+required\s+to)\s+/gi;
-const OBLIGATION_HARD_BOUNDARY = /[.;!?]|\s+but\s+|\s+(?:although|because|while)\s+/i;
-const COORDINATED_OBLIGATION = /\s+(?:and|or)\s+|,\s*(?:(?:and|or)\s+)?/i;
-const OBLIGATION_VERB = /^([a-z]+)/i;
-const PRESERVATION_OBLIGATION_VERB = /^(?:preserve|remain|retain|keep|maintain)$/i;
-// ⛔⭐ 수동태 보존(`must be preserved` · `should be unchanged`)은 동사가 `be` 라 위 배제를 빠져나간다.
-//    실측 2026-08-03: `this behavior should be preserved across releases` 가 요구로 오탐됐다.
-//    ⚠️ 오탐 비용이 낮지 않다 — 이 판정은 clarification 을 만들고, 미답 clarification 은
-//    발사 전 도달 경로를 태운다(`RUN-S13`). ⇒ `be` 뒤의 분사만 좁게 더 본다.
-const PRESERVATION_PARTICIPLE = /^(?:preserved|retained|kept|maintained|unchanged|intact|stable)$/i;
-
-/** Return finite, explicitly modal verb phrases, including verbs that share a modal through coordination. */
-function explicitObligationVerbs(evidence: string): string[] {
-  const modals = Array.from(evidence.matchAll(EXPLICIT_OBLIGATION_MODAL));
-  return modals.flatMap((modal, index) => {
-    const start = (modal.index ?? 0) + modal[0].length;
-    const nextModal = modals[index + 1]?.index ?? evidence.length;
-    const remaining = evidence.slice(start, nextModal);
-    const boundary = remaining.search(OBLIGATION_HARD_BOUNDARY);
-    const obligation = remaining.slice(0, boundary === -1 ? remaining.length : boundary);
-    return obligation.split(COORDINATED_OBLIGATION).flatMap((phrase) => {
-      const verb = OBLIGATION_VERB.exec(phrase.trim())?.[1];
-      return verb ? [verb] : [];
-    });
-  });
-}
-
-/** Persistent evidence remains a preservation contract; only preservation verbs are excluded from explicit modal obligations. */
-/** ⭐ 테스트가 **배포 코드**를 물게 export 한다 — 종전 회귀는 정규식을 복사해 vacuous 였다(`[T]` 반증 자기검증). */
-export function hasUnmetRequirementOutsidePreservationClause(evidence: string): boolean {
-  return explicitObligationPhrases(evidence).some((phrase) => {
-    const [verb, next] = phrase.trim().split(/\s+/, 2);
-    if (!verb) return false;
-    if (PRESERVATION_OBLIGATION_VERB.test(verb)) return false;
-    // `be preserved` / `be unchanged` 처럼 수동태로 쓴 보존은 요구가 아니다.
-    if (/^be$/i.test(verb) && next && PRESERVATION_PARTICIPLE.test(next)) return false;
-    return true;
-  });
-}
-
-/** 배제 판정에 `be <분사>` 를 보려면 동사 하나가 아니라 구가 필요하다. `explicitObligationVerbs` 의 형제. */
-function explicitObligationPhrases(evidence: string): string[] {
-  const modals = Array.from(evidence.matchAll(EXPLICIT_OBLIGATION_MODAL));
-  return modals.flatMap((modal, index) => {
-    const start = (modal.index ?? 0) + modal[0].length;
-    const nextModal = modals[index + 1]?.index ?? evidence.length;
-    const remaining = evidence.slice(start, nextModal);
-    const boundary = remaining.search(OBLIGATION_HARD_BOUNDARY);
-    const obligation = remaining.slice(0, boundary === -1 ? remaining.length : boundary);
-    return obligation.split(COORDINATED_OBLIGATION).map((phrase) => phrase.trim()).filter(Boolean);
-  });
-}
-
 function preservationAmbiguities(facts: CodebaseGrounding | null, groundingError: boolean): string[] {
   if (groundingError) return [];
   return (facts?.persistentEvidence ?? []).filter(hasUnmetRequirementOutsidePreservationClause);
@@ -5979,8 +5930,6 @@ export function defaultGoalAuthorDeps(cwd: string): GoalAuthorDeps {
   };
 }
 
-const IDENTITY_LINE = /^(agent|track|session|submitted):\s*(.*?)\s*$/i;
-
 function missionSlugFallback(goal: string): string {
   return slugify(extractSlugSource(goal));
 }
@@ -5993,71 +5942,6 @@ async function goalSlug(goal: string, slugFn: (goal: string) => Promise<string>)
   }
 }
 
-function repositoryIdentifiers(ask: string): string[] {
-  const lines = ask.split(/\r?\n/);
-  const metadata = leadingIdentityMetadata(ask);
-  const body = metadata.size
-    ? (lines[0]?.trim() === '---' ? lines.slice(lines.slice(1).findIndex((line) => line.trim() === '---') + 2) : lines.slice(lines.findIndex((line) => !IDENTITY_LINE.test(line))))
-    : lines;
-  return body
-    .filter((line) => !line.startsWith('Checkable requested criterion:'))
-    .join('\n')
-    .match(/[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*/g) ?? [];
-}
-
-function leadingIdentityMetadata(ask: string): Map<string, string> {
-  const lines = ask.split(/\r?\n/);
-  let candidates: string[] = [];
-  if (lines[0]?.trim() === '---') {
-    const end = lines.slice(1).findIndex((line) => line.trim() === '---');
-    if (end < 0) return new Map();
-    candidates = lines.slice(1, end + 1);
-  } else if (IDENTITY_LINE.test(lines[0] ?? '')) {
-    candidates = lines.slice(0, lines.findIndex((line) => !IDENTITY_LINE.test(line)) === -1
-      ? lines.length
-      : lines.findIndex((line) => !IDENTITY_LINE.test(line)));
-  }
-
-  const metadata = new Map<string, string>();
-  for (const line of candidates) {
-    const match = IDENTITY_LINE.exec(line);
-    const value = match?.[2].trim();
-    if (match && value && !metadata.has(match[1].toLowerCase())) metadata.set(match[1].toLowerCase(), value);
-  }
-  return metadata;
-}
-
-/** `submitted` 는 KST 로 적는다 — 두 트랙이 같은 벽시계를 인용해야 이력이 정렬된다. */
-export function formatSubmittedAt(at: Date): string {
-  const parts = new Intl.DateTimeFormat('sv-SE', {
-    timeZone: 'Asia/Seoul', year: 'numeric', month: '2-digit', day: '2-digit',
-    hour: '2-digit', minute: '2-digit', hour12: false,
-  }).format(at);
-  return `${parts.replace(' ', ' ')} KST`;
-}
-
-/**
- * 신원 머리말 — **값이 있는 줄만** 낸다.
- *
- * ⛔ 빈 값·`unknown` 을 찍지 않는다: 부재와 미지가 같은 값이 되면 조회가 거짓을 생산한다.
- *    *"모르면 비워라"* 가 아니라 **"없으면 줄을 쓰지 마라"** 다.
- * ⭐ 우선순위는 **ask 에 이미 적힌 값 > 환경/시계 유도**다(호출자가 명시한 것이 이긴다).
- */
-function identityLines(ask: string, cwd: string, env: NodeJS.ProcessEnv, at: Date): string[] {
-  const metadata = leadingIdentityMetadata(ask);
-  const tree = /[/\\](pilot|axon)[/\\]/i.exec(cwd)?.[1]?.toLowerCase();
-  const track = metadata.get('track') ?? (tree === 'pilot' ? 'S' : tree === 'axon' ? 'T' : undefined);
-  const agent = metadata.get('agent') ?? env.AI_AGENT?.trim();
-  const session = metadata.get('session') ?? env.CLAUDE_CODE_SESSION_ID?.trim();
-  const submitted = metadata.get('submitted') ?? formatSubmittedAt(at);
-  return [
-    agent && `agent: ${agent}`,
-    track && `track: ${track}`,
-    session && `session: ${session}`,
-    submitted && `submitted: ${submitted}`,
-  ].filter((line): line is string => Boolean(line));
-}
-
 /** ⛔⭐ 문서가 «어떤 절 본문»으로 끝나면 그 절이 꼬리 메타를 삼킨다 — 그래서 경계를 준다.
  *
  *  ⛔ 종전엔 기동 선언 «하나»만 봤다. 2026-08-20 에 검증 시나리오 절이 그 뒤에 붙자

package/src/self-implement/graph-overlay-yaml.ts

@@ -199,9 +199,24 @@ export function applyGraphOverlays(
     applied.push(overlay.overlayId);
   }
 
-  // ⑵ 계약 없는 노드를 «거부» — 권한 없는 노드가 조용히 들어오는 것을 막는다.
+  // ⑵ 계약 없는 실행 노드를 거부한다. 원본부터 계약이 없는 종결 gate 는
+  // 실행 권한을 갖지 않으므로 원본·결과 모두 recipe=none·출구 없음이고 선언이 그대로일 때만 허용한다.
   for (const node of next.nodes) {
-    if (!node.contract || node.contract.tools === '') {
+    const original = template.nodes.find((candidate) => candidate.nodeId === node.nodeId);
+    const existingTerminalGate = original?.kind === 'gate' && original.recipe === 'none'
+      && original.contract === undefined
+      && JSON.stringify(node) === JSON.stringify(original)
+      && template.terminalNodes.includes(node.nodeId)
+      && next.terminalNodes.includes(node.nodeId)
+      && !template.edges.some((edge) => edge.from === node.nodeId)
+      && !next.edges.some((edge) => edge.from === node.nodeId);
+    const contract = node.contract;
+    const validContract = contract != null && Array.isArray(contract.inputs)
+      && contract.inputs.every((input) => typeof input === 'string')
+      && typeof contract.tools === 'string' && contract.tools.trim() !== ''
+      && Array.isArray(contract.outputs)
+      && contract.outputs.every((output) => typeof output === 'string');
+    if (!existingTerminalGate && !validContract) {
       rejections.push({ kind: 'node-without-contract', overlayId: applied.join(',') || '<none>', nodeId: node.nodeId });
     }
   }

package/src/self-implement/graph-unit-flatten.ts

@@ -0,0 +1,103 @@
+import type { GraphEdgeSpec, GraphTemplateSpec } from './graph-yaml.js';
+
+export interface StaticGraphUnit {
+  readonly path: string;
+  readonly template: GraphTemplateSpec;
+}
+
+export type StaticUnitResolver = (call: string, callerPath: string) => StaticGraphUnit;
+
+/** Expand calls for static readers (PWA/anatomy) while the runner keeps executing child runs. */
+export function flattenGraphUnits(
+  graph: GraphTemplateSpec,
+  graphPath: string,
+  resolve: StaticUnitResolver,
+  ancestors: readonly string[] = [],
+): GraphTemplateSpec {
+  if (ancestors.includes(graph.graphId)) throw new Error(`unit cycle: ${[...ancestors, graph.graphId].join(' -> ')}`);
+  if (ancestors.length > 3) throw new Error('unit nesting exceeds depth 3');
+
+  let nodes = [...graph.nodes];
+  let edges = [...graph.edges];
+  let entryNode = graph.entryNode;
+  const terminals = [...graph.terminalNodes];
+
+  for (const callNode of graph.nodes) {
+    if (callNode.kind !== 'subgraph' || !callNode.call) continue;
+    const unit = resolve(callNode.call, graphPath);
+    const unitHeader = unit.template.unit;
+    const selectedEntry = callNode.callEntry ?? unit.template.entryNode;
+    if (!unitHeader || !(unitHeader.entries ?? [unit.template.entryNode]).includes(selectedEntry)) {
+      throw new Error(`unit entry mismatch: ${callNode.nodeId} -> ${selectedEntry}`);
+    }
+    const nested = flattenGraphUnits({ ...unit.template, entryNode: selectedEntry }, unit.path, resolve, [...ancestors, graph.graphId]);
+    // Earlier calls may already have rewritten this call's destinations.
+    const outgoing = edges.find((edge) => edge.from === callNode.nodeId);
+    if (!outgoing || outgoing.on !== 'outcome' || !outgoing.map ||
+        Object.keys(outgoing.map).length !== unitHeader.exits.length ||
+        unitHeader.exits.some((exit) => !Object.hasOwn(outgoing.map!, exit)) ||
+        !callNode.contract ||
+        callNode.contract.inputs.length !== unitHeader.inputs.length ||
+        callNode.contract.inputs.some((key) => !unitHeader.inputs.includes(key)) ||
+        callNode.contract.outputs.length !== unitHeader.outputs.length ||
+        callNode.contract.outputs.some((key) => !unitHeader.outputs.includes(key))) {
+      throw new Error(`unit contract mismatch: ${callNode.nodeId} -> ${callNode.call}`);
+    }
+
+    const prefix = (id: string) => `${callNode.nodeId}__${id}`;
+    const childIds = new Map(nested.nodes.map((node) => [node.nodeId, prefix(node.nodeId)]));
+    const parentIds = new Set(nodes.filter((node) => node.nodeId !== callNode.nodeId).map((node) => node.nodeId));
+    for (const node of nested.nodes) {
+      if (!unitHeader.exits.includes(node.nodeId) && parentIds.has(prefix(node.nodeId))) {
+        throw new Error(`flattened unit node collision: ${prefix(node.nodeId)}`);
+      }
+    }
+    const exitTargets = new Map(unitHeader.exits.map((exit) => [exit, outgoing.map![exit]!]));
+    if (unitHeader.exits.includes(nested.entryNode) && exitTargets.get(nested.entryNode) === callNode.nodeId) {
+      throw new Error(`unit entry exit cannot map back to its own call: ${callNode.nodeId} -> ${nested.entryNode}`);
+    }
+    const childEntry = unitHeader.exits.includes(nested.entryNode)
+      ? exitTargets.get(nested.entryNode)!
+      : childIds.get(nested.entryNode);
+    if (!childEntry) throw new Error(`unit entry missing: ${callNode.nodeId} -> ${selectedEntry}`);
+    const childTarget = (id: string): string => {
+      if (unitHeader.exits.includes(id)) {
+        const target = exitTargets.get(id)!;
+        // A caller exit mapped back into its own call re-enters the flattened unit at its entry.
+        return target === callNode.nodeId ? childEntry : target;
+      }
+      const mapped = childIds.get(id);
+      if (!mapped) throw new Error(`unit edge target missing: ${unit.template.graphId}/${id}`);
+      return mapped;
+    };
+
+    const rewriteTarget = (edge: GraphEdgeSpec, target: string): string => target === callNode.nodeId ? childEntry : target;
+    const rewrittenParentEdges = edges
+      .filter((edge) => edge.from !== callNode.nodeId)
+      .map((edge) => ({
+        ...edge,
+        from: rewriteTarget(edge, edge.from),
+        ...(edge.to ? { to: rewriteTarget(edge, edge.to) } : {}),
+        ...(edge.map ? { map: Object.fromEntries(Object.entries(edge.map).map(([outcome, target]) => [outcome, rewriteTarget(edge, target)])) } : {}),
+        ...(edge.fallback ? { fallback: edge.fallback.map((item) => ({ ...item, node: rewriteTarget(edge, item.node) })) } : {}),
+      }));
+    const childNodes = nested.nodes.filter((node) => !unitHeader.exits.includes(node.nodeId))
+      .map((node) => ({ ...node, nodeId: childIds.get(node.nodeId)! }));
+    const childEdges = nested.edges.filter((edge) => !unitHeader.exits.includes(edge.from)).map((edge) => ({
+      ...edge,
+      from: childIds.get(edge.from) ?? childTarget(edge.from),
+      ...(edge.to ? { to: childTarget(edge.to) } : {}),
+      ...(edge.map ? { map: Object.fromEntries(Object.entries(edge.map).map(([outcome, target]) => [outcome, childTarget(target)])) } : {}),
+      ...(edge.fallback ? { fallback: edge.fallback.map((item) => ({ ...item, node: childTarget(item.node) })) } : {}),
+    }));
+
+    nodes = nodes.filter((node) => node.nodeId !== callNode.nodeId).concat(childNodes);
+    edges = rewrittenParentEdges.concat(childEdges);
+    if (entryNode === callNode.nodeId) entryNode = childEntry;
+    // Unit exits are replaced by their caller's mapped destinations. `terminals`
+    // belongs to the parent graph; removing by child exit name can erase a
+    // same-named parent terminal that is still present in the flattened graph.
+  }
+
+  return { ...graph, entryNode, terminalNodes: terminals, nodes, edges, unit: undefined };
+}

package/src/self-implement/graph-unit-resolver.ts

@@ -0,0 +1,107 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+import { parseGraphTemplateYaml, type GraphTemplateSpec } from './graph-yaml.js';
+import { flattenGraphUnits, type StaticGraphUnit } from './graph-unit-flatten.js';
+
+export type ResolvedGraphUnit = StaticGraphUnit & { readonly hash: string };
+
+export class UnitNotFoundError extends Error {
+  constructor(call: string) {
+    super(`unit not found: ${call}`);
+    this.name = 'UnitNotFoundError';
+  }
+}
+
+type UnitCandidate = ResolvedGraphUnit | { readonly path: string; readonly version: unknown; readonly error: string };
+type UnitIndex = Map<string, UnitCandidate[]>;
+type IndexCache = Map<string, UnitIndex>;
+
+function looseTopLevelScalar(source: string, key: string): unknown {
+  const match = source.match(new RegExp(`^${key}:\\s*(.*?)\\s*(?:#.*)?$`, 'm'));
+  if (!match) return undefined;
+  try { return (parseYaml(`value: ${match[1] ?? ''}`) as { value?: unknown }).value; }
+  catch { return match[1]?.trim(); }
+}
+
+function indexUnits(dir: string): UnitIndex {
+  const byId: UnitIndex = new Map();
+  const yamlFiles = (root: string): string[] => readdirSync(root, { withFileTypes: true }).flatMap(entry => {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) return yamlFiles(path);
+    return entry.isFile() && /\.ya?ml$/.test(entry.name) && entry.name !== 'recipes.yaml' && entry.name !== 'recipes.yml' ? [path] : [];
+  });
+  for (const path of yamlFiles(dir)) {
+    const source = readFileSync(path, 'utf8');
+    let header: unknown;
+    try { header = parseYaml(source); }
+    catch (error) {
+      // A malformed YAML document can still explicitly declare a graph ID and
+      // unit header. Keep that broken declaration visible to block fallback.
+      const id = looseTopLevelScalar(source, 'graph_id');
+      if (typeof id !== 'string' || !/^unit\s*:/m.test(source)) continue;
+      const candidates = byId.get(id) ?? [];
+      candidates.push({
+        path,
+        version: looseTopLevelScalar(source, 'version'),
+        error: `YAML parsing failed: ${error instanceof Error ? error.message : String(error)}`,
+      });
+      byId.set(id, candidates);
+      continue;
+    }
+    if (!header || typeof header !== 'object' || Array.isArray(header)) continue;
+    const id = (header as Record<string, unknown>).graph_id;
+    if (typeof id !== 'string') continue;
+    const version: unknown = (header as Record<string, unknown>).version;
+    const parsed = parseGraphTemplateYaml(source, path);
+    if (parsed.errors.length) {
+      if (!Object.hasOwn(header, 'unit')) continue;
+      const candidates = byId.get(id) ?? [];
+      candidates.push({ path, version, error: parsed.errors.map((issue) => issue.message).join('; ') || 'unit header missing' });
+      byId.set(id, candidates);
+      continue;
+    }
+    if (!parsed.template?.unit) continue;
+    const candidates = byId.get(id) ?? [];
+    candidates.push({ path, template: parsed.template, hash: createHash('sha256').update(source).digest('hex') });
+    byId.set(id, candidates);
+  }
+  return byId;
+}
+
+/** Resolve unit calls with the runner's existing precedence and version contract. */
+export function resolveGraphUnit(call: string, callerPath: string, cache?: IndexCache): ResolvedGraphUnit {
+  const [id, requested] = call.split('@');
+  const repo = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const directories = [join(dirname(callerPath), 'units'), dirname(callerPath), join(repo, 'graphs', 'units'), join(getElanousConfigDir(), 'graphs', 'units')];
+  for (const dir of directories) {
+    if (!existsSync(dir)) continue;
+    const byId = cache?.get(dir) ?? indexUnits(dir);
+    if (cache && !cache.has(dir)) cache.set(dir, byId);
+    const matches = (byId.get(id!) ?? []).filter((candidate) => {
+      const version = 'template' in candidate ? candidate.template.version : candidate.version;
+      if (!('template' in candidate) && (typeof version !== 'number' || !Number.isFinite(version))) return true;
+      return requested === String(version) || requested === `^${version}`;
+    });
+    if (matches.length > 1) throw new Error(`ambiguous unit: ${call}`);
+    if (matches.length) {
+      const match = matches[0]!;
+      if (!('template' in match)) throw new Error(`invalid graph unit: ${call} at ${match.path}: ${match.error}`);
+      return match;
+    }
+  }
+  throw new UnitNotFoundError(call);
+}
+
+export function createGraphUnitResolver(): (call: string, callerPath: string) => ResolvedGraphUnit {
+  const cache: IndexCache = new Map();
+  return (call, callerPath) => resolveGraphUnit(call, callerPath, cache);
+}
+
+/** Shared server-side static view used by PWA, anatomy, and runner verification. */
+export function flattenGraphTemplate(graph: GraphTemplateSpec, graphPath: string): GraphTemplateSpec {
+  return flattenGraphUnits(graph, graphPath, createGraphUnitResolver());
+}