@jsleekr/graft 5.7.0

package/dist/codegen/hooks.js

@@ -0,0 +1,165 @@
+import { formatExpr } from '../format.js';
+export function generateHook(edge) {
+    if (edge.transforms.length === 0)
+        return null;
+    if (edge.target.kind !== 'direct')
+        return null;
+    const source = edge.source.toLowerCase();
+    const target = edge.target.node.toLowerCase();
+    const { code: transformCode, isCompact, needsCompactFn, needsTruncateFn } = transformsToJs(edge.transforms);
+    const stringify = isCompact ? 'JSON.stringify(result)' : 'JSON.stringify(result, null, 2)';
+    // Build helper functions section
+    const helpers = [];
+    if (needsCompactFn) {
+        helpers.push(COMPACT_FN);
+    }
+    if (needsTruncateFn) {
+        helpers.push(TRUNCATE_FN);
+    }
+    const helperSection = helpers.length > 0 ? '\n' + helpers.join('\n') + '\n' : '';
+    return `#!/usr/bin/env node
+// Auto-generated by Graft Compiler
+// Edge: ${edge.source} -> ${edge.target.node}
+
+const fs = require('fs');
+const path = require('path');
+
+const INPUT = path.resolve('.graft/session/node_outputs/${source}.json');
+const OUTPUT = path.resolve('.graft/session/node_outputs/${source}_to_${target}.json');
+const TOKEN_LOG = path.resolve('.graft/token_log.txt');
+
+if (!fs.existsSync(INPUT)) {
+  // Graceful no-op: this hook fires on ALL Write calls,
+  // so the source output may not exist yet (different agent writing).
+  process.exit(0);
+}
+
+const raw = fs.readFileSync(INPUT, 'utf-8');
+const data = JSON.parse(raw);
+${helperSection}
+${transformCode}
+
+const output = ${stringify};
+fs.writeFileSync(OUTPUT, output);
+
+// Token accounting
+const original = Buffer.byteLength(raw);
+const transformed = Buffer.byteLength(output);
+const reduction = original > 0 ? Math.round((original - transformed) * 100 / original) : 0;
+const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
+
+fs.appendFileSync(TOKEN_LOG, \`[\${timestamp}] Edge ${edge.source}->${edge.target.node} | \${original}B -> \${transformed}B (\${reduction}% reduction)\\n\`);
+`;
+}
+// Compact: recursively remove null, undefined, empty strings, empty arrays, empty objects
+const COMPACT_FN = `function isEmpty(v) {
+  if (v === null || v === undefined || v === '') return true;
+  if (Array.isArray(v) && v.length === 0) return true;
+  if (typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0) return true;
+  return false;
+}
+function compact(data) {
+  if (data === null || data === undefined) return undefined;
+  if (typeof data !== 'object') return data;
+  if (Array.isArray(data)) {
+    return data.map(item => compact(item)).filter(item => !isEmpty(item));
+  }
+  const result = {};
+  for (const [key, val] of Object.entries(data)) {
+    const c = compact(val);
+    if (!isEmpty(c)) result[key] = c;
+  }
+  return result;
+}`;
+// Truncate: proportionally reduce content to fit within token budget
+const TRUNCATE_FN = `function truncate(data, maxTokens) {
+  const maxChars = maxTokens * 4;
+  const json = JSON.stringify(data);
+  if (json.length <= maxChars) return data;
+  if (typeof data === 'string') return data.slice(0, maxChars) + '...';
+  if (typeof data !== 'object' || data === null) return data;
+  const ratio = maxChars / json.length;
+  return truncateDeep(data, ratio);
+}
+function truncateDeep(data, ratio) {
+  if (data === null || data === undefined) return data;
+  if (typeof data === 'string') {
+    const maxLen = Math.max(10, Math.floor(data.length * ratio));
+    return data.length > maxLen ? data.slice(0, maxLen) + '...' : data;
+  }
+  if (Array.isArray(data)) {
+    const maxItems = Math.max(1, Math.floor(data.length * ratio));
+    return data.slice(0, maxItems).map(item => truncateDeep(item, ratio));
+  }
+  if (typeof data === 'object') {
+    const result = {};
+    for (const [key, val] of Object.entries(data)) result[key] = truncateDeep(val, ratio);
+    return result;
+  }
+  return data;
+}`;
+function transformsToJs(transforms) {
+    const selectFields = [];
+    const dropFields = [];
+    const filterExprs = [];
+    let isCompact = false;
+    let truncateTokens = null;
+    for (const t of transforms) {
+        switch (t.type) {
+            case 'select':
+                selectFields.push(...t.fields);
+                break;
+            case 'drop':
+                dropFields.push(t.field);
+                break;
+            case 'filter':
+                filterExprs.push(filterToJs(t));
+                break;
+            case 'compact':
+                isCompact = true;
+                break;
+            case 'truncate':
+                truncateTokens = t.tokens;
+                break;
+        }
+    }
+    const lines = [];
+    if (selectFields.length > 0) {
+        const picks = selectFields.map(f => `  ${JSON.stringify(f)}: data[${JSON.stringify(f)}]`).join(',\n');
+        lines.push(`let result = {\n${picks}\n};`);
+    }
+    else {
+        lines.push('let result = { ...data };');
+    }
+    for (const f of dropFields) {
+        lines.push(`delete result[${JSON.stringify(f)}];`);
+    }
+    for (const expr of filterExprs) {
+        lines.push(expr);
+    }
+    if (isCompact) {
+        lines.push('result = compact(result);');
+    }
+    if (truncateTokens !== null) {
+        lines.push(`result = truncate(result, ${truncateTokens});`);
+    }
+    return {
+        code: lines.join('\n'),
+        isCompact,
+        needsCompactFn: isCompact,
+        needsTruncateFn: truncateTokens !== null,
+    };
+}
+function filterToJs(t) {
+    const { field, condition } = t;
+    if (condition.kind !== 'binary')
+        return `result[${JSON.stringify(field)}] = result[${JSON.stringify(field)}];`;
+    const fieldName = condition.left.kind === 'field_access'
+        ? condition.left.segments[condition.left.segments.length - 1]
+        : formatExpr(condition.left);
+    const valueStr = condition.right.kind === 'literal'
+        ? JSON.stringify(condition.right.value)
+        : formatExpr(condition.right);
+    const op = condition.op === '==' ? '===' : condition.op === '!=' ? '!==' : condition.op;
+    return `result[${JSON.stringify(field)}] = (result[${JSON.stringify(field)}] || []).filter(item => item[${JSON.stringify(fieldName)}] ${op} ${valueStr});`;
+}

package/dist/codegen/orchestration.d.ts

@@ -0,0 +1,3 @@
+import { Program } from '../parser/ast.js';
+import { TokenReport } from '../analyzer/estimator.js';
+export declare function generateOrchestration(program: Program, report: TokenReport): string;

package/dist/codegen/orchestration.js

@@ -0,0 +1,250 @@
+import { ProgramIndex } from '../program-index.js';
+import { formatExpr } from '../format.js';
+export function generateOrchestration(program, report) {
+    const graph = program.graphs[0];
+    if (!graph)
+        return '';
+    const index = new ProgramIndex(program);
+    const memoryNames = new Set(program.memories.map(m => m.name));
+    const edgeMap = new Map();
+    for (const edge of program.edges) {
+        if (edge.target.kind === 'direct' && edge.transforms.length > 0) {
+            edgeMap.set(`${edge.source}->${edge.target.node}`, { transforms: edge.transforms });
+        }
+    }
+    const { text: steps } = generateSteps(graph.flow, report, edgeMap, 1, null, index.nodeMap, memoryNames);
+    // Memory preamble
+    const memorySection = program.memories.length > 0
+        ? `
+## Persistent Memory
+${program.memories.map(m => `- \`${m.name}\`: \`.graft/memory/${m.name.toLowerCase()}.json\` (${m.maxTokens.toLocaleString('en-US')} tokens max)`).join('\n')}
+- Memories persist across runs. Nodes with \`writes\` clauses update memory after execution.
+
+`
+        : '';
+    const paramsSection = graph.params.length > 0
+        ? `\n## Parameters\n${graph.params.map(p => `- ${p.name}: ${p.type}${p.default !== undefined ? ` (default: ${p.default})` : ''}`).join('\n')}\n`
+        : '';
+    return `# Graft Orchestration: ${graph.name}
+
+> Auto-generated by Graft Compiler. Edit the .gft source, not this file.
+${paramsSection}
+## Budget
+Total: ${graph.budget.toLocaleString('en-US')} tokens
+Best case: ${report.bestCase.toLocaleString('en-US')} tokens
+Worst case: ${report.worstCase.toLocaleString('en-US')} tokens
+${memorySection}
+## Execution Plan
+${steps}
+## Token Budget Tracking
+Check \`.graft/token_log.txt\` after each step.
+- 80% consumed: switch remaining agents to compact mode
+- 90% consumed: skip non-critical agents
+
+## Failure Recovery
+- Agent failure: follow on_failure policy in each agent definition
+- Token overrun: switch to compact mode, then skip non-critical steps
+- Complete failure: intermediate results preserved in \`.graft/session/\`
+`;
+}
+function describeTransforms(transforms) {
+    const parts = [];
+    for (const t of transforms) {
+        switch (t.type) {
+            case 'select':
+                parts.push(`keep only fields: ${t.fields.map(f => `\`${f}\``).join(', ')}`);
+                break;
+            case 'drop':
+                parts.push(`remove field \`${t.field}\``);
+                break;
+            case 'compact':
+                parts.push('minify JSON (no whitespace)');
+                break;
+            case 'filter':
+                parts.push(`filter \`${t.field}\` array`);
+                break;
+            case 'truncate':
+                parts.push(`truncate to ${t.tokens} tokens`);
+                break;
+        }
+    }
+    return parts.join(', then ');
+}
+function generateSteps(flow, report, edgeMap, startStep, prevNode, nodeMap, memoryNames) {
+    let text = '';
+    let stepNum = startStep;
+    let prev = prevNode;
+    let prevParallelBranches = [];
+    for (const step of flow) {
+        switch (step.kind) {
+            case 'node': {
+                const lowerName = step.name.toLowerCase();
+                const nodeReport = report.nodes.find(n => n.name === step.name);
+                let inputSource = '';
+                let transformNote = '';
+                if (prev) {
+                    // Single predecessor (sequential)
+                    const edgeInfo = edgeMap.get(`${prev}->${step.name}`);
+                    if (edgeInfo) {
+                        inputSource = `\n- Input: \`.graft/session/node_outputs/${prev.toLowerCase()}_to_${lowerName}.json\``;
+                        transformNote = `\n- **Edge transform**: After ${prev} completes, transform its output: ${describeTransforms(edgeInfo.transforms)}. Save to \`.graft/session/node_outputs/${prev.toLowerCase()}_to_${lowerName}.json\` before starting ${step.name}.`;
+                    }
+                    else {
+                        inputSource = `\n- Input: \`.graft/session/node_outputs/${prev.toLowerCase()}.json\``;
+                    }
+                }
+                else if (prevParallelBranches.length > 0) {
+                    // Multiple predecessors (after parallel block)
+                    const inputs = [];
+                    const transforms = [];
+                    for (const branch of prevParallelBranches) {
+                        const edgeInfo = edgeMap.get(`${branch}->${step.name}`);
+                        if (edgeInfo) {
+                            const transformedPath = `.graft/session/node_outputs/${branch.toLowerCase()}_to_${lowerName}.json`;
+                            inputs.push(`\`${transformedPath}\``);
+                            transforms.push(`- **Edge transform** (${branch} → ${step.name}): ${describeTransforms(edgeInfo.transforms)}. Run: \`node .claude/hooks/${branch.toLowerCase()}-to-${lowerName}.js\` or manually apply. Output: \`${transformedPath}\``);
+                        }
+                        else {
+                            inputs.push(`\`.graft/session/node_outputs/${branch.toLowerCase()}.json\``);
+                        }
+                    }
+                    inputSource = `\n- Inputs: ${inputs.join(', ')}`;
+                    if (transforms.length > 0) {
+                        transformNote = '\n' + transforms.join('\n');
+                    }
+                }
+                let memoryLines = '';
+                let additionalInputs = '';
+                const nodeDecl = nodeMap.get(step.name);
+                if (nodeDecl) {
+                    const memReads = nodeDecl.reads.filter(r => memoryNames.has(r.context));
+                    for (const mr of memReads) {
+                        memoryLines += `\n- Memory load: \`.graft/memory/${mr.context.toLowerCase()}.json\``;
+                    }
+                    for (const w of nodeDecl.writes) {
+                        if (memoryNames.has(w.memory)) {
+                            memoryLines += `\n- Memory save: \`.graft/memory/${w.memory.toLowerCase()}.json\``;
+                        }
+                    }
+                    // List produces-type reads that aren't covered by edges
+                    for (const ref of nodeDecl.reads) {
+                        if (memoryNames.has(ref.context))
+                            continue; // already handled as memory
+                        // Find the node that produces this type
+                        const producerNode = [...nodeMap.values()].find(n => n.produces.name === ref.context);
+                        if (!producerNode || producerNode.name === step.name)
+                            continue;
+                        // Skip if already covered by edge-based input/transform
+                        const edgeKey = `${producerNode.name}->${step.name}`;
+                        if (edgeMap.has(edgeKey))
+                            continue;
+                        // Skip if already in prevParallelBranches list (these are covered by the parallel input resolution above)
+                        if (prevParallelBranches.includes(producerNode.name))
+                            continue;
+                        // Skip if this is the immediate sequential predecessor (already covered)
+                        if (prev === producerNode.name)
+                            continue;
+                        additionalInputs += `\n- Also reads: \`.graft/session/node_outputs/${producerNode.name.toLowerCase()}.json\` (${ref.context})`;
+                    }
+                }
+                text += `
+### Step ${stepNum}: ${step.name} [sequential]
+- Agent: ${lowerName}${inputSource}${transformNote}${additionalInputs}${memoryLines}
+- Expected tokens: input ~${nodeReport?.estimatedIn.toLocaleString('en-US') || '?'} / output ~${nodeReport?.estimatedOut.toLocaleString('en-US') || '?'}
+- Completion: \`===NODE_COMPLETE:${lowerName}===\`
+- Output: \`.graft/session/node_outputs/${lowerName}.json\`
+`;
+                prev = step.name;
+                prevParallelBranches = [];
+                stepNum++;
+                break;
+            }
+            case 'parallel': {
+                const branchList = step.branches.join(', ');
+                text += `
+### Step ${stepNum}: [parallel] ${branchList}
+- **Dispatch all ${step.branches.length} agents concurrently** using the Agent tool in a single message
+- Wait for all to complete before proceeding
+`;
+                // Collect edge transforms from preceding sequential node into parallel branches
+                const incomingTransforms = [];
+                for (const branchName of step.branches) {
+                    const lowerName = branchName.toLowerCase();
+                    const nodeReport = report.nodes.find(n => n.name === branchName);
+                    let branchInputNote = '';
+                    if (prev) {
+                        const edgeInfo = edgeMap.get(`${prev}->${branchName}`);
+                        if (edgeInfo) {
+                            const transformedPath = `.graft/session/node_outputs/${prev.toLowerCase()}_to_${lowerName}.json`;
+                            branchInputNote = ` [input: \`${transformedPath}\`]`;
+                            incomingTransforms.push(`- **Edge transform** (${prev} → ${branchName}): ${describeTransforms(edgeInfo.transforms)}. Run: \`node .claude/hooks/${prev.toLowerCase()}-to-${lowerName}.js\` or manually apply. Output: \`${transformedPath}\``);
+                        }
+                        else {
+                            branchInputNote = ` [input: \`.graft/session/node_outputs/${prev.toLowerCase()}.json\`]`;
+                        }
+                    }
+                    let branchMemAnnotations = '';
+                    const branchDecl = nodeMap.get(branchName);
+                    if (branchDecl) {
+                        const memReads = branchDecl.reads.filter(r => memoryNames.has(r.context));
+                        for (const mr of memReads) {
+                            branchMemAnnotations += ` [mem-read: ${mr.context.toLowerCase()}]`;
+                        }
+                        for (const w of branchDecl.writes) {
+                            if (memoryNames.has(w.memory)) {
+                                branchMemAnnotations += ` [mem-write: ${w.memory.toLowerCase()}]`;
+                            }
+                        }
+                    }
+                    text += `- Agent: ${lowerName} -- tokens: input ~${nodeReport?.estimatedIn.toLocaleString('en-US') || '?'} / output ~${nodeReport?.estimatedOut.toLocaleString('en-US') || '?'}${branchInputNote}${branchMemAnnotations}
+`;
+                }
+                if (incomingTransforms.length > 0) {
+                    text += incomingTransforms.join('\n') + '\n';
+                }
+                text += `- Completion: all ${step.branches.length} \`===NODE_COMPLETE===\` signals received
+`;
+                // Track parallel branches for downstream edge resolution
+                prevParallelBranches = [...step.branches];
+                prev = null;
+                stepNum++;
+                break;
+            }
+            case 'foreach': {
+                text += `
+### Step ${stepNum}: [foreach over ${step.source}.output.${step.field}, max ${step.maxIterations} iterations]
+- For each \`${step.binding}\` in list:
+`;
+                let subLetter = 'a';
+                for (const bodyStep of step.body) {
+                    if (bodyStep.kind === 'node') {
+                        text += `  - Sub-step ${stepNum}${subLetter}: ${bodyStep.name} [foreach-body]
+`;
+                        subLetter = String.fromCharCode(subLetter.charCodeAt(0) + 1);
+                    }
+                }
+                text += `- Completion: all iterations done or list exhausted
+`;
+                prev = null;
+                stepNum++;
+                break;
+            }
+            case 'let':
+                text += `
+### Step ${stepNum}: [data binding] let ${step.name}
+- Bind: \`${step.name}\` = \`${formatExpr(step.value)}\`
+`;
+                stepNum++;
+                break;
+            case 'graph_call':
+                text += `
+### Step ${stepNum}: [sub-pipeline] ${step.name}(${step.args.map(a => `${a.name}: ${formatExpr(a.value)}`).join(', ')})
+- Execute graph \`${step.name}\` with parameters
+`;
+                stepNum++;
+                prev = null;
+                break;
+        }
+    }
+    return { text, nextStep: stepNum, lastNode: prev };
+}

package/dist/codegen/settings.d.ts

@@ -0,0 +1,36 @@
+import { Program } from '../parser/ast.js';
+import { ProgramIndex } from '../program-index.js';
+export interface GraftSettings {
+    model: string;
+    permissions: {
+        allow: string[];
+    };
+    graft: {
+        version: string;
+        source: string;
+        compiled_at: string;
+        budget: {
+            total: number;
+            warning_threshold: number;
+            critical_threshold: number;
+        };
+        model_routing: {
+            default: string;
+            overrides: Record<string, string>;
+        };
+    };
+    hooks: {
+        PostToolUse: HookEntry[];
+    };
+}
+interface HookCommand {
+    type: 'command';
+    command: string;
+    if?: string;
+}
+interface HookEntry {
+    matcher: string;
+    hooks: HookCommand[];
+}
+export declare function generateSettings(program: Program, sourceFile: string, index?: ProgramIndex): GraftSettings;
+export {};

package/dist/codegen/settings.js

@@ -0,0 +1,87 @@
+import { MODEL_MAP, BUDGET_WARNING_THRESHOLD, BUDGET_CRITICAL_THRESHOLD } from '../constants.js';
+import { VERSION } from '../version.js';
+import { ProgramIndex } from '../program-index.js';
+/**
+ * Find the first 'node'-kind FlowNode name from a FlowNode array.
+ * Returns undefined if no node-kind step exists.
+ */
+function findFirstNodeName(flow) {
+    for (const step of flow) {
+        switch (step.kind) {
+            case 'node':
+                return step.name;
+            case 'parallel':
+                return step.branches[0];
+            case 'foreach':
+                return findFirstNodeName(step.body);
+            case 'let':
+                break;
+            case 'graph_call':
+                break;
+        }
+    }
+    return undefined;
+}
+export function generateSettings(program, sourceFile, index) {
+    const idx = index ?? new ProgramIndex(program);
+    const graph = program.graphs[0];
+    const firstNodeName = graph ? findFirstNodeName(graph.flow) : undefined;
+    const firstNodeModel = firstNodeName
+        ? idx.nodeMap.get(firstNodeName)?.model
+        : undefined;
+    const defaultModel = firstNodeModel
+        ? (MODEL_MAP[firstNodeModel] || firstNodeModel)
+        : MODEL_MAP.sonnet;
+    const overrides = {};
+    for (const node of program.nodes) {
+        const resolved = MODEL_MAP[node.model] || node.model;
+        if (resolved !== defaultModel) {
+            overrides[node.name.toLowerCase()] = resolved;
+        }
+    }
+    // Collect all hook commands, then merge into a single "Write" matcher entry
+    const hookCommands = [];
+    for (const edge of program.edges) {
+        if (edge.transforms.length === 0)
+            continue;
+        if (edge.target.kind !== 'direct')
+            continue;
+        const source = edge.source.toLowerCase();
+        const target = edge.target.node.toLowerCase();
+        hookCommands.push({
+            type: 'command',
+            command: `node .claude/hooks/${source}-to-${target}.js`,
+            if: `Write(.graft/session/node_outputs/${source}.json)`,
+        });
+    }
+    const hookEntries = [];
+    if (hookCommands.length > 0) {
+        hookEntries.push({
+            matcher: 'Write',
+            hooks: hookCommands,
+        });
+    }
+    return {
+        model: defaultModel,
+        permissions: {
+            allow: ['Read', 'Write', 'Edit', 'Bash', 'Skill'],
+        },
+        graft: {
+            version: VERSION,
+            source: sourceFile,
+            compiled_at: new Date().toISOString(),
+            budget: {
+                total: graph?.budget || 0,
+                warning_threshold: BUDGET_WARNING_THRESHOLD,
+                critical_threshold: BUDGET_CRITICAL_THRESHOLD,
+            },
+            model_routing: {
+                default: defaultModel,
+                overrides,
+            },
+        },
+        hooks: {
+            PostToolUse: hookEntries,
+        },
+    };
+}

package/dist/compiler.d.ts

@@ -0,0 +1,21 @@
+import { TokenReport } from './analyzer/estimator.js';
+import { GeneratedFile } from './codegen/codegen.js';
+import { GraftError } from './errors/diagnostics.js';
+import { Program } from './parser/ast.js';
+import { ProgramIndex } from './program-index.js';
+export interface ProgramResult {
+    success: boolean;
+    program?: Program;
+    index?: ProgramIndex;
+    report?: TokenReport;
+    errors: GraftError[];
+    warnings: GraftError[];
+}
+export interface CompileResult extends ProgramResult {
+    files?: GeneratedFile[];
+}
+export declare function compileToProgram(source: string, sourceFile: string): ProgramResult;
+export declare function compileAndGenerate(source: string, sourceFile: string): CompileResult;
+/** Backward-compatible alias for compileAndGenerate */
+export declare function compile(source: string, sourceFile: string): CompileResult;
+export declare function compileAndWrite(source: string, sourceFile: string, outDir: string): CompileResult;

package/dist/compiler.js

@@ -0,0 +1,101 @@
+import * as path from 'node:path';
+import { Lexer } from './lexer/lexer.js';
+import { Parser } from './parser/parser.js';
+import { resolve } from './resolver/resolver.js';
+import { ScopeChecker } from './analyzer/scope.js';
+import { TypeChecker } from './analyzer/types.js';
+import { TokenEstimator } from './analyzer/estimator.js';
+import { generate, writeFiles } from './codegen/codegen.js';
+import { GraftError } from './errors/diagnostics.js';
+import { ProgramIndex } from './program-index.js';
+export function compileToProgram(source, sourceFile) {
+    const errors = [];
+    const warnings = [];
+    // Lex
+    let tokens;
+    try {
+        const lexer = new Lexer(source);
+        tokens = lexer.tokenize();
+    }
+    catch (e) {
+        if (e instanceof GraftError) {
+            return { success: false, errors: [e], warnings };
+        }
+        throw e;
+    }
+    // Parse
+    const { program: parsedProgram, errors: parseErrors } = new Parser(tokens).parse();
+    let program = parsedProgram;
+    errors.push(...parseErrors);
+    if (parseErrors.length > 0) {
+        return { success: false, program, errors, warnings };
+    }
+    // Set sourceFile on all entry declarations
+    const absSourceFile = path.resolve(sourceFile);
+    for (const c of program.contexts)
+        c.sourceFile = absSourceFile;
+    for (const n of program.nodes)
+        n.sourceFile = absSourceFile;
+    // Resolve imports
+    if (program.imports.length > 0) {
+        const resolveResult = resolve(program, sourceFile);
+        if (resolveResult.errors.length > 0) {
+            errors.push(...resolveResult.errors);
+            return { success: false, program, errors, warnings };
+        }
+        program = resolveResult.program;
+    }
+    // Build ProgramIndex once (after resolve, before analyzers)
+    const index = new ProgramIndex(program);
+    // Analyze: scope
+    const scopeDiagnostics = new ScopeChecker(program, index).check();
+    // Analyze: types (ratchet v3.0-R4: TypeChecker migrated to ProgramIndex)
+    const typeDiagnostics = new TypeChecker(program, index).check();
+    // Separate errors from warnings
+    for (const d of [...scopeDiagnostics, ...typeDiagnostics]) {
+        if (d.severity === 'warning') {
+            warnings.push(d);
+        }
+        else {
+            errors.push(d);
+        }
+    }
+    if (errors.length > 0) {
+        return { success: false, program, index, errors, warnings };
+    }
+    // Analyze: tokens
+    const report = new TokenEstimator(program, index).estimate();
+    warnings.push(...report.warnings);
+    return { success: true, program, index, report, errors, warnings };
+}
+export function compileAndGenerate(source, sourceFile) {
+    const result = compileToProgram(source, sourceFile);
+    if (!result.success || !result.program) {
+        return result;
+    }
+    // Guard: no graph declaration (codegen prerequisite)
+    if (result.program.graphs.length === 0) {
+        return {
+            ...result,
+            success: false,
+            errors: [
+                ...result.errors,
+                new GraftError('No graph declaration found', { line: 1, column: 1, offset: 0 }, 'error', 'GRAPH_MISSING'),
+            ],
+        };
+    }
+    // Generate
+    const files = generate(result.program, result.report, sourceFile, result.index);
+    return { ...result, files };
+}
+/** Backward-compatible alias for compileAndGenerate */
+export function compile(source, sourceFile) {
+    return compileAndGenerate(source, sourceFile);
+}
+export function compileAndWrite(source, sourceFile, outDir) {
+    const result = compile(source, sourceFile);
+    if (result.success && result.files) {
+        writeFiles(result.files, outDir);
+    }
+    return result;
+}

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const MODEL_MAP: Record<string, string>;
+/** Fraction of tokens estimated for a single-field read (vs full context). */
+export declare const PARTIAL_FIELD_FACTOR = 0.3;
+/** Budget fraction at which to emit a warning. */
+export declare const BUDGET_WARNING_THRESHOLD = 0.8;
+/** Budget fraction at which to emit a critical warning. */
+export declare const BUDGET_CRITICAL_THRESHOLD = 0.9;
+/** Maximum depth for conditional chain traversal in both estimation and runtime. */
+export declare const MAX_CONDITIONAL_HOPS = 10;