@karmaniverous/jeeves-meta 0.1.0

package/dist/index.js

@@ -0,0 +1,1394 @@
+import { readdirSync, unlinkSync, readFileSync, mkdirSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { join, dirname, relative, sep } from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { z } from 'zod';
+
+/**
+ * List archive snapshot files in chronological order.
+ *
+ * @module archive/listArchive
+ */
+/**
+ * List archive .json files sorted chronologically (oldest first).
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns Array of absolute paths to archive files, or empty if none.
+ */
+function listArchiveFiles(metaPath) {
+    const archiveDir = join(metaPath, 'archive');
+    try {
+        return readdirSync(archiveDir)
+            .filter((f) => f.endsWith('.json'))
+            .sort()
+            .map((f) => join(archiveDir, f));
+    }
+    catch {
+        return [];
+    }
+}
+
+/**
+ * Prune old archive snapshots beyond maxArchive.
+ *
+ * @module archive/prune
+ */
+/**
+ * Prune archive directory to keep at most maxArchive snapshots.
+ * Removes the oldest files.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @param maxArchive - Maximum snapshots to retain.
+ * @returns Number of files pruned.
+ */
+function pruneArchive(metaPath, maxArchive) {
+    const files = listArchiveFiles(metaPath);
+    const toRemove = files.length - maxArchive;
+    if (toRemove <= 0)
+        return 0;
+    for (let i = 0; i < toRemove; i++) {
+        unlinkSync(files[i]);
+    }
+    return toRemove;
+}
+
+/**
+ * Read the latest archive snapshot for steer change detection.
+ *
+ * @module archive/readLatest
+ */
+/**
+ * Read the most recent archive snapshot.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns The latest archived meta, or null if no archives exist.
+ */
+function readLatestArchive(metaPath) {
+    const files = listArchiveFiles(metaPath);
+    if (files.length === 0)
+        return null;
+    const raw = readFileSync(files[files.length - 1], 'utf8');
+    return JSON.parse(raw);
+}
+
+/**
+ * Create archive snapshots of meta.json.
+ *
+ * Copies current meta.json to archive/\{ISO-timestamp\}.json with
+ * _archived: true and _archivedAt added.
+ *
+ * @module archive/snapshot
+ */
+/**
+ * Create an archive snapshot of the current meta.json.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @param meta - Current meta.json content.
+ * @returns The archive file path.
+ */
+function createSnapshot(metaPath, meta) {
+    const archiveDir = join(metaPath, 'archive');
+    mkdirSync(archiveDir, { recursive: true });
+    const now = new Date().toISOString().replace(/[:.]/g, '-');
+    const archiveFile = join(archiveDir, now + '.json');
+    const archived = {
+        ...meta,
+        _archived: true,
+        _archivedAt: new Date().toISOString(),
+    };
+    writeFileSync(archiveFile, JSON.stringify(archived, null, 2) + '\n');
+    return archiveFile;
+}
+
+/**
+ * Ensure meta.json exists in each .meta/ directory.
+ *
+ * If meta.json is missing, creates it with a generated UUID.
+ *
+ * @module discovery/ensureMetaJson
+ */
+/**
+ * Ensure meta.json exists at the given .meta/ path.
+ *
+ * @param metaPath - Absolute path to a .meta/ directory.
+ * @returns The meta.json content (existing or newly created).
+ */
+function ensureMetaJson(metaPath) {
+    const filePath = join(metaPath, 'meta.json');
+    if (existsSync(filePath)) {
+        const raw = readFileSync(filePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    // Create the archive subdirectory while we're at it
+    const archivePath = join(metaPath, 'archive');
+    if (!existsSync(archivePath)) {
+        mkdirSync(archivePath, { recursive: true });
+    }
+    const meta = { _id: randomUUID() };
+    writeFileSync(filePath, JSON.stringify(meta, null, 2) + '\n');
+    return meta;
+}
+
+/**
+ * Glob watchPaths for .meta/ directories.
+ *
+ * Walks each watchPath recursively, collecting directories named '.meta'
+ * that contain (or will contain) a meta.json file.
+ *
+ * @module discovery/globMetas
+ */
+/**
+ * Recursively find all .meta/ directories under the given paths.
+ *
+ * @param watchPaths - Root directories to search.
+ * @returns Array of absolute paths to .meta/ directories.
+ */
+function globMetas(watchPaths) {
+    const results = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return; // Skip unreadable directories
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isDirectory())
+                continue;
+            if (entry === '.meta') {
+                results.push(full);
+            }
+            else {
+                walk(full);
+            }
+        }
+    }
+    for (const wp of watchPaths) {
+        walk(wp);
+    }
+    return results;
+}
+
+/**
+ * Build the ownership tree from discovered .meta/ paths.
+ *
+ * Each .meta/ directory owns its parent directory and all descendants,
+ * except subtrees that contain their own .meta/. For those subtrees,
+ * the parent meta consumes the child meta's synthesis output.
+ *
+ * @module discovery/ownershipTree
+ */
+/** Normalize path separators to forward slashes for consistent comparison. */
+function normalizePath$1(p) {
+    return p.split(sep).join('/');
+}
+/**
+ * Build an ownership tree from an array of .meta/ directory paths.
+ *
+ * @param metaPaths - Absolute paths to .meta/ directories.
+ * @returns The ownership tree with parent/child relationships.
+ */
+function buildOwnershipTree(metaPaths) {
+    const nodes = new Map();
+    // Create nodes, sorted by ownerPath length (shortest first = shallowest)
+    const sorted = [...metaPaths]
+        .map((mp) => ({
+        metaPath: normalizePath$1(mp),
+        ownerPath: normalizePath$1(dirname(mp)),
+    }))
+        .sort((a, b) => a.ownerPath.length - b.ownerPath.length);
+    for (const { metaPath, ownerPath } of sorted) {
+        nodes.set(metaPath, {
+            metaPath,
+            ownerPath,
+            treeDepth: 0,
+            children: [],
+            parent: null,
+        });
+    }
+    const roots = [];
+    // For each node, find its closest ancestor meta
+    for (const node of nodes.values()) {
+        let bestParent = null;
+        let bestParentLen = -1;
+        for (const candidate of nodes.values()) {
+            if (candidate === node)
+                continue;
+            // Check if node's ownerPath is under candidate's ownerPath
+            const rel = relative(candidate.ownerPath, node.ownerPath);
+            if (rel.startsWith('..') || rel === '')
+                continue;
+            // candidate.ownerPath is an ancestor of node.ownerPath
+            if (candidate.ownerPath.length > bestParentLen) {
+                bestParent = candidate;
+                bestParentLen = candidate.ownerPath.length;
+            }
+        }
+        if (bestParent) {
+            node.parent = bestParent;
+            node.treeDepth = bestParent.treeDepth + 1;
+            bestParent.children.push(node);
+        }
+        else {
+            roots.push(node);
+        }
+    }
+    return { nodes, roots };
+}
+
+/**
+ * Compute the file scope owned by a meta node.
+ *
+ * A meta owns: parent dir + all descendants, minus child .meta/ subtrees.
+ * For child subtrees, it consumes the child's .meta/meta.json as a rollup input.
+ *
+ * @module discovery/scope
+ */
+/**
+ * Get the scope path prefix for a meta node.
+ *
+ * This is the ownerPath — all files under this path are in scope,
+ * except subtrees owned by child metas.
+ *
+ * @param node - The meta node to compute scope for.
+ * @returns The scope path prefix.
+ */
+function getScopePrefix(node) {
+    return node.ownerPath;
+}
+/**
+ * Get paths that should be excluded from the scope (child meta subtrees).
+ *
+ * @param node - The meta node to compute exclusions for.
+ * @returns Array of path prefixes to exclude from scope queries.
+ */
+function getScopeExclusions(node) {
+    return node.children.map((child) => child.ownerPath);
+}
+/**
+ * Filter a list of file paths to only those in scope for a meta node.
+ *
+ * Includes files under ownerPath, excludes files under child meta ownerPaths,
+ * but includes child .meta/meta.json files as rollup inputs.
+ *
+ * @param node - The meta node.
+ * @param files - Array of file paths to filter.
+ * @returns Filtered array of in-scope file paths.
+ */
+function filterInScope(node, files) {
+    const prefix = node.ownerPath + '/';
+    const exclusions = node.children.map((c) => c.ownerPath + '/');
+    const childMetaJsons = new Set(node.children.map((c) => c.metaPath + '/meta.json'));
+    return files.filter((f) => {
+        const normalized = f.split('\\').join('/');
+        // Must be under ownerPath
+        if (!normalized.startsWith(prefix) && normalized !== node.ownerPath)
+            return false;
+        // Check if under a child meta's subtree
+        for (const excl of exclusions) {
+            if (normalized.startsWith(excl)) {
+                // Exception: child meta.json files are included as rollup inputs
+                return childMetaJsons.has(normalized);
+            }
+        }
+        return true;
+    });
+}
+
+/**
+ * Exponential moving average helper for token tracking.
+ *
+ * @module ema
+ */
+const DEFAULT_DECAY = 0.3;
+/**
+ * Compute exponential moving average.
+ *
+ * @param current - New observation.
+ * @param previous - Previous EMA value, or undefined for first observation.
+ * @param decay - Decay factor (0-1). Higher = more weight on new value. Default 0.3.
+ * @returns Updated EMA.
+ */
+function computeEma(current, previous, decay = DEFAULT_DECAY) {
+    if (previous === undefined)
+        return current;
+    return decay * current + (1 - decay) * previous;
+}
+
+/**
+ * Paginated scan helper for exhaustive scope enumeration.
+ *
+ * @module paginatedScan
+ */
+/**
+ * Perform a paginated scan that follows cursor tokens until exhausted.
+ *
+ * @param watcher - WatcherClient instance.
+ * @param params - Base scan parameters (cursor is managed internally).
+ * @returns All matching files across all pages.
+ */
+async function paginatedScan(watcher, params) {
+    const allFiles = [];
+    let cursor;
+    do {
+        const result = await watcher.scan({ ...params, cursor });
+        allFiles.push(...result.files);
+        cursor = result.next;
+    } while (cursor);
+    return allFiles;
+}
+
+/**
+ * Build the SynthContext for a synthesis cycle.
+ *
+ * Computes shared inputs once: scope files, delta files, child meta outputs,
+ * previous content/feedback, steer, and archive paths.
+ *
+ * @module orchestrator/contextPackage
+ */
+/**
+ * Condense a file list into glob-like summaries.
+ * Groups by directory + extension pattern.
+ *
+ * @param files - Array of file paths.
+ * @param maxIndividual - Show individual files up to this count.
+ * @returns Condensed summary string.
+ */
+function condenseScopeFiles(files, maxIndividual = 30) {
+    if (files.length <= maxIndividual)
+        return files.join('\n');
+    // Group by dir + extension
+    const groups = new Map();
+    for (const f of files) {
+        const dir = f.substring(0, f.lastIndexOf('/') + 1) || './';
+        const ext = f.includes('.') ? f.substring(f.lastIndexOf('.')) : '(no ext)';
+        const key = dir + '*' + ext;
+        groups.set(key, (groups.get(key) ?? 0) + 1);
+    }
+    // Sort by count descending
+    const sorted = [...groups.entries()].sort((a, b) => b[1] - a[1]);
+    return sorted
+        .map(([pattern, count]) => pattern + ' (' + count.toString() + ' files)')
+        .join('\n');
+}
+/** Filter files to exclude child meta subtrees. */
+function excludeChildSubtrees(files, childPrefixes) {
+    if (childPrefixes.length === 0)
+        return files;
+    return files.filter((f) => childPrefixes.every((cp) => !f.startsWith(cp)));
+}
+/**
+ * Build the context package for a synthesis cycle.
+ *
+ * @param node - The meta node being synthesized.
+ * @param meta - Current meta.json content.
+ * @param watcher - WatcherClient for scope enumeration.
+ * @returns The computed context package.
+ */
+async function buildContextPackage(node, meta, watcher) {
+    const childPrefixes = node.children.map((c) => c.ownerPath + '/');
+    // Scope files via watcher scan, excluding child subtrees
+    const allScanFiles = await paginatedScan(watcher, {
+        pathPrefix: node.ownerPath,
+    });
+    const allFiles = allScanFiles.map((f) => f.file_path);
+    const scopeFiles = excludeChildSubtrees(allFiles, childPrefixes);
+    // Delta files: modified since _generatedAt
+    let deltaFiles;
+    if (meta._generatedAt) {
+        const modifiedAfter = Math.floor(new Date(meta._generatedAt).getTime() / 1000);
+        const deltaScanFiles = await paginatedScan(watcher, {
+            pathPrefix: node.ownerPath,
+            modifiedAfter,
+        });
+        deltaFiles = excludeChildSubtrees(deltaScanFiles.map((f) => f.file_path), childPrefixes);
+    }
+    else {
+        deltaFiles = scopeFiles; // First run: all files are delta
+    }
+    // Child meta outputs
+    const childMetas = {};
+    for (const child of node.children) {
+        const childMetaFile = join(child.metaPath, 'meta.json');
+        try {
+            const raw = readFileSync(childMetaFile, 'utf8');
+            const childMeta = JSON.parse(raw);
+            childMetas[child.ownerPath] = childMeta._content ?? null;
+        }
+        catch {
+            childMetas[child.ownerPath] = null;
+        }
+    }
+    // Archive paths
+    const archives = listArchiveFiles(node.metaPath);
+    return {
+        path: node.metaPath,
+        scopeFiles,
+        deltaFiles,
+        childMetas,
+        previousContent: meta._content ?? null,
+        previousFeedback: meta._feedback ?? null,
+        steer: meta._steer ?? null,
+        archives,
+    };
+}
+
+/**
+ * Build task prompts for each synthesis step.
+ *
+ * @module orchestrator/buildTask
+ */
+/** Append optional context sections shared across all step prompts. */
+function appendSharedSections(sections, ctx, options) {
+    const opts = {
+        includeSteer: true,
+        includePreviousContent: true,
+        includePreviousFeedback: true,
+        feedbackHeading: '## PREVIOUS FEEDBACK',
+        includeChildMetas: true,
+        ...options,
+    };
+    if (opts.includeSteer && ctx.steer) {
+        sections.push('', '## STEERING PROMPT', ctx.steer);
+    }
+    if (opts.includePreviousContent && ctx.previousContent) {
+        sections.push('', '## PREVIOUS SYNTHESIS', ctx.previousContent);
+    }
+    if (opts.includePreviousFeedback && ctx.previousFeedback) {
+        sections.push('', opts.feedbackHeading, ctx.previousFeedback);
+    }
+    if (opts.includeChildMetas && Object.keys(ctx.childMetas).length > 0) {
+        sections.push('', '## CHILD META OUTPUTS');
+        for (const [childPath, content] of Object.entries(ctx.childMetas)) {
+            sections.push(`### ${childPath}`, typeof content === 'string' ? content : '(not yet synthesized)');
+        }
+    }
+}
+/**
+ * Build the architect task prompt.
+ *
+ * @param ctx - Synthesis context.
+ * @param meta - Current meta.json.
+ * @param config - Synthesis config.
+ * @returns The architect task prompt string.
+ */
+function buildArchitectTask(ctx, meta, config) {
+    const sections = [
+        meta._architect ?? config.defaultArchitect,
+        '',
+        '## SCOPE',
+        `Path: ${ctx.path}`,
+        `Total files in scope: ${ctx.scopeFiles.length.toString()}`,
+        `Files changed since last synthesis: ${ctx.deltaFiles.length.toString()}`,
+        '',
+        '### File listing (scope)',
+        condenseScopeFiles(ctx.scopeFiles),
+    ];
+    // Inject previous _builder so architect can see its own prior output
+    if (meta._builder) {
+        sections.push('', '## PREVIOUS TASK BRIEF', meta._builder);
+    }
+    appendSharedSections(sections, ctx);
+    if (ctx.archives.length > 0) {
+        sections.push('', '## ARCHIVE HISTORY', `${ctx.archives.length.toString()} previous synthesis snapshots available in .meta/archive/.`, 'Review these to understand how the synthesis has evolved over time.');
+    }
+    return sections.join('\n');
+}
+/**
+ * Build the builder task prompt.
+ *
+ * @param ctx - Synthesis context.
+ * @param meta - Current meta.json.
+ * @param config - Synthesis config.
+ * @returns The builder task prompt string.
+ */
+function buildBuilderTask(ctx, meta, config) {
+    const sections = [
+        '## TASK BRIEF (from Architect)',
+        meta._builder ?? '(No architect brief available)',
+        '',
+        '## SCOPE',
+        `Path: ${ctx.path}`,
+        `Delta files (${ctx.deltaFiles.length.toString()} changed):`,
+        ...ctx.deltaFiles.slice(0, config.maxLines).map((f) => `- ${f}`),
+    ];
+    appendSharedSections(sections, ctx, {
+        includeSteer: false,
+        feedbackHeading: '## FEEDBACK FROM CRITIC',
+    });
+    sections.push('', '## OUTPUT FORMAT', 'Return a JSON object with:', '- "_content": Markdown narrative synthesis (required)', '- Any additional structured fields as non-underscore keys');
+    return sections.join('\n');
+}
+/**
+ * Build the critic task prompt.
+ *
+ * @param ctx - Synthesis context.
+ * @param meta - Current meta.json (with _content already set by builder).
+ * @param config - Synthesis config.
+ * @returns The critic task prompt string.
+ */
+function buildCriticTask(ctx, meta, config) {
+    const sections = [
+        meta._critic ?? config.defaultCritic,
+        '',
+        '## SYNTHESIS TO EVALUATE',
+        meta._content ?? '(No content produced)',
+        '',
+        '## SCOPE',
+        `Path: ${ctx.path}`,
+        `Files in scope: ${ctx.scopeFiles.length.toString()}`,
+    ];
+    appendSharedSections(sections, ctx, {
+        includePreviousContent: false,
+        feedbackHeading: '## YOUR PREVIOUS FEEDBACK',
+        includeChildMetas: false,
+    });
+    sections.push('', '## OUTPUT FORMAT', 'Return your evaluation as Markdown text. Be specific and actionable.');
+    return sections.join('\n');
+}
+
+/**
+ * Zod schema for jeeves-meta configuration.
+ *
+ * Consumers load config however they want (file, env, constructor).
+ * The library validates via this schema.
+ *
+ * @module schema/config
+ */
+/** Zod schema for jeeves-meta configuration. */
+const synthConfigSchema = z.object({
+    /** Filesystem paths to watch for .meta/ directories. */
+    watchPaths: z.array(z.string()).min(1),
+    /** Watcher service base URL. */
+    watcherUrl: z.url(),
+    /** Run architect every N cycles (per meta). */
+    architectEvery: z.number().int().min(1).default(10),
+    /** Exponent for depth weighting in staleness formula. */
+    depthWeight: z.number().min(0).default(0.5),
+    /** Maximum archive snapshots to retain per meta. */
+    maxArchive: z.number().int().min(1).default(20),
+    /** Maximum lines of context to include in subprocess prompts. */
+    maxLines: z.number().int().min(50).default(500),
+    /** Architect subprocess timeout in seconds. */
+    architectTimeout: z.number().int().min(30).default(120),
+    /** Builder subprocess timeout in seconds. */
+    builderTimeout: z.number().int().min(60).default(600),
+    /** Critic subprocess timeout in seconds. */
+    criticTimeout: z.number().int().min(30).default(300),
+    /** Resolved architect system prompt text. */
+    defaultArchitect: z.string(),
+    /** Resolved critic system prompt text. */
+    defaultCritic: z.string(),
+    /**
+     * When true, skip unchanged candidates and iterate to the next-stalest
+     * until finding one with actual changes. Skipped candidates get their
+     * _generatedAt bumped to prevent re-selection next cycle.
+     */
+    skipUnchanged: z.boolean().default(true),
+    /** Number of metas to synthesize per invocation. */
+    batchSize: z.number().int().min(1).default(1),
+});
+
+/**
+ * Structured error from a synthesis step failure.
+ *
+ * @module schema/error
+ */
+/** Zod schema for synthesis step errors. */
+const synthErrorSchema = z.object({
+    /** Which step failed: 'architect', 'builder', or 'critic'. */
+    step: z.enum(['architect', 'builder', 'critic']),
+    /** Error classification code. */
+    code: z.string(),
+    /** Human-readable error message. */
+    message: z.string(),
+});
+
+/**
+ * Zod schema for .meta/meta.json files.
+ *
+ * Reserved properties are underscore-prefixed and engine-managed.
+ * All other keys are open schema (builder output).
+ *
+ * @module schema/meta
+ */
+/** Zod schema for the reserved (underscore-prefixed) meta.json properties. */
+const metaJsonSchema = z
+    .object({
+    /** Stable identity. Generated on first synthesis, never changes. */
+    _id: z.uuid(),
+    /** Human-provided steering prompt. Optional. */
+    _steer: z.string().optional(),
+    /** Architect system prompt used this turn. Defaults from config. */
+    _architect: z.string().optional(),
+    /**
+     * Task brief generated by the architect. Cached and reused across cycles;
+     * regenerated only when triggered.
+     */
+    _builder: z.string().optional(),
+    /** Critic system prompt used this turn. Defaults from config. */
+    _critic: z.string().optional(),
+    /** Timestamp of last synthesis. ISO 8601. */
+    _generatedAt: z.iso.datetime().optional(),
+    /** Narrative synthesis output. Rendered by watcher for embedding. */
+    _content: z.string().optional(),
+    /**
+     * Hash of sorted file listing in scope. Detects directory structure
+     * changes that trigger an architect re-run.
+     */
+    _structureHash: z.string().optional(),
+    /**
+     * Cycles since last architect run. Reset to 0 when architect runs.
+     * Used with architectEvery to trigger periodic re-prompting.
+     */
+    _synthesisCount: z.number().int().min(0).optional(),
+    /** Critic evaluation of the last synthesis. */
+    _feedback: z.string().optional(),
+    /**
+     * Present and true on archive snapshots. Distinguishes live vs. archived
+     * metas.
+     */
+    _archived: z.boolean().optional(),
+    /** Timestamp when this snapshot was archived. ISO 8601. */
+    _archivedAt: z.iso.datetime().optional(),
+    /**
+     * Scheduling priority. Higher = updates more often. Negative allowed;
+     * normalized to min 0 at scheduling time.
+     */
+    _depth: z.number().optional(),
+    /**
+     * Emphasis multiplier for depth weighting in scheduling.
+     * Default 1. Higher values increase this meta's scheduling priority
+     * relative to its depth. Set to 0.5 to halve the depth effect,
+     * 2 to double it, 0 to ignore depth entirely for this meta.
+     */
+    _emphasis: z.number().min(0).optional(),
+    /** Token count from last architect subprocess call. */
+    _architectTokens: z.number().int().optional(),
+    /** Token count from last builder subprocess call. */
+    _builderTokens: z.number().int().optional(),
+    /** Token count from last critic subprocess call. */
+    _criticTokens: z.number().int().optional(),
+    /** Exponential moving average of architect token usage (decay 0.3). */
+    _architectTokensAvg: z.number().optional(),
+    /** Exponential moving average of builder token usage (decay 0.3). */
+    _builderTokensAvg: z.number().optional(),
+    /** Exponential moving average of critic token usage (decay 0.3). */
+    _criticTokensAvg: z.number().optional(),
+    /**
+     * Structured error from last cycle. Present when a step failed.
+     * Cleared on successful cycle.
+     */
+    _error: synthErrorSchema.optional(),
+})
+    .loose();
+
+/**
+ * Merge synthesis results into meta.json.
+ *
+ * Preserves human-set fields (_id, _steer, _depth).
+ * Writes engine fields (_generatedAt, _structureHash, etc.).
+ * Validates against schema before writing.
+ *
+ * @module orchestrator/merge
+ */
+/**
+ * Merge results into meta.json and write atomically.
+ *
+ * @param options - Merge options.
+ * @returns The updated MetaJson.
+ * @throws If validation fails (malformed output).
+ */
+function mergeAndWrite(options) {
+    const merged = {
+        // Preserve human-set fields
+        _id: options.current._id,
+        _steer: options.current._steer,
+        _depth: options.current._depth,
+        _emphasis: options.current._emphasis,
+        // Engine fields
+        _architect: options.architect,
+        _builder: options.builder,
+        _critic: options.critic,
+        _generatedAt: new Date().toISOString(),
+        _structureHash: options.structureHash,
+        _synthesisCount: options.synthesisCount,
+        // Token tracking
+        _architectTokens: options.architectTokens,
+        _builderTokens: options.builderTokens,
+        _criticTokens: options.criticTokens,
+        _architectTokensAvg: options.architectTokens !== undefined
+            ? computeEma(options.architectTokens, options.current._architectTokensAvg)
+            : options.current._architectTokensAvg,
+        _builderTokensAvg: options.builderTokens !== undefined
+            ? computeEma(options.builderTokens, options.current._builderTokensAvg)
+            : options.current._builderTokensAvg,
+        _criticTokensAvg: options.criticTokens !== undefined
+            ? computeEma(options.criticTokens, options.current._criticTokensAvg)
+            : options.current._criticTokensAvg,
+        // Content from builder
+        _content: options.builderOutput?.content ?? options.current._content,
+        // Feedback from critic
+        _feedback: options.feedback ?? options.current._feedback,
+        // Error handling
+        _error: options.error ?? undefined,
+        // Spread structured fields from builder
+        ...options.builderOutput?.fields,
+    };
+    // Clean up undefined optional fields
+    if (merged._steer === undefined)
+        delete merged._steer;
+    if (merged._depth === undefined)
+        delete merged._depth;
+    if (merged._emphasis === undefined)
+        delete merged._emphasis;
+    if (merged._architectTokens === undefined)
+        delete merged._architectTokens;
+    if (merged._builderTokens === undefined)
+        delete merged._builderTokens;
+    if (merged._criticTokens === undefined)
+        delete merged._criticTokens;
+    if (merged._architectTokensAvg === undefined)
+        delete merged._architectTokensAvg;
+    if (merged._builderTokensAvg === undefined)
+        delete merged._builderTokensAvg;
+    if (merged._criticTokensAvg === undefined)
+        delete merged._criticTokensAvg;
+    if (merged._error === undefined)
+        delete merged._error;
+    if (merged._content === undefined)
+        delete merged._content;
+    if (merged._feedback === undefined)
+        delete merged._feedback;
+    // Validate
+    const result = metaJsonSchema.safeParse(merged);
+    if (!result.success) {
+        throw new Error(`Meta validation failed: ${result.error.message}`);
+    }
+    // Write atomically
+    const filePath = join(options.metaPath, 'meta.json');
+    writeFileSync(filePath, JSON.stringify(result.data, null, 2) + '\n');
+    return result.data;
+}
+
+/**
+ * Shared error utilities.
+ *
+ * @module errors
+ */
+/**
+ * Wrap an unknown caught value into a SynthError.
+ *
+ * @param step - Which synthesis step failed.
+ * @param err - The caught error value.
+ * @param code - Error classification code.
+ * @returns A structured SynthError.
+ */
+function toSynthError(step, err, code = 'FAILED') {
+    return {
+        step,
+        code,
+        message: err instanceof Error ? err.message : String(err),
+    };
+}
+
+/**
+ * File-system lock for preventing concurrent synthesis on the same meta.
+ *
+ * Lock file: .meta/.lock containing PID + timestamp.
+ * Stale timeout: 30 minutes.
+ *
+ * @module lock
+ */
+const LOCK_FILE = '.lock';
+const STALE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+/**
+ * Attempt to acquire a lock on a .meta directory.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns True if lock was acquired, false if already locked (non-stale).
+ */
+function acquireLock(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    if (existsSync(lockPath)) {
+        try {
+            const raw = readFileSync(lockPath, 'utf8');
+            const data = JSON.parse(raw);
+            const lockAge = Date.now() - new Date(data.startedAt).getTime();
+            if (lockAge < STALE_TIMEOUT_MS) {
+                return false; // Lock is active
+            }
+            // Stale lock — fall through to overwrite
+        }
+        catch {
+            // Corrupt lock file — overwrite
+        }
+    }
+    const lock = {
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    };
+    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n');
+    return true;
+}
+/**
+ * Release a lock on a .meta directory.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ */
+function releaseLock(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // Already removed or never existed
+    }
+}
+/**
+ * Check if a .meta directory is currently locked (non-stale).
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns True if locked and not stale.
+ */
+function isLocked(metaPath) {
+    const lockPath = join(metaPath, LOCK_FILE);
+    if (!existsSync(lockPath))
+        return false;
+    try {
+        const raw = readFileSync(lockPath, 'utf8');
+        const data = JSON.parse(raw);
+        const lockAge = Date.now() - new Date(data.startedAt).getTime();
+        return lockAge < STALE_TIMEOUT_MS;
+    }
+    catch {
+        return false; // Corrupt lock = not locked
+    }
+}
+
+/**
+ * Select the best synthesis candidate from stale metas.
+ *
+ * Picks the meta with highest effective staleness.
+ *
+ * @module scheduling/selectCandidate
+ */
+/**
+ * Select the candidate with the highest effective staleness.
+ *
+ * @param candidates - Array of candidates with computed effective staleness.
+ * @returns The winning candidate, or null if no candidates.
+ */
+function selectCandidate(candidates) {
+    if (candidates.length === 0)
+        return null;
+    let best = candidates[0];
+    for (let i = 1; i < candidates.length; i++) {
+        if (candidates[i].effectiveStaleness > best.effectiveStaleness) {
+            best = candidates[i];
+        }
+    }
+    return best;
+}
+
+/**
+ * Staleness detection via watcher scan.
+ *
+ * A meta is stale when any file in its scope was modified after _generatedAt.
+ *
+ * @module scheduling/staleness
+ */
+/**
+ * Check if a meta is stale by querying the watcher for modified files.
+ *
+ * @param scopePrefix - Path prefix for this meta's scope.
+ * @param meta - Current meta.json content.
+ * @param watcher - WatcherClient instance.
+ * @returns True if any file in scope was modified after _generatedAt.
+ */
+async function isStale(scopePrefix, meta, watcher) {
+    if (!meta._generatedAt)
+        return true; // Never synthesized = stale
+    const generatedAtUnix = Math.floor(new Date(meta._generatedAt).getTime() / 1000);
+    const result = await watcher.scan({
+        pathPrefix: scopePrefix,
+        modifiedAfter: generatedAtUnix,
+        limit: 1,
+    });
+    return result.files.length > 0;
+}
+/**
+ * Compute actual staleness in seconds (now minus _generatedAt).
+ *
+ * @param meta - Current meta.json content.
+ * @returns Staleness in seconds, or Infinity if never synthesized.
+ */
+function actualStaleness(meta) {
+    if (!meta._generatedAt)
+        return Infinity;
+    const generatedMs = new Date(meta._generatedAt).getTime();
+    return (Date.now() - generatedMs) / 1000;
+}
+
+/**
+ * Weighted staleness formula for candidate selection.
+ *
+ * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ *
+ * @module scheduling/weightedFormula
+ */
+/**
+ * Compute effective staleness for a set of candidates.
+ *
+ * Normalizes depths so the minimum becomes 0, then applies the formula:
+ * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ *
+ * Per-meta _emphasis (default 1) multiplies depthWeight, allowing individual
+ * metas to tune how much their tree position affects scheduling.
+ *
+ * @param candidates - Array of \{ node, meta, actualStaleness \}.
+ * @param depthWeight - Exponent for depth weighting (0 = pure staleness).
+ * @returns Same array with effectiveStaleness computed.
+ */
+function computeEffectiveStaleness(candidates, depthWeight) {
+    if (candidates.length === 0)
+        return [];
+    // Get depth for each candidate: use _depth override or tree depth
+    const depths = candidates.map((c) => c.meta._depth ?? c.node.treeDepth);
+    // Normalize: shift so minimum becomes 0
+    const minDepth = Math.min(...depths);
+    const normalizedDepths = depths.map((d) => Math.max(0, d - minDepth));
+    return candidates.map((c, i) => {
+        const emphasis = c.meta._emphasis ?? 1;
+        return {
+            ...c,
+            effectiveStaleness: c.actualStaleness *
+                Math.pow(normalizedDepths[i] + 1, depthWeight * emphasis),
+        };
+    });
+}
+
+/**
+ * Compute a structure hash from a sorted file listing.
+ *
+ * Used to detect when directory structure changes, triggering
+ * an architect re-run.
+ *
+ * @module structureHash
+ */
+/**
+ * Compute a SHA-256 hash of a sorted file listing.
+ *
+ * @param filePaths - Array of file paths in scope.
+ * @returns Hex-encoded SHA-256 hash of the sorted, newline-joined paths.
+ */
+function computeStructureHash(filePaths) {
+    const sorted = [...filePaths].sort();
+    const content = sorted.join('\n');
+    return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Parse subprocess outputs for each synthesis step.
+ *
+ * - Architect: returns text \> _builder
+ * - Builder: returns JSON \> _content + structured fields
+ * - Critic: returns text \> _feedback
+ *
+ * @module orchestrator/parseOutput
+ */
+/**
+ * Parse architect output. The architect returns a task brief as text.
+ *
+ * @param output - Raw subprocess output.
+ * @returns The task brief string.
+ */
+function parseArchitectOutput(output) {
+    return output.trim();
+}
+/**
+ * Parse builder output. The builder returns JSON with _content and optional fields.
+ *
+ * Attempts JSON parse first. If that fails, treats the entire output as _content.
+ *
+ * @param output - Raw subprocess output.
+ * @returns Parsed builder output with content and structured fields.
+ */
+function parseBuilderOutput(output) {
+    const trimmed = output.trim();
+    // Try to extract JSON from the output (may be wrapped in markdown code fences)
+    let jsonStr = trimmed;
+    const fenceMatch = /```(?:json)?\s*([\s\S]*?)```/.exec(trimmed);
+    if (fenceMatch) {
+        jsonStr = fenceMatch[1].trim();
+    }
+    try {
+        const parsed = JSON.parse(jsonStr);
+        // Extract _content
+        const content = typeof parsed._content === 'string'
+            ? parsed._content
+            : typeof parsed.content === 'string'
+                ? parsed.content
+                : trimmed;
+        // Extract non-underscore fields
+        const fields = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (!key.startsWith('_') && key !== 'content') {
+                fields[key] = value;
+            }
+        }
+        return { content, fields };
+    }
+    catch {
+        // Not valid JSON — treat entire output as content
+        return { content: trimmed, fields: {} };
+    }
+}
+/**
+ * Parse critic output. The critic returns evaluation text.
+ *
+ * @param output - Raw subprocess output.
+ * @returns The feedback string.
+ */
+function parseCriticOutput(output) {
+    return output.trim();
+}
+
+/**
+ * Main orchestration function — the 13-step synthesis cycle.
+ *
+ * Wires together discovery, scheduling, archiving, executor calls,
+ * and merge/write-back.
+ *
+ * @module orchestrator/orchestrate
+ */
+/** Normalize path separators to forward slashes. */
+function normalizePath(p) {
+    return p.replaceAll('\\', '/');
+}
+/** Finalize a cycle: merge, snapshot, prune. */
+function finalizeCycle(metaPath, current, config, architect, builder, critic, builderOutput, feedback, structureHash, synthesisCount, error, architectTokens, builderTokens, criticTokens) {
+    const updated = mergeAndWrite({
+        metaPath,
+        current,
+        architect,
+        builder,
+        critic,
+        builderOutput,
+        feedback,
+        structureHash,
+        synthesisCount,
+        error,
+        architectTokens,
+        builderTokens,
+        criticTokens,
+    });
+    createSnapshot(metaPath, updated);
+    pruneArchive(metaPath, config.maxArchive);
+    return updated;
+}
+/**
+ * Run a single synthesis cycle.
+ *
+ * Discovers all metas, selects the stalest candidate, and runs the
+ * three-step synthesis (architect, builder, critic).
+ *
+ * @param config - Validated synthesis config.
+ * @param executor - Pluggable LLM executor.
+ * @param watcher - Watcher HTTP client.
+ * @returns Result indicating whether synthesis occurred.
+ */
+async function orchestrateOnce(config, executor, watcher) {
+    // Step 1: Discover
+    const metaPaths = globMetas(config.watchPaths);
+    if (metaPaths.length === 0)
+        return { synthesized: false };
+    // Ensure all meta.json files exist
+    const metas = new Map();
+    for (const mp of metaPaths) {
+        metas.set(normalizePath(mp), ensureMetaJson(mp));
+    }
+    const tree = buildOwnershipTree(metaPaths);
+    // Steps 3-4: Staleness check + candidate selection
+    const candidates = [];
+    for (const node of tree.nodes.values()) {
+        const meta = metas.get(node.metaPath);
+        const staleness = actualStaleness(meta);
+        if (staleness > 0) {
+            candidates.push({ node, meta, actualStaleness: staleness });
+        }
+    }
+    const weighted = computeEffectiveStaleness(candidates, config.depthWeight);
+    // Sort by effective staleness descending
+    const ranked = [...weighted].sort((a, b) => b.effectiveStaleness - a.effectiveStaleness);
+    if (ranked.length === 0)
+        return { synthesized: false };
+    // Find the first candidate with actual changes (if skipUnchanged)
+    let winner = null;
+    for (const candidate of ranked) {
+        if (!acquireLock(candidate.node.metaPath))
+            continue;
+        const verifiedStale = await isStale(getScopePrefix(candidate.node), candidate.meta, watcher);
+        if (!verifiedStale && candidate.meta._generatedAt) {
+            // Bump _generatedAt so it doesn't win next cycle
+            const metaFilePath = join(candidate.node.metaPath, 'meta.json');
+            const freshMeta = JSON.parse(readFileSync(metaFilePath, 'utf8'));
+            freshMeta._generatedAt = new Date().toISOString();
+            writeFileSync(metaFilePath, JSON.stringify(freshMeta, null, 2));
+            releaseLock(candidate.node.metaPath);
+            if (config.skipUnchanged)
+                continue;
+            return { synthesized: false };
+        }
+        winner = candidate;
+        break;
+    }
+    if (!winner)
+        return { synthesized: false };
+    const { node } = winner;
+    try {
+        // Re-read meta after lock (may have changed)
+        const currentMeta = JSON.parse(readFileSync(join(node.metaPath, 'meta.json'), 'utf8'));
+        const architectPrompt = currentMeta._architect ?? config.defaultArchitect;
+        const criticPrompt = currentMeta._critic ?? config.defaultCritic;
+        // Step 5: Structure hash
+        const scopePrefix = getScopePrefix(node);
+        const allScanFiles = await paginatedScan(watcher, {
+            pathPrefix: scopePrefix,
+        });
+        const allFilePaths = allScanFiles.map((f) => f.file_path);
+        // Structure hash uses scope-filtered files (excluding child subtrees)
+        // so changes in child scopes don't trigger parent architect re-runs
+        const scopeFiles = filterInScope(node, allFilePaths);
+        const newStructureHash = computeStructureHash(scopeFiles);
+        const structureChanged = newStructureHash !== currentMeta._structureHash;
+        // Step 6: Steer change detection
+        const latestArchive = readLatestArchive(node.metaPath);
+        const steerChanged = latestArchive
+            ? currentMeta._steer !== latestArchive._steer
+            : Boolean(currentMeta._steer);
+        // Step 7: Compute context
+        const ctx = await buildContextPackage(node, currentMeta, watcher);
+        // Step 8: Architect (conditional)
+        const architectTriggered = !currentMeta._builder ||
+            structureChanged ||
+            steerChanged ||
+            (currentMeta._synthesisCount ?? 0) >= config.architectEvery;
+        let builderBrief = currentMeta._builder ?? '';
+        let synthesisCount = currentMeta._synthesisCount ?? 0;
+        let stepError = null;
+        let architectTokens;
+        let builderTokens;
+        let criticTokens;
+        if (architectTriggered) {
+            try {
+                const architectTask = buildArchitectTask(ctx, currentMeta, config);
+                const architectResult = await executor.spawn(architectTask, {
+                    timeout: config.architectTimeout,
+                });
+                builderBrief = parseArchitectOutput(architectResult.output);
+                architectTokens = architectResult.tokens;
+                synthesisCount = 0;
+            }
+            catch (err) {
+                stepError = toSynthError('architect', err);
+                if (!currentMeta._builder) {
+                    // No cached builder — cycle fails
+                    finalizeCycle(node.metaPath, currentMeta, config, architectPrompt, '', criticPrompt, null, null, newStructureHash, synthesisCount, stepError, architectTokens);
+                    return {
+                        synthesized: true,
+                        metaPath: node.metaPath,
+                        error: stepError,
+                    };
+                }
+                // Has cached builder — continue with existing
+            }
+        }
+        // Step 9: Builder
+        const metaForBuilder = { ...currentMeta, _builder: builderBrief };
+        let builderOutput = null;
+        try {
+            const builderTask = buildBuilderTask(ctx, metaForBuilder, config);
+            const builderResult = await executor.spawn(builderTask, {
+                timeout: config.builderTimeout,
+            });
+            builderOutput = parseBuilderOutput(builderResult.output);
+            builderTokens = builderResult.tokens;
+            synthesisCount++;
+        }
+        catch (err) {
+            stepError = toSynthError('builder', err);
+            return { synthesized: true, metaPath: node.metaPath, error: stepError };
+        }
+        // Step 10: Critic
+        const metaForCritic = {
+            ...currentMeta,
+            _content: builderOutput.content,
+        };
+        let feedback = null;
+        try {
+            const criticTask = buildCriticTask(ctx, metaForCritic, config);
+            const criticResult = await executor.spawn(criticTask, {
+                timeout: config.criticTimeout,
+            });
+            feedback = parseCriticOutput(criticResult.output);
+            criticTokens = criticResult.tokens;
+            stepError = null; // Clear any architect error on full success
+        }
+        catch (err) {
+            stepError = stepError ?? toSynthError('critic', err);
+        }
+        // Steps 11-12: Merge, archive, prune
+        finalizeCycle(node.metaPath, currentMeta, config, architectPrompt, builderBrief, criticPrompt, builderOutput, feedback, newStructureHash, synthesisCount, stepError, architectTokens, builderTokens, criticTokens);
+        return {
+            synthesized: true,
+            metaPath: node.metaPath,
+            error: stepError ?? undefined,
+        };
+    }
+    finally {
+        // Step 13: Release lock
+        releaseLock(node.metaPath);
+    }
+}
+/**
+ * Run synthesis cycles up to batchSize.
+ *
+ * Calls orchestrateOnce() in a loop, stopping when batchSize is reached
+ * or no more candidates are available.
+ *
+ * @param config - Validated synthesis config.
+ * @param executor - Pluggable LLM executor.
+ * @param watcher - Watcher HTTP client.
+ * @returns Array of results, one per cycle attempted.
+ */
+async function orchestrate(config, executor, watcher) {
+    const results = [];
+    for (let i = 0; i < config.batchSize; i++) {
+        const result = await orchestrateOnce(config, executor, watcher);
+        results.push(result);
+        if (!result.synthesized)
+            break; // No more candidates
+    }
+    return results;
+}
+
+/**
+ * Factory for creating a bound synthesis engine.
+ *
+ * @module engine
+ */
+/**
+ * Create a synthesis engine with bound config, executor, and watcher client.
+ *
+ * @param config - Validated synthesis config.
+ * @param executor - Pluggable LLM executor.
+ * @param watcher - Watcher HTTP client.
+ * @returns A bound engine instance.
+ */
+function createSynthEngine(config, executor, watcher) {
+    return {
+        config,
+        synthesize() {
+            return orchestrate(config, executor, watcher);
+        },
+        synthesizePath(ownerPath) {
+            const scopedConfig = { ...config, watchPaths: [ownerPath] };
+            return orchestrate(scopedConfig, executor, watcher);
+        },
+    };
+}
+
+/**
+ * HTTP implementation of the WatcherClient interface.
+ *
+ * Talks to jeeves-watcher's POST /scan and POST /rules endpoints
+ * with retry and exponential backoff.
+ *
+ * @module watcher-client/HttpWatcherClient
+ */
+/** Default retry configuration. */
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BACKOFF_BASE_MS = 1000;
+const DEFAULT_BACKOFF_FACTOR = 4;
+/** Sleep for a given number of milliseconds. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Check if an error is transient (worth retrying). */
+function isTransient(status) {
+    return status >= 500 || status === 408 || status === 429;
+}
+/**
+ * HTTP-based WatcherClient implementation with retry.
+ */
+class HttpWatcherClient {
+    baseUrl;
+    maxRetries;
+    backoffBaseMs;
+    backoffFactor;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.backoffBaseMs = options.backoffBaseMs ?? DEFAULT_BACKOFF_BASE_MS;
+        this.backoffFactor = options.backoffFactor ?? DEFAULT_BACKOFF_FACTOR;
+    }
+    /** POST JSON with retry. */
+    async post(endpoint, body) {
+        const url = this.baseUrl + endpoint;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            if (res.ok) {
+                return res.json();
+            }
+            if (!isTransient(res.status) || attempt === this.maxRetries) {
+                const text = await res.text();
+                throw new Error(`Watcher ${endpoint} failed: HTTP ${res.status.toString()} - ${text}`);
+            }
+            // Exponential backoff
+            const delayMs = this.backoffBaseMs * Math.pow(this.backoffFactor, attempt);
+            await sleep(delayMs);
+        }
+        // Unreachable, but TypeScript needs it
+        throw new Error('Retry exhausted');
+    }
+    async scan(params) {
+        const body = {
+            pathPrefix: params.pathPrefix,
+        };
+        if (params.modifiedAfter !== undefined) {
+            body.modifiedAfter = params.modifiedAfter;
+        }
+        if (params.fields !== undefined) {
+            body.fields = params.fields;
+        }
+        if (params.limit !== undefined) {
+            body.limit = params.limit;
+        }
+        if (params.cursor !== undefined) {
+            body.cursor = params.cursor;
+        }
+        const result = await this.post('/scan', body);
+        return result;
+    }
+    async registerRules(source, rules) {
+        await this.post('/rules/register', { source, rules });
+    }
+    async unregisterRules(source) {
+        await this.post('/rules/unregister', { source });
+    }
+}
+
+export { HttpWatcherClient, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildOwnershipTree, computeEffectiveStaleness, computeEma, computeStructureHash, createSnapshot, createSynthEngine, ensureMetaJson, filterInScope, getScopeExclusions, getScopePrefix, globMetas, isLocked, isStale, listArchiveFiles, mergeAndWrite, metaJsonSchema, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, releaseLock, selectCandidate, synthConfigSchema, synthErrorSchema, toSynthError };