@synergenius/flow-weaver-pack-weaver 0.8.1

package/src/node-types/genesis-escrow-stage.ts

@@ -0,0 +1,104 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import type { GenesisContext, GenesisConfig, GenesisProposal, GenesisOperation, EscrowToken } from '../bot/types.js';
+import { GenesisStore } from '../bot/genesis-store.js';
+
+/**
+ * Separates self-modify operations from the proposal, copies current files
+ * to backup, writes new content to staged, and creates the escrow token.
+ *
+ * @flowWeaver nodeType
+ * @label Genesis Escrow Stage
+ * @input ctx [order:0] - Genesis context (JSON)
+ * @output ctx [order:0] - Genesis context with escrow staging result (JSON)
+ * @output onSuccess [order:-2] - On Success
+ * @output onFailure [order:-1] [hidden] - On Failure
+ */
+export function genesisEscrowStage(ctx: string): {
+  onSuccess: boolean; onFailure: boolean;
+  ctx: string;
+} {
+  const context = JSON.parse(ctx) as GenesisContext;
+  const { env } = context;
+  const config = JSON.parse(context.genesisConfigJson) as GenesisConfig;
+  const proposal = JSON.parse(context.proposalJson!) as GenesisProposal;
+
+  const selfModifyTypes = new Set(['selfModifyWorkflow', 'selfModifyNodeType', 'selfModifyModule']);
+  const selfOps = proposal.operations.filter(op => selfModifyTypes.has(op.type));
+
+  if (selfOps.length === 0) {
+    context.hasSelfModifyOps = false;
+    return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+  }
+
+  // Resolve the pack root (parent of src/)
+  const packRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..');
+
+  const store = new GenesisStore(env.projectDir);
+  store.ensureEscrowDirs();
+
+  const affectedFiles: string[] = [];
+  const stagedHashes: Record<string, string> = {};
+  const backupHashes: Record<string, string> = {};
+
+  try {
+    for (const op of selfOps) {
+      const relFile = op.args.file!;
+
+      // Path traversal protection
+      const normalized = path.normalize(relFile);
+      if (normalized.startsWith('..') || path.isAbsolute(normalized)) {
+        console.error(`\x1b[31m→ Rejected unsafe file path: ${relFile}\x1b[0m`);
+        continue;
+      }
+
+      const absFile = path.resolve(packRoot, relFile);
+      affectedFiles.push(relFile);
+
+      // Backup current file
+      if (fs.existsSync(absFile)) {
+        const backupDest = store.getEscrowBackupPath(relFile);
+        fs.mkdirSync(path.dirname(backupDest), { recursive: true });
+        fs.copyFileSync(absFile, backupDest);
+        backupHashes[relFile] = GenesisStore.hashFile(absFile);
+      }
+
+      // Write staged content then hash the file (consistent with GenesisStore.hashFile)
+      const stagedDest = store.getEscrowStagedPath(relFile);
+      fs.mkdirSync(path.dirname(stagedDest), { recursive: true });
+      fs.writeFileSync(stagedDest, op.args.content!, 'utf-8');
+      stagedHashes[relFile] = GenesisStore.hashFile(stagedDest);
+    }
+
+    const gracePeriod = config.selfEvolveGracePeriod ?? 3;
+
+    const token: EscrowToken = {
+      migrationId: crypto.randomUUID().slice(0, 12),
+      cycleId: context.cycleId,
+      stagedAt: new Date().toISOString(),
+      phase: 'staged',
+      affectedFiles,
+      stagedFileHashes: stagedHashes,
+      backupFileHashes: backupHashes,
+      ownerPid: process.pid,
+      graceRemaining: gracePeriod,
+      graceCycleIds: [],
+    };
+
+    store.saveEscrowToken(token);
+
+    context.hasSelfModifyOps = true;
+    context.selfModifyOpsJson = JSON.stringify(selfOps);
+    context.escrowResultJson = JSON.stringify({ staged: true, migrationId: token.migrationId, files: affectedFiles });
+
+    console.log(`\x1b[36m→ Escrow staged: ${affectedFiles.length} file(s), migration ${token.migrationId}\x1b[0m`);
+    return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`\x1b[31m→ Escrow staging failed: ${msg}\x1b[0m`);
+    store.clearEscrow();
+    context.error = `Escrow staging failed: ${msg}`;
+    return { onSuccess: false, onFailure: true, ctx: JSON.stringify(context) };
+  }
+}

package/src/node-types/genesis-escrow-validate.ts

@@ -0,0 +1,120 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import type { GenesisContext } from '../bot/types.js';
+import { GenesisStore } from '../bot/genesis-store.js';
+
+/**
+ * Validates staged escrow files. For workflows, runs flow-weaver compile+validate
+ * on a temp copy. For TypeScript modules, runs a transpile check.
+ *
+ * @flowWeaver nodeType
+ * @label Genesis Escrow Validate
+ * @input ctx [order:0] - Genesis context (JSON)
+ * @output ctx [order:0] - Genesis context with escrow validation result (JSON)
+ * @output onSuccess [order:-2] - On Success
+ * @output onFailure [order:-1] [hidden] - On Failure
+ */
+export function genesisEscrowValidate(ctx: string): {
+  onSuccess: boolean; onFailure: boolean;
+  ctx: string;
+} {
+  const context = JSON.parse(ctx) as GenesisContext;
+  const { env } = context;
+  const store = new GenesisStore(env.projectDir);
+  const token = store.loadEscrowToken();
+
+  if (!token || token.phase !== 'staged') {
+    // No staged escrow: pass through (not an error, just nothing to validate)
+    return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+  }
+
+  const packRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..');
+
+  try {
+    for (const relFile of token.affectedFiles) {
+      const stagedPath = store.getEscrowStagedPath(relFile);
+      const content = fs.readFileSync(stagedPath, 'utf-8');
+
+      if (relFile.includes('workflows/')) {
+        // Workflow file: write to temp, run compile+validate
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'escrow-validate-'));
+        const tmpFile = path.join(tmpDir, path.basename(relFile));
+        fs.writeFileSync(tmpFile, content, 'utf-8');
+
+        try {
+          execFileSync('flow-weaver', ['compile', tmpFile], {
+            cwd: packRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 30_000,
+          });
+
+          execFileSync('flow-weaver', ['validate', tmpFile], {
+            cwd: packRoot,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 30_000,
+          });
+        } finally {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+      } else {
+        // TypeScript module: transpile check using tsc --noEmit on a temp file
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'escrow-tsc-'));
+        const tmpFile = path.join(tmpDir, path.basename(relFile));
+        fs.writeFileSync(tmpFile, content, 'utf-8');
+
+        // Write a minimal tsconfig for the check
+        const tsconfig = {
+          compilerOptions: {
+            target: 'ES2022',
+            module: 'Node16',
+            moduleResolution: 'Node16',
+            noEmit: true,
+            strict: true,
+            skipLibCheck: true,
+            esModuleInterop: true,
+          },
+          include: [path.basename(relFile)],
+        };
+        fs.writeFileSync(path.join(tmpDir, 'tsconfig.json'), JSON.stringify(tsconfig), 'utf-8');
+
+        try {
+          execFileSync('npx', ['tsc', '--project', path.join(tmpDir, 'tsconfig.json')], {
+            cwd: tmpDir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 30_000,
+          });
+        } finally {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+      }
+    }
+
+    token.phase = 'validated';
+    token.validationResult = { compiled: true, validated: true };
+    store.saveEscrowToken(token);
+
+    console.log('\x1b[32m→ Escrow validation passed\x1b[0m');
+    return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+
+    token.phase = 'rolled-back';
+    token.rollbackReason = `Validation failed: ${msg.slice(0, 500)}`;
+    token.validationResult = { compiled: false, validated: false, error: msg.slice(0, 500) };
+    store.saveEscrowToken(token);
+
+    // Clean up staged files
+    for (const relFile of token.affectedFiles) {
+      try { fs.unlinkSync(store.getEscrowStagedPath(relFile)); } catch { /* ignore */ }
+    }
+
+    console.error(`\x1b[31m→ Escrow validation failed: ${msg.slice(0, 200)}\x1b[0m`);
+    context.error = `Escrow validation failed: ${msg.slice(0, 200)}`;
+    return { onSuccess: false, onFailure: true, ctx: JSON.stringify(context) };
+  }
+}

package/src/node-types/genesis-load-config.ts

@@ -0,0 +1,44 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { WeaverEnv, GenesisConfig, GenesisContext } from '../bot/types.js';
+import { GenesisStore } from '../bot/genesis-store.js';
+
+/**
+ * Loads genesis configuration from the project .genesis directory,
+ * validates the target workflow exists, and generates a new cycle ID.
+ * Creates the initial GenesisContext that threads through the pipeline.
+ *
+ * @flowWeaver nodeType
+ * @expression
+ * @label Genesis Load Config
+ * @input env [order:0] - Weaver environment bundle
+ * @output ctx [order:0] - Genesis context (JSON)
+ * @output onFailure [hidden]
+ */
+export function genesisLoadConfig(env: WeaverEnv): {
+  ctx: string;
+} {
+  const store = new GenesisStore(env.projectDir);
+  const config = store.loadConfig();
+
+  if (!config.targetWorkflow) {
+    throw new Error('Genesis config has no targetWorkflow set. Run "weaver genesis --init" and set it in .genesis/config.json');
+  }
+
+  const targetPath = path.resolve(env.projectDir, config.targetWorkflow);
+  if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isFile()) {
+    throw new Error(`Target workflow not found: ${targetPath}`);
+  }
+
+  const cycleId = GenesisStore.newCycleId();
+  console.log(`\x1b[36m→ Genesis config loaded, cycle ${cycleId}\x1b[0m`);
+
+  const ctx: GenesisContext = {
+    env,
+    genesisConfigJson: JSON.stringify(config),
+    cycleId,
+    startTimeMs: Date.now(),
+  };
+
+  return { ctx: JSON.stringify(ctx) };
+}

package/src/node-types/genesis-observe.ts

@@ -0,0 +1,119 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import type { GenesisFingerprint, GenesisContext } from '../bot/types.js';
+import { getWorkflowDescription } from '../bot/genesis-prompt-context.js';
+
+/**
+ * Fingerprints the project state: hashes .ts files, reads package.json,
+ * captures git branch/commit, scans for workflow files, and hashes the
+ * target workflow content.
+ *
+ * @flowWeaver nodeType
+ * @label Genesis Observe
+ * @input ctx [order:0] - Genesis context (JSON)
+ * @output ctx [order:0] - Genesis context with fingerprintJson (JSON)
+ * @output onSuccess [order:-2] - On Success
+ * @output onFailure [order:-1] [hidden] - On Failure
+ */
+export async function genesisObserve(
+  execute: boolean,
+  ctx: string,
+): Promise<{
+  onSuccess: boolean; onFailure: boolean;
+  ctx: string;
+}> {
+  const context = JSON.parse(ctx) as GenesisContext;
+  const { env } = context;
+  const config = JSON.parse(context.genesisConfigJson);
+
+  if (!execute) {
+    const empty: GenesisFingerprint = {
+      timestamp: new Date().toISOString(),
+      files: {},
+      packageJson: null,
+      gitBranch: null,
+      gitCommit: null,
+      workflowHash: '',
+      existingWorkflows: [],
+    };
+    context.fingerprintJson = JSON.stringify(empty);
+    return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+  }
+
+  const projectDir = env.projectDir;
+
+  try {
+    const files: Record<string, string> = {};
+    const dirsToScan = [projectDir];
+    const srcDir = path.join(projectDir, 'src');
+    if (fs.existsSync(srcDir) && fs.statSync(srcDir).isDirectory()) dirsToScan.push(srcDir);
+
+    for (const dir of dirsToScan) {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith('.ts')) {
+          const filePath = path.join(dir, entry.name);
+          const relPath = path.relative(projectDir, filePath);
+          const content = fs.readFileSync(filePath, 'utf-8');
+          files[relPath] = crypto.createHash('sha256').update(content).digest('hex');
+        }
+      }
+    }
+
+    let packageJson: Record<string, unknown> | null = null;
+    const pkgPath = path.join(projectDir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      packageJson = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    }
+
+    let gitBranch: string | null = null;
+    let gitCommit: string | null = null;
+    try {
+      gitBranch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+        cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+      gitCommit = execFileSync('git', ['rev-parse', 'HEAD'], {
+        cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+    } catch {
+      // Not a git repo or git unavailable
+    }
+
+    const existingWorkflows: string[] = [];
+    for (const [relPath, _hash] of Object.entries(files)) {
+      const filePath = path.join(projectDir, relPath);
+      const content = fs.readFileSync(filePath, 'utf-8');
+      if (content.includes('@flowWeaver workflow')) {
+        existingWorkflows.push(relPath);
+      }
+    }
+
+    const targetPath = path.resolve(projectDir, config.targetWorkflow);
+    const targetContent = fs.readFileSync(targetPath, 'utf-8');
+    const workflowHash = crypto.createHash('sha256').update(targetContent).digest('hex');
+
+    const fingerprint: GenesisFingerprint = {
+      timestamp: new Date().toISOString(),
+      files,
+      packageJson,
+      gitBranch,
+      gitCommit,
+      workflowHash,
+      existingWorkflows,
+    };
+
+    console.log(`\x1b[36m→ Fingerprint: ${Object.keys(files).length} files, ${existingWorkflows.length} workflows\x1b[0m`);
+
+    context.fingerprintJson = JSON.stringify(fingerprint);
+    context.workflowDescription = await getWorkflowDescription(targetPath);
+
+    return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`\x1b[31m→ Observe failed: ${msg}\x1b[0m`);
+    context.fingerprintJson = '{}';
+    return { onSuccess: false, onFailure: true, ctx: JSON.stringify(context) };
+  }
+}

package/src/node-types/genesis-propose.ts

@@ -0,0 +1,86 @@
+import * as path from 'node:path';
+import type { GenesisConfig, GenesisProposal, GenesisContext } from '../bot/types.js';
+import { callAI, parseJsonResponse } from '../bot/ai-client.js';
+import { getGenesisSystemPrompt, getOperationExamples } from '../bot/genesis-prompt-context.js';
+
+/**
+ * Sends project context and diff information to the AI provider, which
+ * returns a structured proposal of workflow operations to apply.
+ *
+ * @flowWeaver nodeType
+ * @label Genesis Propose
+ * @input ctx [order:0] - Genesis context (JSON)
+ * @output ctx [order:0] - Genesis context with proposalJson (JSON)
+ * @output onSuccess [order:-2] - On Success
+ * @output onFailure [order:-1] [hidden] - On Failure
+ */
+export async function genesisPropose(
+  execute: boolean,
+  ctx: string,
+): Promise<{
+  onSuccess: boolean; onFailure: boolean;
+  ctx: string;
+}> {
+  const context = JSON.parse(ctx) as GenesisContext;
+  const { env } = context;
+
+  if (!execute) {
+    const empty: GenesisProposal = { operations: [], totalCost: 0, impactLevel: 'COSMETIC', summary: 'dry run', rationale: '' };
+    context.proposalJson = JSON.stringify(empty);
+    return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+  }
+
+  const { providerInfo: pInfo } = env;
+  const config = JSON.parse(context.genesisConfigJson) as GenesisConfig;
+  const diff = JSON.parse(context.diffJson!);
+  const targetPath = path.resolve(env.projectDir, config.targetWorkflow);
+
+  const systemPrompt = await getGenesisSystemPrompt(config, !!context.stabilized, {
+    selfEvolveLocked: !!context.escrowGraceLocked,
+    graceRemaining: context.escrowGraceRemaining ?? 0,
+  });
+
+  const userPrompt = [
+    '## Current Workflow Structure',
+    context.workflowDescription || '(no description available)',
+    '',
+    '## Project Diff Since Last Cycle',
+    JSON.stringify(diff, null, 2),
+    '',
+    '## Current Fingerprint',
+    context.fingerprintJson!,
+    '',
+    getOperationExamples(targetPath),
+    '',
+    'Propose workflow evolution operations within the budget. Use node IDs and port names that exist in the workflow structure above.',
+  ].join('\n');
+
+  const maxAttempts = 2;
+  let lastError = '';
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const text = await callAI(pInfo, systemPrompt, userPrompt, 8192);
+
+      const proposal = parseJsonResponse(text) as unknown as GenesisProposal;
+      console.log(`\x1b[36m→ Proposal: ${proposal.summary} (${proposal.operations.length} ops, impact=${proposal.impactLevel})\x1b[0m`);
+
+      context.proposalJson = JSON.stringify(proposal);
+      return { onSuccess: true, onFailure: false, ctx: JSON.stringify(context) };
+    } catch (err: unknown) {
+      lastError = err instanceof Error ? err.message : String(err);
+      const isTransient = /ETIMEDOUT|ECONNRESET|ECONNREFUSED|EPIPE|socket hang up/i.test(lastError);
+
+      if (isTransient && attempt < maxAttempts) {
+        console.log(`\x1b[33m→ Proposal attempt ${attempt} failed (transient): ${lastError.slice(0, 100)}. Retrying...\x1b[0m`);
+        continue;
+      }
+
+      console.error(`\x1b[31m→ Proposal failed: ${lastError}\x1b[0m`);
+    }
+  }
+
+  context.error = `Proposal failed: ${lastError}`;
+  context.proposalJson = JSON.stringify({ operations: [], totalCost: 0, impactLevel: 'COSMETIC', summary: `Failed: ${lastError}`, rationale: '' });
+  return { onSuccess: false, onFailure: true, ctx: JSON.stringify(context) };
+}

package/src/node-types/genesis-report.ts

@@ -0,0 +1,95 @@
+import type { GenesisCycleRecord, GenesisContext } from '../bot/types.js';
+
+/**
+ * Formats a genesis cycle summary for console output. Receives context
+ * from either the success path or the fail path. Fires from any
+ * incoming path.
+ *
+ * @flowWeaver nodeType
+ * @expression
+ * @label Genesis Report
+ * @executeWhen DISJUNCTION
+ * @input [successCtx] [order:0] - Genesis context from success path (JSON)
+ * @input [failCtx] [order:1] - Genesis context from apply-retry fail path (JSON)
+ * @input [proposeFailCtx] [order:2] - Genesis context from propose failure (JSON)
+ * @input [commitFailCtx] [order:3] - Genesis context from commit failure (JSON)
+ * @output summary [order:1] - Formatted summary text
+ * @output onFailure [hidden]
+ */
+export function genesisReport(successCtx?: string, failCtx?: string, proposeFailCtx?: string, commitFailCtx?: string): { summary: string } {
+  const ctx = successCtx ?? failCtx ?? proposeFailCtx ?? commitFailCtx;
+  if (!ctx) {
+    const summary = 'Genesis cycle completed with no record';
+    console.log(`\n\x1b[33m${summary}\x1b[0m\n`);
+    return { summary };
+  }
+
+  const context = JSON.parse(ctx) as GenesisContext;
+  const elapsed = formatElapsed(context.startTimeMs);
+
+  if (context.error) {
+    const reason = categorizeFailure(context);
+    let summary = `Genesis: ${reason}`;
+    if (context.applyResultJson) {
+      try {
+        const result = JSON.parse(context.applyResultJson) as { applied: number; failed: number };
+        summary += ` (applied: ${result.applied}, failed: ${result.failed})`;
+      } catch { /* ignore */ }
+    }
+    summary += elapsed ? ` [${elapsed}]` : '';
+    console.log(`\n\x1b[31m${summary}\x1b[0m\n`);
+    return { summary };
+  }
+
+  if (!context.cycleRecordJson) {
+    const summary = `Genesis: no changes proposed${elapsed ? ` [${elapsed}]` : ''}`;
+    console.log(`\n\x1b[33m${summary}\x1b[0m\n`);
+    return { summary };
+  }
+
+  const record = JSON.parse(context.cycleRecordJson) as GenesisCycleRecord;
+
+  const parts: string[] = [`Cycle ${record.id}`];
+
+  if (record.proposal) {
+    parts.push(`${record.proposal.operations.length} ops`);
+    parts.push(`impact=${record.proposal.impactLevel}`);
+  }
+
+  parts.push(record.outcome);
+
+  if (record.approved !== null) {
+    parts.push(record.approved ? 'approved' : 'rejected');
+  }
+
+  if (elapsed) parts.push(elapsed);
+
+  if (record.error) {
+    parts.push(record.error);
+  }
+
+  const summary = `Genesis: ${parts.join(' | ')}`;
+  const color = record.outcome === 'applied' ? '\x1b[32m' : record.outcome === 'error' ? '\x1b[31m' : '\x1b[33m';
+
+  console.log(`\n\x1b[1m${color}${summary}\x1b[0m\n`);
+
+  return { summary };
+}
+
+function formatElapsed(startTimeMs?: number): string {
+  if (!startTimeMs) return '';
+  const seconds = (Date.now() - startTimeMs) / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remaining = seconds % 60;
+  return `${minutes}m${remaining.toFixed(0)}s`;
+}
+
+function categorizeFailure(context: GenesisContext): string {
+  const err = context.error ?? '';
+  if (err.startsWith('Proposal failed')) return 'proposal failed';
+  if (err.includes('not approved') || err.includes('rejected')) return 'proposal rejected';
+  if (err.startsWith('Commit failed')) return 'commit failed';
+  if (err.includes('Apply') || err.includes('compile')) return 'apply/compile failed';
+  return err.slice(0, 120);
+}

package/src/node-types/genesis-snapshot.ts

@@ -0,0 +1,30 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { GenesisConfig, GenesisContext } from '../bot/types.js';
+import { GenesisStore } from '../bot/genesis-store.js';
+
+/**
+ * Saves a snapshot of the target workflow file before any modifications
+ * are applied, enabling rollback if something goes wrong.
+ *
+ * @flowWeaver nodeType
+ * @expression
+ * @label Genesis Snapshot
+ * @input ctx [order:0] - Genesis context (JSON)
+ * @output ctx [order:0] - Genesis context with snapshotPath (JSON)
+ * @output onFailure [hidden]
+ */
+export function genesisSnapshot(ctx: string): { ctx: string } {
+  const context = JSON.parse(ctx) as GenesisContext;
+  const config = JSON.parse(context.genesisConfigJson) as GenesisConfig;
+  const targetPath = path.resolve(context.env.projectDir, config.targetWorkflow);
+  const content = fs.readFileSync(targetPath, 'utf-8');
+
+  const store = new GenesisStore(context.env.projectDir);
+  const snapshotPath = store.saveSnapshot(context.cycleId, content);
+
+  console.log(`\x1b[36m→ Snapshot saved: ${snapshotPath}\x1b[0m`);
+
+  context.snapshotPath = snapshotPath;
+  return { ctx: JSON.stringify(context) };
+}