elanous 0.2.42 → 0.2.44

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

@@ -43,6 +43,157 @@ export interface OverlayParseResult {
   readonly errors: readonly GraphParseIssue[];
 }
 
+/** Injected ARG promotion evidence used by the graph-promote rehearsal.
+ * This input is deliberately separate from the production run ledger: a fixture
+ * can exercise the decision path, but its output is always labelled mock-only. */
+export interface ArgPromotionEvidenceEvent {
+  readonly runId: string;
+  readonly timestamp: string;
+  readonly trigger: string;
+  readonly phase: 'adaptation' | 'baseline' | 'shadow';
+  readonly landed?: boolean;
+  readonly shadowAccepted?: boolean;
+}
+
+export interface ArgPromotionCandidate {
+  readonly overlayId: string;
+  readonly target: string;
+  readonly appliesWhen: string;
+  readonly patch: readonly OverlayPatchOp[];
+}
+
+export interface ArgPromotionEvaluation {
+  readonly mockOnly: true;
+  readonly verdict: 'eligible-for-human-pr' | 'held';
+  readonly blockers: readonly string[];
+  readonly metrics: {
+    readonly trigger: string;
+    readonly adaptationRuns: number;
+    readonly adaptationLandingRate: number | null;
+    readonly baselineRuns: number;
+    readonly baselineLandingRate: number | null;
+    readonly landingDelta: number | null;
+    readonly adaptationWindowDays: number | null;
+    readonly shadowObservations: number;
+    readonly shadowWindowDays: number | null;
+  };
+  readonly proposal?: {
+    readonly action: 'proposal-only';
+    readonly promoted_from: readonly string[];
+    readonly evidence: Readonly<Record<string, unknown>>;
+    readonly overlay: {
+      readonly overlay_id: string;
+      readonly target: string;
+      readonly stage: 'launch';
+      readonly applies_when: string;
+      readonly patch: readonly OverlayPatchOp[];
+    };
+    readonly rollback: 'open a human-reviewed demotion PR if the 7-day landing rate declines';
+    readonly patentReview: 'ELA-53 human review pending';
+  };
+}
+
+const PROMOTION_DAY_MS = 24 * 60 * 60 * 1000;
+
+function promotionSpanDays(events: readonly ArgPromotionEvidenceEvent[]): number | null {
+  if (events.length < 2) return null;
+  const times = events.map((event) => Date.parse(event.timestamp));
+  if (times.some((time) => !Number.isFinite(time))) return null;
+  return (Math.max(...times) - Math.min(...times)) / PROMOTION_DAY_MS;
+}
+
+/** Evaluate injected evidence without reading a production ledger, writing an overlay, or opening a PR. */
+export function evaluateArgPromotionFixture(input: {
+  readonly trigger: string;
+  readonly candidate: ArgPromotionCandidate;
+  readonly events: readonly ArgPromotionEvidenceEvent[];
+}): ArgPromotionEvaluation {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) throw new Error('ARG promotion fixture root must be an object');
+  const { trigger, candidate, events } = input;
+  if (typeof trigger !== 'string' || typeof candidate !== 'object' || candidate === null || Array.isArray(candidate)
+    || typeof candidate.overlayId !== 'string' || typeof candidate.target !== 'string' || typeof candidate.appliesWhen !== 'string'
+    || !Array.isArray(candidate.patch) || !Array.isArray(events)) {
+    throw new Error('ARG promotion fixture requires trigger, candidate object, patch array and events array');
+  }
+  if (!trigger.trim() || !candidate.overlayId.trim() || !candidate.target.trim() || !candidate.appliesWhen.trim()) {
+    throw new Error('ARG promotion fixture requires trigger, overlayId, target and appliesWhen');
+  }
+  if (candidate.patch.length === 0) throw new Error('ARG promotion candidate patch must not be empty');
+  for (const operation of candidate.patch) {
+    if (operation === null || typeof operation !== 'object' || !['add', 'replace', 'remove'].includes(operation.op)
+      || typeof operation.path !== 'string' || !operation.path.startsWith('/')
+      || (operation.op !== 'remove' && !('value' in operation))) {
+      throw new Error('ARG promotion candidate contains an invalid JSON Patch operation');
+    }
+  }
+  const runIds = new Set<string>();
+  for (const rawEvent of events) {
+    if (rawEvent === null || typeof rawEvent !== 'object' || Array.isArray(rawEvent)) throw new Error('ARG promotion fixture contains a non-object event');
+    const event = rawEvent as ArgPromotionEvidenceEvent;
+    if (typeof event.runId !== 'string' || !event.runId.trim() || typeof event.timestamp !== 'string'
+      || !Number.isFinite(Date.parse(event.timestamp)) || typeof event.trigger !== 'string' || !event.trigger.trim()
+      || !['adaptation', 'baseline', 'shadow'].includes(event.phase)) {
+      throw new Error('ARG promotion fixture contains an invalid event');
+    }
+    if (runIds.has(event.runId)) throw new Error(`ARG promotion fixture repeats runId ${event.runId}`);
+    runIds.add(event.runId);
+    if ((event.phase === 'adaptation' || event.phase === 'baseline') && typeof event.landed !== 'boolean') {
+      throw new Error(`ARG promotion ${event.phase} event requires landed`);
+    }
+    if (event.phase === 'shadow' && typeof event.shadowAccepted !== 'boolean') {
+      throw new Error('ARG promotion shadow event requires shadowAccepted');
+    }
+  }
+
+  const matching = events.filter((event) => event.trigger === trigger);
+  const adaptations = matching.filter((event) => event.phase === 'adaptation');
+  const baseline = matching.filter((event) => event.phase === 'baseline');
+  const shadow = matching.filter((event) => event.phase === 'shadow');
+  const rate = (rows: readonly ArgPromotionEvidenceEvent[]): number | null => rows.length === 0
+    ? null : rows.filter((event) => event.landed === true).length / rows.length;
+  const adaptationLandingRate = rate(adaptations);
+  const baselineLandingRate = rate(baseline);
+  const landingDelta = adaptationLandingRate === null || baselineLandingRate === null
+    ? null : adaptationLandingRate - baselineLandingRate;
+  const adaptationSpanDays = promotionSpanDays(adaptations);
+  const baselineSpanDays = promotionSpanDays(baseline);
+  const adaptationWindowDays = adaptationSpanDays === null || baselineSpanDays === null
+    ? null : Math.min(adaptationSpanDays, baselineSpanDays);
+  const shadowWindowDays = promotionSpanDays(shadow);
+  const evidenceEnd = Math.max(...[...adaptations, ...baseline].map((event) => Date.parse(event.timestamp)));
+  const shadowStart = Math.min(...shadow.map((event) => Date.parse(event.timestamp)));
+  const blockers: string[] = [];
+  if (adaptations.length < 5) blockers.push('same-trigger-adaptations-below-5');
+  if (baseline.length === 0) blockers.push('same-trigger-baseline-missing');
+  if (landingDelta === null || landingDelta < 0.2 - Number.EPSILON) blockers.push('landing-improvement-below-20pp');
+  if (adaptationWindowDays === null || adaptationWindowDays < 7) blockers.push('adaptation-evidence-window-under-7-days');
+  if (shadow.length < 2 || shadowWindowDays === null || shadowWindowDays < 7) blockers.push('shadow-window-under-7-days');
+  if (!Number.isFinite(evidenceEnd) || !Number.isFinite(shadowStart) || shadowStart < evidenceEnd) blockers.push('shadow-starts-before-evidence-window');
+  if (shadow.some((event) => event.shadowAccepted !== true)) blockers.push('shadow-evaluation-declined');
+
+  const metrics = { trigger, adaptationRuns: adaptations.length, adaptationLandingRate,
+    baselineRuns: baseline.length, baselineLandingRate, landingDelta, adaptationWindowDays,
+    shadowObservations: shadow.length, shadowWindowDays };
+  if (blockers.length > 0) return { mockOnly: true, verdict: 'held', blockers, metrics };
+  const promotedFrom = adaptations.map((event) => event.runId).sort();
+  return {
+    mockOnly: true, verdict: 'eligible-for-human-pr', blockers, metrics,
+    proposal: {
+      action: 'proposal-only', promoted_from: promotedFrom,
+      evidence: {
+        source: 'injected-mock-fixture', trigger, adaptationRuns: promotedFrom,
+        baselineRuns: baseline.map((event) => event.runId).sort(),
+        adaptationLandingRate, baselineLandingRate, landingDelta,
+        adaptationWindowDays, shadowRunIds: shadow.map((event) => event.runId).sort(), shadowWindowDays,
+      },
+      overlay: { overlay_id: candidate.overlayId, target: candidate.target, stage: 'launch',
+        applies_when: candidate.appliesWhen, patch: candidate.patch },
+      rollback: 'open a human-reviewed demotion PR if the 7-day landing rate declines',
+      patentReview: 'ELA-53 human review pending',
+    },
+  };
+}
+
 const STAGES = new Set<OverlayStage>(['launch', 'runtime', 'heal']);
 const OPS = new Set(['add', 'replace', 'remove']);
 
@@ -167,8 +318,10 @@ export function applyGraphOverlays(
       rejections.push({ kind: 'unknown-target', overlayId: overlay.overlayId, target: overlay.target });
       continue;
     }
+    const beforeNodes = new Map(next.nodes.map((node) => [node.nodeId, node]));
     const beforeVisits = new Map(next.nodes.map((node) => [node.nodeId, node.maxVisits]));
-    const beforeRoutes = edgeMapOf(next);
+    const beforeRoutes = graphRouteMap(next);
+    const beforeEdgeMap = edgeMapOf(next);
     for (const op of overlay.patch) {
       const resolved = resolvePointer(next, op.path);
       if (!resolved) { rejections.push({ kind: 'bad-pointer', overlayId: overlay.overlayId, path: op.path }); continue; }
@@ -190,15 +343,27 @@ export function applyGraphOverlays(
         if (op.op === 'remove') delete bag[key]; else bag[key] = op.value;
       } else rejections.push({ kind: 'bad-pointer', overlayId: overlay.overlayId, path: op.path });
     }
+    for (const node of next.nodes) {
+      if (beforeNodes.has(node.nodeId)) continue;
+      patches.push({ overlayId: overlay.overlayId, field: 'node-added', node: node.nodeId, kind: node.kind, maxVisits: node.maxVisits });
+    }
+    const afterRoutes = graphRouteMap(next);
+    for (const [key, route] of afterRoutes) {
+      const before = beforeRoutes.get(key);
+      if (before && before.to !== route.to) {
+        patches.push({ overlayId: overlay.overlayId, field: 'edge-rerouted', from: route.from, outcome: route.outcome, was: before.to, to: route.to });
+      }
+    }
     for (const node of next.nodes) {
       const before = beforeVisits.get(node.nodeId);
       if (before !== undefined && before !== node.maxVisits) {
         patches.push({ overlayId: overlay.overlayId, field: 'maxVisits', node: node.nodeId, before, after: node.maxVisits });
       }
     }
-    const afterRoutes = edgeMapOf(next);
-    for (const [node, before] of Object.entries(beforeRoutes)) {
-      const after = afterRoutes[node] ?? [];
+    const afterEdgeMap = edgeMapOf(next);
+    for (const node of Object.keys(beforeEdgeMap)) {
+      const before = beforeEdgeMap[node] ?? [];
+      const after = afterEdgeMap[node] ?? [];
       if (before.length !== after.length || before.some((destination, index) => destination !== after[index])) {
         patches.push({ overlayId: overlay.overlayId, field: 'routes', node, before, after });
       }
@@ -246,6 +411,18 @@ export function applyGraphOverlays(
   return { ok: true, template: next, overlayIds: applied, patches };
 }
 
+/** Keep outcome names while comparing route changes; the compiled edge map deliberately drops them. */
+function graphRouteMap(template: GraphTemplateSpec): Map<string, { from: string; outcome: string; to: string }> {
+  const routes = new Map<string, { from: string; outcome: string; to: string }>();
+  for (const [index, edge] of template.edges.entries()) {
+    if (edge.to) routes.set(`${edge.from}\u0000direct\u0000${index}`, { from: edge.from, outcome: '', to: edge.to });
+    for (const [outcome, to] of Object.entries(edge.map ?? {})) {
+      routes.set(`${edge.from}\u0000${edge.on ?? 'outcome'}\u0000${outcome}`, { from: edge.from, outcome, to });
+    }
+  }
+  return routes;
+}
+
 export interface OverlayLoadResult {
   readonly overlays: readonly GraphOverlaySpec[];
   readonly errors: readonly GraphParseIssue[];

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

@@ -26,7 +26,9 @@ export type OverlayRejection =
 
 export type OverlayPatch =
   | { readonly overlayId: string; readonly field: 'maxVisits'; readonly node: string; readonly before: number; readonly after: number }
-  | { readonly overlayId: string; readonly field: 'routes'; readonly node: string; readonly before: readonly string[]; readonly after: readonly string[] };
+  | { readonly overlayId: string; readonly field: 'routes'; readonly node: string; readonly before: readonly string[]; readonly after: readonly string[] }
+  | { readonly overlayId: string; readonly field: 'node-added'; readonly node: string; readonly kind: string; readonly maxVisits: number }
+  | { readonly overlayId: string; readonly field: 'edge-rerouted'; readonly from: string; readonly outcome: string; readonly was: string; readonly to: string };
 
 export type OverlayResult =
   | { ok: true; template: GraphTemplate; patches: readonly OverlayPatch[] }

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

@@ -0,0 +1,107 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import { evaluateOverlayCondition, parseOverlayCondition } from './graph-overlay-condition.js';
+import type { GraphParseIssue } from './graph-yaml.js';
+
+/** L1 profile: a deterministic state bundle and references to already-declared overlays. */
+export interface GraphProfileSpec {
+  readonly profileId: string;
+  readonly appliesWhen: string;
+  readonly state: Readonly<Record<string, string | number | boolean>>;
+  readonly overlays: readonly string[];
+}
+
+export interface GraphProfileParseResult {
+  readonly profile?: GraphProfileSpec;
+  readonly errors: readonly GraphParseIssue[];
+}
+
+export function parseGraphProfileYaml(source: string, label = '<inline>'): GraphProfileParseResult {
+  let raw: unknown;
+  try { raw = parseYaml(source); }
+  catch (error) {
+    return { errors: [{ path: label, message: `YAML 파싱 실패: ${error instanceof Error ? error.message : String(error)}` }] };
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+    return { errors: [{ path: label, message: 'YAML 최상위가 맵이 아니다' }] };
+  const doc = raw as Record<string, unknown>;
+  const errors: GraphParseIssue[] = [];
+  const profileId = typeof doc.profile_id === 'string' && /^[a-z][a-z0-9-]*$/.test(doc.profile_id) ? doc.profile_id : undefined;
+  if (!profileId) errors.push({ path: `${label}/profile_id`, message: 'profile_id는 소문자·숫자·하이픈 식별자여야 한다' });
+  const appliesWhen = typeof doc.applies_when === 'string' ? doc.applies_when : undefined;
+  if (!appliesWhen || !parseOverlayCondition(appliesWhen).ok)
+    errors.push({ path: `${label}/applies_when`, message: 'applies_when은 오버레이 조건 한 개(key op literal)여야 한다' });
+  const stateRaw = doc.state;
+  const state: Record<string, string | number | boolean> = {};
+  if (!stateRaw || typeof stateRaw !== 'object' || Array.isArray(stateRaw)) {
+    errors.push({ path: `${label}/state`, message: 'state는 스칼라 값만 담는 맵이어야 한다' });
+  } else {
+    for (const [key, value] of Object.entries(stateRaw as Record<string, unknown>)) {
+      if (!/^[a-z_][a-z0-9_]*$/i.test(key) || !['string', 'number', 'boolean'].includes(typeof value)
+        || (typeof value === 'number' && !Number.isFinite(value))) {
+        errors.push({ path: `${label}/state/${key}`, message: 'state 키와 값은 조건 파서가 다루는 키·문자열·유한수·불리언이어야 한다' });
+      } else state[key] = value as string | number | boolean;
+    }
+  }
+  const overlaysRaw = doc.overlays;
+  const overlays = Array.isArray(overlaysRaw) ? overlaysRaw.filter((value): value is string => typeof value === 'string') : undefined;
+  if (!Array.isArray(overlaysRaw) || !overlays || overlays.length !== overlaysRaw.length || new Set(overlays).size !== overlays.length)
+    errors.push({ path: `${label}/overlays`, message: 'overlays는 중복 없는 문자열 목록이어야 한다' });
+  if (errors.length > 0) return { errors };
+  return { profile: { profileId: profileId!, appliesWhen: appliesWhen!, state, overlays: overlays! }, errors };
+}
+
+export interface GraphProfileLoadResult {
+  readonly profiles: readonly GraphProfileSpec[];
+  readonly errors: readonly GraphParseIssue[];
+  readonly scannedFiles: number;
+}
+
+export function loadGraphProfiles(dir: string): GraphProfileLoadResult {
+  let files: string[];
+  try { files = readdirSync(dir).filter((file) => file.endsWith('.yaml') || file.endsWith('.yml')).sort(); }
+  catch (error) { return { profiles: [], errors: [{ path: dir, message: `프로필 디렉토리를 못 읽었다: ${error instanceof Error ? error.message : String(error)}` }], scannedFiles: 0 }; }
+  const errors: GraphParseIssue[] = [];
+  const profiles: GraphProfileSpec[] = [];
+  for (const file of files) {
+    try {
+      const parsed = parseGraphProfileYaml(readFileSync(join(dir, file), 'utf8'), file);
+      errors.push(...parsed.errors);
+      if (parsed.profile) profiles.push(parsed.profile);
+    } catch (error) { errors.push({ path: file, message: `읽기 실패: ${error instanceof Error ? error.message : String(error)}` }); }
+  }
+  const seen = new Set<string>();
+  for (const profile of profiles) {
+    if (seen.has(profile.profileId)) errors.push({ path: `${dir}/${profile.profileId}`, message: `profile_id '${profile.profileId}'가 중복이다` });
+    seen.add(profile.profileId);
+  }
+  return errors.length ? { profiles: [], errors, scannedFiles: files.length } : { profiles, errors, scannedFiles: files.length };
+}
+
+export function defaultProfilesDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'graphs', 'profiles');
+}
+
+export interface GraphProfileSelection {
+  readonly applied: readonly GraphProfileSpec[];
+  readonly errors: readonly string[];
+  readonly state: Readonly<Record<string, unknown>>;
+}
+
+/** Match all profiles deterministically; conflicting owned state rejects the whole profile set. */
+export function selectGraphProfiles(
+  profiles: readonly GraphProfileSpec[],
+  state: Readonly<Record<string, unknown>>,
+): GraphProfileSelection {
+  const applied = profiles.filter((profile) => evaluateOverlayCondition(profile.appliesWhen, state).kind === 'applies');
+  const owned = new Map<string, string | number | boolean>();
+  const errors: string[] = [];
+  for (const profile of applied) for (const [key, value] of Object.entries(profile.state)) {
+    if (owned.has(key) && owned.get(key) !== value) errors.push(`profile state conflict: ${key} (${String(owned.get(key))} vs ${String(value)})`);
+    else owned.set(key, value);
+  }
+  if (errors.length) return { applied: [], errors, state };
+  return { applied, errors, state: { ...state, ...Object.fromEntries(owned) } };
+}

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

@@ -37,6 +37,8 @@ export interface GraphNodeSpec {
   /** Entry selected by this call when a unit exposes more than one entry. */
   readonly callEntry?: string;
   readonly budget?: { readonly innerSteps: number };
+  /** ARG L upper bound inherited by this child graph call. */
+  readonly allowance?: { readonly innerSteps: number };
   /** L1: skip this optional node when a measured state condition holds. */
   readonly skipWhen?: string;
 }
@@ -48,6 +50,11 @@ export interface GraphEdgeSpec {
   /** 조건부 엣지 — 라우터가 읽는 «상태 키». ⛔ 값은 코드가 낸다(RFC §4.3 ⑵). */
   readonly on?: string;
   readonly map?: Readonly<Record<string, string>>;
+  /** Explicit fan-out destinations keyed by outcome. Each selected branch runs concurrently and joins at `join`. */
+  readonly branches?: Readonly<Record<string, readonly string[]>>;
+  readonly join?: string;
+  /** Failed warning branches remain visible in the join output but do not fail the barrier. */
+  readonly warningBranches?: readonly string[];
   /** 심이 «주입 안 됐을 때» 내려가는 순서. `requires` 는 그 심 이름들. */
   readonly fallback?: readonly { readonly node: string; readonly requires: readonly string[]; readonly observed?: number }[];
   readonly observed?: number;
@@ -65,6 +72,8 @@ export interface GraphTemplateSpec {
   /** 문서 전용 변경이면 gate 노드를 건너뛸 수 있다는 템플릿 정책. */
   readonly docsOnlyGateSkip?: boolean;
   readonly state?: readonly string[];
+  /** ARG L upper bound for this graph's total executed steps. */
+  readonly allowance?: { readonly innerSteps: number };
   /** ⭐ 런 계약(선택) — 이 그래프가 «기본으로» 요구하는 실행 칸 등. 발사 인자가 덮는다(graph-run-contract.ts). */
   readonly runContract?: GraphRunContractSpec;
   readonly unit?: { readonly inputs: readonly string[]; readonly outputs: readonly string[]; readonly exits: readonly string[]; readonly entries?: readonly string[] };
@@ -148,6 +157,14 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
 
   const terminalNodes = asArray(doc.terminal_nodes).filter((v): v is string => typeof v === 'string');
   if (terminalNodes.length === 0) errors.push({ path: `${label}/terminal_nodes`, message: 'terminal_nodes 가 비었다 — 끝날 수 없는 그래프다' });
+  let allowance: GraphTemplateSpec['allowance'];
+  if (doc.allowance !== undefined) {
+    const value = doc.allowance as Record<string, unknown> | undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value) || !Number.isSafeInteger(value.inner_steps) ||
+        (value.inner_steps as number) < 1 || Object.keys(value).some(key => key !== 'inner_steps'))
+      errors.push({ path: `${label}/allowance/inner_steps`, message: 'inner_steps 는 1 이상의 안전한 정수여야 한다' });
+    else allowance = { innerSteps: value.inner_steps as number };
+  }
 
   const journeyStages = doc.journey_stages;
   if (journeyStages !== undefined && (!Array.isArray(journeyStages) || journeyStages.length === 0
@@ -202,21 +219,28 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
       : undefined;
     // A subgraph node becomes a unit call only when it names `call:`; without it the node keeps the
     // pre-unit meaning (catalog role / recipe node), so existing declarations stay valid.
-    if (kind === 'subgraph' && (n.call !== undefined || n.budget !== undefined || n.call_entry !== undefined)) {
+    if (kind === 'subgraph' && (n.call !== undefined || n.budget !== undefined || n.allowance !== undefined || n.call_entry !== undefined)) {
       if (typeof n.call !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*@(?:\^?[1-9]\d*)$/.test(n.call))
         errors.push({ path: `${at}/call`, message: 'call 은 id@정수판 또는 id@^주판이어야 한다' });
       const budget = n.budget as Record<string, unknown> | undefined;
       if (!budget || typeof budget !== 'object' || Array.isArray(budget) ||
           !Number.isSafeInteger(budget.inner_steps) || (budget.inner_steps as number) < 1 || Object.keys(budget).some(key => key !== 'inner_steps'))
         errors.push({ path: `${at}/budget/inner_steps`, message: 'inner_steps 는 1 이상의 안전한 정수여야 한다' });
+      if (n.allowance !== undefined) {
+        const childAllowance = n.allowance as Record<string, unknown> | undefined;
+        if (!childAllowance || typeof childAllowance !== 'object' || Array.isArray(childAllowance) ||
+            !Number.isSafeInteger(childAllowance.inner_steps) || (childAllowance.inner_steps as number) < 1 ||
+            Object.keys(childAllowance).some(key => key !== 'inner_steps'))
+          errors.push({ path: `${at}/allowance/inner_steps`, message: 'inner_steps 는 1 이상의 안전한 정수여야 한다' });
+      }
       if (!contractRaw || !Array.isArray(contractRaw.inputs) || !contractRaw.inputs.every(v => typeof v === 'string') ||
           !Array.isArray(contractRaw.outputs) || !contractRaw.outputs.every(v => typeof v === 'string'))
         errors.push({ path: `${at}/contract`, message: 'subgraph 에는 inputs·outputs 계약이 필요하다' });
       if (recipe !== 'none') errors.push({ path: `${at}/recipe`, message: 'subgraph 는 recipe 를 실행하지 않는다' });
       if (n.call_entry !== undefined && (typeof n.call_entry !== 'string' || !n.call_entry.trim()))
         errors.push({ path: `${at}/call_entry`, message: 'call_entry 는 비어 있지 않은 노드 id 여야 한다' });
-    } else if (kind !== 'subgraph' && (n.call !== undefined || n.budget !== undefined || n.call_entry !== undefined)) {
-      errors.push({ path: at, message: 'call·call_entry·budget 은 subgraph 전용이다' });
+    } else if (kind !== 'subgraph' && (n.call !== undefined || n.budget !== undefined || n.allowance !== undefined || n.call_entry !== undefined)) {
+      errors.push({ path: at, message: 'call·call_entry·budget·allowance 은 subgraph 전용이다' });
     }
     // ⛔ 계약이 없으면 「이 노드가 무엇을 할 수 있나」를 답할 수 없다 — 경고로 남긴다(거절은 오버레이 쪽).
     if (contract === undefined) warnings.push({ path: `${at}/contract`, message: '계약(inputs·tools·outputs)이 없다 — 권한을 코드에서만 알 수 있다' });
@@ -235,6 +259,9 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
       ...(kind === 'subgraph' && n.budget && typeof n.budget === 'object' && !Array.isArray(n.budget) &&
         typeof (n.budget as Record<string, unknown>).inner_steps === 'number'
         ? { budget: { innerSteps: (n.budget as { inner_steps: number }).inner_steps } } : {}),
+      ...(kind === 'subgraph' && n.allowance && typeof n.allowance === 'object' && !Array.isArray(n.allowance) &&
+        typeof (n.allowance as Record<string, unknown>).inner_steps === 'number'
+        ? { allowance: { innerSteps: (n.allowance as { inner_steps: number }).inner_steps } } : {}),
       ...(typeof n.skip_when === 'string' ? { skipWhen: n.skip_when } : {}),
     });
   }
@@ -251,14 +278,19 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
     if (!known.has(from)) { errors.push({ path: `${at}/from`, message: `'${from}' 은 선언된 노드가 아니다` }); continue; }
     const hasTo = typeof e.to === 'string';
     const hasMap = e.map !== null && typeof e.map === 'object';
+    const hasBranches = e.branches !== null && typeof e.branches === 'object' && !Array.isArray(e.branches);
     if (e.when !== undefined && (typeof e.when !== 'string' || !parseOverlayCondition(e.when).ok))
       errors.push({ path: `${at}/when`, message: 'when 은 오버레이 조건 한 개(key op literal)여야 한다' });
     if (e.when !== undefined && (L1_PROTECTED_ROUTE_NODES.has(from) || nodes.some(node => node.nodeId === from && node.kind === 'gate') || terminalNodes.includes(from)))
       errors.push({ path: `${at}/when`, message: `'${from}' 의 필수 검증·착지 결과는 when 간선으로 덮을 수 없다` });
     if (e.when !== undefined && (!hasTo || hasMap || e.on !== undefined))
       errors.push({ path: `${at}/when`, message: 'when 은 to 간선에서만 쓴다' });
-    if (hasTo === hasMap) {
-      errors.push({ path: at, message: 'to 와 map 중 «정확히 하나»를 써야 한다' });
+    if (!hasTo && !hasMap && !hasBranches) {
+      errors.push({ path: at, message: 'to 또는 map/branches 조합을 써야 한다' });
+      continue;
+    }
+    if (hasTo && (hasMap || hasBranches)) {
+      errors.push({ path: at, message: 'to 는 map·branches 와 함께 쓸 수 없다' });
       continue;
     }
     const map: Record<string, string> = {};
@@ -270,6 +302,35 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
       }
       if (typeof e.on !== 'string') errors.push({ path: `${at}/on`, message: 'map 을 쓰면 on(라우터가 읽는 상태 키)이 필요하다' });
     }
+    let branches: Record<string, readonly string[]> | undefined;
+    let warningBranches: readonly string[] | undefined;
+    if (hasBranches) {
+      branches = {};
+      for (const [outcome, destinations] of Object.entries(e.branches as Record<string, unknown>)) {
+        if (!Array.isArray(destinations) || destinations.length < 2 || !destinations.every((value) => typeof value === 'string')) {
+          errors.push({ path: `${at}/branches/${outcome}`, message: 'branches 목적지는 두 개 이상의 노드 id 목록이어야 한다' });
+          continue;
+        }
+        if (new Set(destinations).size !== destinations.length)
+          errors.push({ path: `${at}/branches/${outcome}`, message: 'branches 목적지는 중복될 수 없다' });
+        for (const [index, destination] of destinations.entries()) {
+          if (!known.has(destination)) errors.push({ path: `${at}/branches/${outcome}/${index}`, message: `'${destination}' 는 선언된 노드가 아니다` });
+        }
+        branches[outcome] = destinations as string[];
+      }
+      if (typeof e.on !== 'string' || typeof e.join !== 'string' || !known.has(e.join))
+        errors.push({ path: at, message: 'branches 에는 on 과 선언된 join 노드가 필요하다' });
+      if (e.fallback !== undefined || e.when !== undefined) errors.push({ path: at, message: 'branches 는 fallback·when 과 함께 쓸 수 없다' });
+      if (hasMap && Object.keys(map).some((outcome) => Object.hasOwn(e.branches as object, outcome)))
+        errors.push({ path: `${at}/branches`, message: 'map 과 branches 의 outcome 키는 겹칠 수 없다' });
+      if (e.warning_branches !== undefined) {
+        if (!Array.isArray(e.warning_branches) || e.warning_branches.some((branch) => typeof branch !== 'string' || !branch.trim()) ||
+            new Set(e.warning_branches).size !== e.warning_branches.length ||
+            e.warning_branches.some((branch) => !Object.values(branches!).some((destinations) => destinations.includes(branch as string)))) {
+          errors.push({ path: `${at}/warning_branches`, message: 'warning_branches 는 중복 없는 branches 목적지 목록이어야 한다' });
+        } else warningBranches = e.warning_branches as string[];
+      }
+    }
     if (hasTo && !known.has(e.to as string)) { errors.push({ path: `${at}/to`, message: `'${String(e.to)}' 는 선언된 노드가 아니다` }); continue; }
 
     const fallback = asArray(e.fallback).flatMap((f, fi) => {
@@ -287,6 +348,7 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
       from,
       ...(hasTo ? { to: e.to as string } : {}),
       ...(hasMap ? { on: String(e.on), map } : {}),
+      ...(branches ? { on: String(e.on), branches, join: String(e.join), ...(warningBranches ? { warningBranches } : {}) } : {}),
       ...(fallback.length > 0 ? { fallback } : {}),
       ...(typeof e.observed === 'number' ? { observed: e.observed } : {}),
       ...(typeof e.when === 'string' ? { when: e.when } : {}),
@@ -304,6 +366,25 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
     if (!edges.some(candidate => candidate.from === edge.from && candidate.when === undefined))
       errors.push({ path: `${label}/edges/${edge.from}/when`, message: 'when 간선에는 모호·미관측 때 탈 무조건 기본 간선이 필요하다' });
   }
+  const fanOutDestinations = new Map<string, string>();
+  const fanOutJoins = new Map<string, string>();
+  for (const edge of edges) {
+    if (!edge.branches || !edge.join) continue;
+    const sourceNode = nodes.find(node => node.nodeId === edge.from);
+    if (sourceNode && sourceNode.maxVisits !== 1) errors.push({ path: `${label}/edges/${edge.from}/branches`, message: 'fan-out 출발 노드는 재방문할 수 없어 max_visits: 1 이어야 한다' });
+    if (fanOutJoins.has(edge.join) && fanOutJoins.get(edge.join) !== edge.from) errors.push({ path: `${label}/edges/${edge.from}/join`, message: 'join 노드는 하나의 fan-out barrier만 소유할 수 있다' });
+    fanOutJoins.set(edge.join, edge.from);
+    if (edge.join === edge.from || Object.values(edge.branches).some((branches) => branches.includes(edge.join!)))
+      errors.push({ path: `${label}/edges/${edge.from}/join`, message: 'join 노드는 fan-out source나 branch 목적지일 수 없다' });
+    for (const branch of new Set(Object.values(edge.branches).flat())) {
+      if (fanOutDestinations.has(branch) && fanOutDestinations.get(branch) !== edge.from) errors.push({ path: `${label}/edges/${edge.from}/branches`, message: `branch '${branch}' 는 하나의 fan-out source 에서만 실행할 수 있다` });
+      fanOutDestinations.set(branch, edge.from);
+      if (edges.some(candidate => candidate.from === branch)) errors.push({ path: `${label}/edges/${edge.from}/branches`, message: `branch '${branch}' 는 단일 노드만 지원하며 후속 간선은 허용되지 않는다` });
+    }
+    const joinEdge = edges.find((candidate) => candidate.from === edge.join && candidate.on === 'outcome');
+    if (!joinEdge?.map || !Object.hasOwn(joinEdge.map, 'ok') || !Object.hasOwn(joinEdge.map, 'fail'))
+      errors.push({ path: `${label}/edges/${edge.join}`, message: 'fan-out join 은 ok·fail 출구를 모두 선언해야 한다' });
+  }
 
   if (entryNode !== undefined && !known.has(entryNode)) errors.push({ path: `${label}/entry_node`, message: `'${entryNode}' 는 선언된 노드가 아니다` });
   for (const t of terminalNodes) if (!known.has(t)) errors.push({ path: `${label}/terminal_nodes`, message: `'${t}' 는 선언된 노드가 아니다` });
@@ -358,6 +439,7 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
       ...(loop ? { loop } : {}),
       ...(typeof doc.docs_only_gate_skip === 'boolean' ? { docsOnlyGateSkip: doc.docs_only_gate_skip } : {}),
       ...(Array.isArray(doc.state) ? { state: doc.state.filter((v): v is string => typeof v === 'string') } : {}),
+      ...(allowance ? { allowance } : {}),
       ...(runContract.spec ? { runContract: runContract.spec } : {}),
     },
     errors, warnings,
@@ -512,6 +594,13 @@ export function edgeMapOf(template: GraphTemplateSpec): Record<string, string[]>
     const push = (t: string) => { if (!targets.includes(t)) targets.push(t); };
     if (edge.to) push(edge.to);
     for (const t of Object.values(edge.map ?? {})) push(t);
+    for (const destinations of Object.values(edge.branches ?? {})) for (const destination of destinations) {
+      push(destination);
+      if (edge.join) {
+        const branchTargets = edges[destination] ?? (edges[destination] = []);
+        if (!branchTargets.includes(edge.join)) branchTargets.push(edge.join);
+      }
+    }
     for (const fb of edge.fallback ?? []) push(fb.node);
   }
   return edges;