elanous 0.2.10 → 0.2.12

package/src/field-note/transcribe.ts

@@ -0,0 +1,248 @@
+import type { TranscriptEntry } from './index';
+
+/** Mono, normalized PCM. The capture instant is required for NOTE1's absolute photo alignment. */
+export interface FieldAudio {
+  samples: Float32Array;
+  sampleRate: number;
+  recordedAt: string;
+}
+
+export interface AudioChunk {
+  samples: Float32Array;
+  sampleRate: number;
+  /** Offset from the first sample of the recording, in seconds. */
+  startSeconds: number;
+}
+
+export interface SpeechSegment {
+  /** Start and end in seconds relative to the supplied chunk. */
+  startSeconds: number;
+  endSeconds: number;
+  text: string;
+  speaker?: string;
+}
+
+export interface EngineRequest {
+  language: string;
+  /** Preserve source-language speech rather than translating it. */
+  task: 'transcribe';
+}
+
+export interface TranscriptionEngine {
+  transcribe(chunk: AudioChunk, request: EngineRequest): Promise<readonly SpeechSegment[]>;
+}
+
+/** The caller provides the local Whisper runtime; this module never downloads a model. */
+export interface LocalWhisperClient {
+  transcribe(input: {
+    audio: Float32Array;
+    sampleRate: number;
+    language: string;
+    task: 'transcribe';
+  }): Promise<readonly SpeechSegment[]>;
+}
+
+/** The caller provides authentication/transport; no network call occurs on construction. */
+export interface CloudSttClient {
+  transcribe(input: {
+    audio: Float32Array;
+    sampleRate: number;
+    language: string;
+    timestamps: true;
+    diarization: true;
+  }): Promise<readonly SpeechSegment[]>;
+}
+
+export function createLocalWhisperEngine(client: LocalWhisperClient): TranscriptionEngine {
+  return {
+    transcribe: (chunk, request) => client.transcribe({
+      audio: chunk.samples, sampleRate: chunk.sampleRate, language: request.language, task: request.task,
+    }),
+  };
+}
+
+export function createCloudSttEngine(client: CloudSttClient): TranscriptionEngine {
+  return {
+    transcribe: (chunk, request) => client.transcribe({
+      audio: chunk.samples, sampleRate: chunk.sampleRate, language: request.language,
+      timestamps: true, diarization: true,
+    }),
+  };
+}
+
+export interface TranscriptionOptions {
+  /** Default: ko. */
+  language?: string;
+  /** Default: 30 seconds. */
+  chunkSeconds?: number;
+  /** Default: 2 seconds. Must be shorter than chunkSeconds. */
+  overlapSeconds?: number;
+  /** Used only if an engine omits a speaker label. Otherwise the label remains 화자 미상. */
+  defaultSpeaker?: string;
+}
+
+function validateAudio(audio: FieldAudio): number {
+  if (!Number.isInteger(audio.sampleRate) || audio.sampleRate <= 0) {
+    throw new RangeError('Audio sampleRate must be a positive integer');
+  }
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,3})?(Z|[+-]\d{2}:\d{2})$/.exec(audio.recordedAt);
+  if (!match) throw new RangeError('Audio recordedAt must be an ISO timestamp with a timezone offset');
+  const [, year, month, day, hour, minute, second, zone] = match;
+  const calendar = new Date(Date.UTC(+year!, +month! - 1, +day!, +hour!, +minute!, +second!));
+  const recordedAt = Date.parse(audio.recordedAt);
+  if (calendar.getUTCFullYear() !== +year! || calendar.getUTCMonth() + 1 !== +month! ||
+      calendar.getUTCDate() !== +day! || calendar.getUTCHours() !== +hour! ||
+      calendar.getUTCMinutes() !== +minute! || calendar.getUTCSeconds() !== +second! ||
+      (zone !== 'Z' && (+zone!.slice(1, 3) > 23 || +zone!.slice(4) > 59)) ||
+      !Number.isFinite(recordedAt)) {
+    throw new RangeError('Invalid audio recordedAt timestamp');
+  }
+  return recordedAt;
+}
+
+/** Sample-index arithmetic avoids gaps and drift from repeated floating-point additions. */
+export function splitAudioIntoChunks(audio: FieldAudio, options: TranscriptionOptions = {}): AudioChunk[] {
+  validateAudio(audio);
+  const chunkSeconds = options.chunkSeconds ?? 30;
+  const overlapSeconds = options.overlapSeconds ?? 2;
+  if (!Number.isFinite(chunkSeconds) || !Number.isFinite(overlapSeconds) ||
+      chunkSeconds <= 0 || overlapSeconds < 0 || overlapSeconds >= chunkSeconds) {
+    throw new RangeError('Audio chunk length must exceed nonnegative overlap');
+  }
+  const size = Math.round(chunkSeconds * audio.sampleRate);
+  const overlap = Math.round(overlapSeconds * audio.sampleRate);
+  if (size <= 0 || overlap >= size) throw new RangeError('Audio chunk and overlap must span valid samples');
+  const chunks: AudioChunk[] = [];
+  for (let start = 0; start < audio.samples.length;) {
+    const end = Math.min(start + size, audio.samples.length);
+    chunks.push({ samples: audio.samples.subarray(start, end), sampleRate: audio.sampleRate,
+      startSeconds: start / audio.sampleRate });
+    if (end === audio.samples.length) break;
+    start = end - overlap;
+  }
+  return chunks;
+}
+
+function mergeOverlappingText(left: string, right: string): string | null {
+  if (left === right) return left;
+  if (left.includes(right)) return left;
+  if (right.includes(left)) return right;
+  for (let length = Math.min(left.length, right.length); length >= 2; length--) {
+    if (left.endsWith(right.slice(0, length))) return left + right.slice(length);
+  }
+  return null;
+}
+
+interface TimedSegment {
+  start: number;
+  end: number;
+  speaker: string;
+  text: string;
+  chunkIndex: number;
+}
+
+/** Return absolute ISO timestamps accepted by NOTE1, preserving speaker labels and chronological order. */
+export async function transcribeFieldAudio(
+  audio: FieldAudio,
+  engine: TranscriptionEngine,
+  options: TranscriptionOptions = {},
+): Promise<TranscriptEntry[]> {
+  const origin = validateAudio(audio);
+  const chunks = splitAudioIntoChunks(audio, options);
+  const segments: TimedSegment[] = [];
+  for (const [chunkIndex, chunk] of chunks.entries()) {
+    const result = await engine.transcribe(chunk, { language: options.language ?? 'ko', task: 'transcribe' });
+    const duration = chunk.samples.length / chunk.sampleRate;
+    for (const segment of result) {
+      if (!Number.isFinite(segment.startSeconds) || !Number.isFinite(segment.endSeconds) ||
+          segment.startSeconds < 0 || segment.endSeconds < segment.startSeconds ||
+          // Only floating-point slack — a segment may not end after the chunk's real audio (NOTE3a review must-fix).
+          segment.endSeconds > duration + 1e-9) {
+        throw new RangeError(`Invalid transcription segment times in chunk ${chunkIndex}`);
+      }
+      const text = segment.text.trim();
+      if (!text) continue;
+      segments.push({
+        start: chunk.startSeconds + segment.startSeconds,
+        end: chunk.startSeconds + segment.endSeconds,
+        text, speaker: segment.speaker?.trim() || options.defaultSpeaker?.trim() || '화자 미상',
+        chunkIndex,
+      });
+    }
+  }
+  segments.sort((a, b) => a.chunkIndex - b.chunkIndex || a.start - b.start);
+  const stitched: TimedSegment[] = [];
+  const center = (segment: TimedSegment) => {
+    const source = chunks[segment.chunkIndex]!;
+    return source.startSeconds + source.samples.length / source.sampleRate / 2;
+  };
+  // Engine speaker IDs are chunk-scoped. A later chunk's ID that matched an earlier chunk's speech in the overlap takes
+  // the earlier global label; an ID that never matched is qualified with its chunk so different people never share a label.
+  const unlabeled = new Set(['화자 미상', options.defaultSpeaker?.trim()].filter((label): label is string => !!label));
+  const qualify = (speaker: string, chunkIndex: number) => chunkIndex && !unlabeled.has(speaker) ? `${speaker} · 구간 ${chunkIndex + 1}` : speaker;
+  for (const [chunkIndex, chunk] of chunks.entries()) {
+    const incoming = segments.filter((segment) => segment.chunkIndex === chunkIndex);
+    const speakerMap = new Map<string, string>();
+    const previous = stitched.filter((segment) => segment.chunkIndex === chunkIndex - 1);
+    const sharedStart = chunk.startSeconds;
+    const sharedEnd = chunkIndex ? Math.min(chunk.startSeconds + chunk.samples.length / chunk.sampleRate,
+      chunks[chunkIndex - 1]!.startSeconds + chunks[chunkIndex - 1]!.samples.length / audio.sampleRate) : sharedStart;
+    const eligible = (segment: TimedSegment) => segment.start <= sharedEnd && segment.end >= sharedStart;
+    const consumedPrevious = new Set<TimedSegment>();
+    const consumedIncoming = new Set<TimedSegment>();
+    const replacements: TimedSegment[] = [];
+    // A chunk may split one sentence into several timed segments while its
+    // neighbor reports the entire sentence. Match contiguous groups on both sides.
+    while (sharedEnd > sharedStart) {
+      let best: { earlier: TimedSegment[]; later: TimedSegment[]; text: string } | undefined;
+      for (let a = 0; a < previous.length; a++) {
+        for (let b = a + 1; b <= previous.length; b++) {
+          const earlier = previous.slice(a, b);
+          if (earlier.some((item) => consumedPrevious.has(item) || !eligible(item))) break;
+          for (let c = 0; c < incoming.length; c++) {
+            for (let d = c + 1; d <= incoming.length; d++) {
+              const later = incoming.slice(c, d);
+              if (later.some((item) => consumedIncoming.has(item) || !eligible(item))) break;
+              // Speaker IDs are scoped to each engine call, not stable across chunks.
+              // Keep distinct speakers within a chunk separate, but use speech and time across chunks.
+              if (earlier.some((item) => item.speaker !== earlier[0]!.speaker) ||
+                  later.some((item) => item.speaker !== later[0]!.speaker)) continue;
+              const earlierStart = earlier[0]!.start;
+              const earlierEnd = Math.max(...earlier.map((item) => item.end));
+              const laterStart = later[0]!.start;
+              const laterEnd = Math.max(...later.map((item) => item.end));
+              if (earlier.some((item) => item.start > laterEnd || item.end < laterStart) ||
+                  later.some((item) => item.start > earlierEnd || item.end < earlierStart)) continue;
+              const text = mergeOverlappingText(earlier.map((item) => item.text).join(' '),
+                later.map((item) => item.text).join(' '));
+              if (text !== null && (!best || earlier.length + later.length > best.earlier.length + best.later.length)) {
+                best = { earlier, later, text };
+              }
+            }
+          }
+        }
+      }
+      if (!best) break;
+      for (const item of best.earlier) consumedPrevious.add(item);
+      for (const item of best.later) consumedIncoming.add(item);
+      const earlier = best.earlier[0]!;
+      const later = best.later[0]!;
+      const chosen = Math.abs((later.start + later.end) / 2 - center(later)) <
+        Math.abs((earlier.start + earlier.end) / 2 - center(earlier)) ? later : earlier;
+      // The earlier side already carries a global label; first match decides the mapping for this chunk-local ID.
+      for (const item of best.later) if (!speakerMap.has(item.speaker)) speakerMap.set(item.speaker, earlier.speaker);
+      replacements.push({ ...chosen, speaker: earlier.speaker, chunkIndex, text: best.text,
+        start: Math.min(...best.earlier.map((item) => item.start), ...best.later.map((item) => item.start)),
+        end: Math.max(...best.earlier.map((item) => item.end), ...best.later.map((item) => item.end)) });
+    }
+    for (let i = stitched.length - 1; i >= 0; i--) {
+      if (consumedPrevious.has(stitched[i]!)) stitched.splice(i, 1);
+    }
+    stitched.push(...incoming.filter((item) => !consumedIncoming.has(item))
+      .map((item) => ({ ...item, speaker: speakerMap.get(item.speaker) ?? qualify(item.speaker, chunkIndex) })), ...replacements);
+    stitched.sort((a, b) => a.start - b.start || a.chunkIndex - b.chunkIndex);
+  }
+  return stitched.map(({ start, speaker, text }) => ({
+    speaker, text, timestamp: new Date(origin + Math.round(start * 1000)).toISOString(),
+  }));
+}

package/src/graph-kinds/registry.ts

@@ -22,12 +22,12 @@ export interface NodeKindEntry {
 
 export const HARNESS_CORE_KINDS = ['agent', 'gate', 'git', 'judge', 'observe', 'hitl', 'subgraph'] as const;
 
-// Workflow validation and the palette read the same keys; runtime dispatch remains unchanged.
-export const WORKFLOW_CORE_KINDS = ['prompt', 'bash', 'skill', 'cft', 'approval', 'if', 'switch', 'iteration', 'classify', 'extract', 'set', 'filter', 'template', 'http', 'showroom', 'task', 'scheduleTrigger', 'webhookTrigger', 'discordTrigger', 'telegramTrigger', 'manualTrigger', 'chatTrigger'] as const;
+// Workflow validation, the palette, and executor variant labels read the same keys.
+export const WORKFLOW_CORE_KINDS = ['prompt', 'bash', 'skill', 'cft', 'approval', 'if', 'switch', 'iteration', 'classify', 'extract', 'set', 'filter', 'template', 'http', 'showroom', 'task', 'scheduleTrigger', 'webhookTrigger', 'discordTrigger', 'telegramTrigger', 'manualTrigger', 'chatTrigger', 'subworkflow'] as const;
 
 const descriptions: Record<GraphKind, readonly string[]> = {
   harness: ['Run an agent', 'Check an execution gate', 'Perform git operations', 'Judge an outcome', 'Observe a result', 'Request human input', 'Run a child graph'],
-  workflow: ['Run an LLM prompt', 'Run a shell command', 'Invoke a skill', 'Invoke a CFT method', 'Request approval', 'Branch on a condition', 'Select a case', 'Iterate items', 'Classify input', 'Extract structured data', 'Assign variables', 'Filter items', 'Render a template', 'Make an HTTP request', 'Run a showroom', 'Create a task', 'Start on a schedule', 'Start on a webhook', 'Start on Discord', 'Start on Telegram', 'Start manually', 'Start on chat'],
+  workflow: ['Run an LLM prompt', 'Run a shell command', 'Invoke a skill', 'Invoke a CFT method', 'Request approval', 'Branch on a condition', 'Select a case', 'Iterate items', 'Classify input', 'Extract structured data', 'Assign variables', 'Filter items', 'Render a template', 'Make an HTTP request', 'Run a showroom', 'Create a task', 'Start on a schedule', 'Start on a webhook', 'Start on Discord', 'Start on Telegram', 'Start manually', 'Start on chat', 'Call another workflow'],
 };
 
 const kinds = new Map<GraphKind, Map<string, NodeKindEntry>>();

package/src/graph-runner/graph-cli.ts

@@ -3,8 +3,9 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { writeStdoutJson } from '../cli/stdout-json.js';
+import type { GraphVariantPlan } from '../self-implement/graph-variant.js';
 import { debug } from '../debug/log.js';
-import { decideGraphApproval, graphRunAlive, lastJsonObject, latestGraphRun, listGraphRuns, runGraph, type GraphRunState } from './runner.js';
+import { decideGraphApproval, graphRunAlive, lastJsonObject, latestGraphRun, listGraphRuns, manageGraphRun, runGraph, type GraphRunState } from './runner.js';
 
 function findGraphFile(graphId: string): string | undefined {
   const roots = [resolve('graphs'), resolve(import.meta.dir, '../../graphs')];
@@ -56,6 +57,43 @@ export function registerGraphCommands(program: Command, runsDeps: { root?: strin
         process.exitCode = 1;
       }
     });
+  graph.command('variant <template>')
+    .description('Validate and run a graph variant, preserving the resulting graph beside its run ledger')
+    .requiredOption('--plan <json>', 'JSON variant plan (maxVisits, routes, or growth)')
+    .option('--dry-run', 'Walk the variant without executing commands')
+    .option('--run', 'Execute the validated variant')
+    .option('--json', 'Print run state as JSON')
+    .action(async (file: string, opts: { plan: string; dryRun?: boolean; run?: boolean; json?: boolean }) => {
+      try {
+        if (opts.dryRun === opts.run) throw new Error('choose exactly one of --dry-run or --run');
+        let plan: unknown;
+        try { plan = JSON.parse(opts.plan); } catch { throw new Error('--plan must be a JSON object'); }
+        if (!plan || typeof plan !== 'object' || Array.isArray(plan) ||
+          Object.keys(plan).some(key => !['maxVisits', 'routes', 'growth'].includes(key)) ||
+          (plan as Record<string, unknown>).maxVisits !== undefined &&
+            (typeof (plan as Record<string, unknown>).maxVisits !== 'object' || (plan as Record<string, unknown>).maxVisits === null || Array.isArray((plan as Record<string, unknown>).maxVisits)) ||
+          (plan as Record<string, unknown>).routes !== undefined && (!Array.isArray((plan as Record<string, unknown>).routes) ||
+            !(plan as { routes: unknown[] }).routes.every(route => route !== null && typeof route === 'object' && !Array.isArray(route) &&
+              typeof (route as Record<string, unknown>).from === 'string' && typeof (route as Record<string, unknown>).to === 'string' &&
+              typeof (route as Record<string, unknown>).outcome === 'string')) ||
+          (plan as Record<string, unknown>).growth !== undefined &&
+            (!(plan as Record<string, unknown>).growth || typeof (plan as Record<string, unknown>).growth !== 'object' ||
+              Array.isArray((plan as Record<string, unknown>).growth) ||
+              !(plan as { growth: Record<string, unknown> }).growth.node ||
+              typeof (plan as { growth: Record<string, unknown> }).growth.from !== 'string' ||
+              typeof (plan as { growth: Record<string, unknown> }).growth.outcome !== 'string')) {
+          throw new Error('--plan must be a JSON variant plan');
+        }
+        await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
+        const state = await runGraph(file, { dryRun: opts.dryRun, variant: { goal: 'g_graph_variant', plan: plan as GraphVariantPlan }, deps: { root: runsDeps.root } });
+        if (opts.json) await writeStdoutJson(JSON.stringify(state) + '\n');
+        else console.log(`${state.graphId} ${state.runId}: ${state.status} (${state.path.join(' → ')}, executed: ${state.executed})`);
+        if (state.status !== 'done' && state.status !== 'awaiting-approval') process.exitCode = 1;
+      } catch (error) {
+        console.error(`graph variant: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
   graph.command('tick <file>')
     .description('Advance one graph run, resuming a pending decision or starting only when requested')
     .option('--start', 'Start a new run when the graph is idle')
@@ -139,6 +177,28 @@ export function registerGraphCommands(program: Command, runsDeps: { root?: strin
         process.exitCode = 1;
       }
     });
+  for (const action of ['stop', 'destroy'] as const) {
+    runs.command(`${action} <run_id>`)
+      .description(action === 'stop' ? 'Fail a running or orphaned run so it can be resumed' : 'Stop and delete a run and its owned artifacts')
+      .action(async (runId: string) => {
+        try {
+          // Without the sink the stop/destroy observation lines never reach the log store (only `graph run` had it).
+          await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
+          if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId) || runId === '.' || runId === '..') throw new Error(`invalid run id: ${runId}`);
+          const { runs: all, unreadable } = listGraphRuns(runsDeps.root);
+          const exact = all.filter(state => state.runId === runId);
+          const matches = exact.length ? exact : all.filter(state => state.runId.startsWith(runId));
+          if (matches.length !== 1) throw new Error(matches.length ? `ambiguous run id: ${runId}\n${matches.map(state => `${state.graphId}/${state.runId}`).join('\n')}` : `no run: ${runId}`);
+          const saved = matches[0]!;
+          const state = manageGraphRun(saved.graphId, saved.runId, action, runsDeps.root, runsDeps.processStartMs);
+          console.log(`${state.graphId} ${state.runId}: ${action === 'stop' ? state.status : 'destroyed'}`);
+          warning(unreadable);
+        } catch (error) {
+          console.error(`graph runs ${action}: ${error instanceof Error ? error.message : String(error)}`);
+          process.exitCode = 1;
+        }
+      });
+  }
   runs.command('resume <run_id>')
     .option('--from <node_id>', 'Restart at this node on the saved path')
     .option('--use-current-graph', 'Use the installed graph and enforce the original hash')

package/src/graph-runner/graph-grow-llm.ts

@@ -0,0 +1,47 @@
+import { PROVIDERS, streamLLM } from '../llm.js';
+import { getUserConfig, resolveRoleLlm, type UserConfig } from '../user-config.js';
+import type { GrowthProposal, GrowthProposer } from './graph-grow.js';
+
+type GrowthLLM = (prompt: string) => Promise<string>;
+const OUTPUT_TAIL_LENGTH = 2000;
+
+export function graphGrowthLlmOptions(config: UserConfig): { model?: string; provider?: string } {
+  const role = config.roleLlm?.['graph-grow'];
+  if (!role || (!role.provider && !role.model && !role.tier)) return {};
+  const selected = resolveRoleLlm('graph-grow', { config });
+  return { model: selected.model, provider: selected.provider };
+}
+
+async function defaultGrowthLLM(prompt: string): Promise<string> {
+  const selected = graphGrowthLlmOptions(getUserConfig());
+  return streamLLM([{ role: 'user', content: prompt }], () => {}, {
+    ...(selected.model ? { model: selected.model, provider: PROVIDERS[selected.provider!] } : {}),
+    reasoningEffort: 'low',
+  });
+}
+
+/** Model output is untrusted: structural and side-effect validation belongs to proposeGrowth. */
+export function createLLMGrowthProposer(callLLM: GrowthLLM = defaultGrowthLLM): GrowthProposer {
+  return async (input: Parameters<GrowthProposer>[0]) => {
+    const serializedOutput = typeof input.output === 'string' ? input.output : input.output === undefined ? '' : JSON.stringify(input.output);
+    const prompt = [
+      'Propose exactly one new contracted graph node to handle the unseen outcome and one return edge to an existing node.',
+      'Reply with only JSON: {"node":{"nodeId":"...","kind":"agent","recipe":"none","maxVisits":1,"contract":{"inputs":[],"tools":"read-only","outputs":[]}},"returnTo":"existing-node-id","reason":"..."}.',
+      'Use only an existing recipe type (none, an existing cmd:/approval: recipe ID, or a catalog role); never invent commands. The missing-outcome edge and the return edge are built from node and returnTo after validation.',
+      'Do not alter existing nodes or edges. The proposal will be validated independently; do not assume a recipe is safe.',
+      `Graph snapshot: ${JSON.stringify(input.graph)}`,
+      `Blocked node ID: ${JSON.stringify(input.nodeId)}`,
+      `Unseen outcome: ${JSON.stringify(input.outcome)}`,
+      `Blocked node output tail: ${JSON.stringify(serializedOutput.slice(-OUTPUT_TAIL_LENGTH))}`,
+    ].join('\n');
+    const response = await callLLM(prompt);
+    let parsed: unknown;
+    try { parsed = JSON.parse(response.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '')); }
+    catch { return undefined; }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined;
+    const proposal = parsed as Record<string, unknown>;
+    if (!proposal.node || typeof proposal.node !== 'object' || Array.isArray(proposal.node) ||
+      typeof proposal.reason !== 'string' || !proposal.reason.trim() || typeof proposal.returnTo !== 'string') return undefined;
+    return { node: proposal.node, reason: proposal.reason, returnTo: proposal.returnTo } as GrowthProposal;
+  };
+}

package/src/graph-runner/graph-grow.ts

@@ -0,0 +1,50 @@
+import { createGraphVariant } from '../self-implement/graph-variant.js';
+import type { GraphEdgeSpec, GraphNodeSpec, GraphTemplateSpec } from '../self-implement/graph-yaml.js';
+import { createLLMGrowthProposer } from './graph-grow-llm.js';
+
+export interface GrowthProposal {
+  node: GraphNodeSpec;
+  returnTo?: string;
+  reason: string;
+}
+
+export type GrowthProposer = (input: { graph: GraphTemplateSpec; nodeId: string; outcome: string; runId: string; output?: unknown }) => GrowthProposal | undefined | Promise<GrowthProposal | undefined>;
+export type GrowthRecipeEffect = 'read-only' | 'external-effect' | 'unknown';
+
+export interface GraphGrowth {
+  node: GraphNodeSpec;
+  edges: readonly GraphEdgeSpec[];
+  reason: string;
+  undo: { removeNode: string; removeOutcome: { from: string; outcome: string }; removeEdge?: GraphEdgeSpec };
+}
+
+export async function proposeGrowth(input: Parameters<GrowthProposer>[0],
+  proposer: GrowthProposer = createLLMGrowthProposer(), classifyRecipe?: (node: GraphNodeSpec) => GrowthRecipeEffect): Promise<{ ok: true; graph: GraphTemplateSpec; growth: GraphGrowth } | { ok: false; reason: string; park?: boolean }> {
+  let proposal: GrowthProposal | undefined;
+  try { proposal = await proposer(input); }
+  catch (error) { return { ok: false, reason: `proposer failed: ${String(error)}` }; }
+  if (!proposal) return { ok: false, reason: 'no proposal' };
+  if (!proposal.node || typeof proposal.reason !== 'string' || !proposal.reason.trim()) return { ok: false, reason: 'proposal requires a node and reason' };
+  let result: ReturnType<typeof createGraphVariant>;
+  try {
+    result = createGraphVariant({ template: input.graph, goal: `g_${input.runId.replace(/[^a-z0-9_-]/gi, '_')}`,
+      plan: { growth: { node: proposal.node, from: input.nodeId, outcome: input.outcome, returnTo: proposal.returnTo } } });
+  } catch (error) { return { ok: false, reason: `growth rejected: ${String(error)}` }; }
+  if (!result.ok) return { ok: false, reason: `growth rejected: ${JSON.stringify(result.rejections)}` };
+  // Neither a recipe id nor its declared tools certify arbitrary executable code.
+  // Only a trusted classification of the resolved recipe may authorize execution.
+  let effect: GrowthRecipeEffect = 'unknown';
+  if (proposal.node.recipe !== 'none') {
+    try { effect = classifyRecipe?.(proposal.node) ?? 'unknown'; }
+    catch { effect = 'unknown'; }
+    if (effect !== 'read-only') {
+      return { ok: false, park: true, reason: '사람 확인 필요: external or unclassified side-effect recipe' };
+    }
+  }
+  const edges: GraphEdgeSpec[] = [
+    { from: input.nodeId, on: 'outcome', map: { [input.outcome]: proposal.node.nodeId } },
+    { from: proposal.node.nodeId, to: proposal.returnTo as string },
+  ];
+  return { ok: true, graph: result.template, growth: { node: proposal.node, edges, reason: proposal.reason,
+    undo: { removeNode: proposal.node.nodeId, removeOutcome: { from: input.nodeId, outcome: input.outcome }, removeEdge: edges[1]! } } };
+}