@karmaniverous/jeeves-meta 0.15.3 → 0.15.5

package/dist/index.d.ts

@@ -1,1661 +1,35 @@
-import { z } from 'zod';
-import { Command } from 'commander';
-import { JeevesComponentDescriptor } from '@karmaniverous/jeeves';
-export { sleepAsync as sleep } from '@karmaniverous/jeeves';
-import pino, { Logger } from 'pino';
-import * as fastify from 'fastify';
-import { FastifyInstance, FastifyBaseLogger } from 'fastify';
-import * as node_http from 'node:http';
-
-/**
- * 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.
- */
-declare function listArchiveFiles(metaPath: string): string[];
-
-/**
- * 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.
- */
-declare function pruneArchive(metaPath: string, maxArchive: number): Promise<number>;
-
-/**
- * Per-cycle context package computed by the orchestrator.
- *
- * Shared inputs that multiple subprocesses need are computed once
- * and serialized into each subprocess's task prompt.
- *
- * @module interfaces/MetaContext
- */
-/**
- * Context package for a single synthesis cycle.
- *
- * The orchestrator computes this once per cycle from the meta path,
- * ownership tree, watcher walk results, and filesystem reads.
- */
-interface MetaContext {
-    /** Absolute path to the .meta directory. */
-    path: string;
-    /** All files in scope (absolute paths). */
-    scopeFiles: string[];
-    /** Files changed since _generatedAt (absolute paths). */
-    deltaFiles: string[];
-    /** Child _content outputs, keyed by relative path. */
-    childMetas: Record<string, unknown>;
-    /** Cross-referenced meta _content outputs, keyed by owner path. */
-    crossRefMetas: Record<string, unknown>;
-    /** _content from the last cycle, or null on first run. */
-    previousContent: string | null;
-    /** _feedback from the last cycle, or null on first run. */
-    previousFeedback: string | null;
-    /** Current _steer value, or null if unset. */
-    steer: string | null;
-    /** _state from the last cycle, or null on first run. */
-    previousState: unknown;
-    /** Archive snapshot file paths (for steer change detection, etc.). */
-    archives: string[];
-}
-
-/**
- * Pluggable executor interface for LLM subprocess invocation.
- *
- * @module interfaces/MetaExecutor
- */
-/** Options for spawning a synthesis subprocess. */
-interface MetaSpawnOptions {
-    /** Model override for this subprocess. */
-    model?: string;
-    /** Timeout in seconds. */
-    timeout?: number;
-    /** Label for the spawned session. */
-    label?: string;
-    /** Thinking level (e.g. "low", "medium", "high"). */
-    thinking?: string;
-}
-/** Result of a spawn call, including optional token usage. */
-interface MetaSpawnResult {
-    /** Subprocess output text. */
-    output: string;
-    /** Token count for this call, if available from the executor. */
-    tokens?: number;
-}
-/**
- * Interface for spawning synthesis subprocesses.
- *
- * The executor abstracts the LLM invocation mechanism. The orchestrator
- * calls spawn() sequentially for architect, builder, and critic steps.
- * Each call blocks until the subprocess completes and returns its result.
- */
-interface MetaExecutor {
-    /**
-     * Spawn a subprocess with the given task prompt.
-     *
-     * @param task - Full task prompt for the subprocess.
-     * @param options - Optional model and timeout overrides.
-     * @returns The subprocess result with output and optional token count.
-     */
-    spawn(task: string, options?: MetaSpawnOptions): Promise<MetaSpawnResult>;
-    /**
-     * Whether the executor has been aborted by the operator.
-     * When true, runPhase catch blocks should skip persisting _error
-     * because the abort route has already written the correct state.
-     */
-    readonly aborted?: boolean;
-}
-
-/**
- * Abstraction over the jeeves-watcher HTTP API.
- *
- * The service uses this for filesystem enumeration (POST /walk),
- * virtual rule registration (POST /rules/register), and archive reads
- * via filter-only point scans (POST /scan).
- *
- * @module interfaces/WatcherClient
- */
-/** An inference rule to register with the watcher. */
-interface InferenceRuleSpec {
-    /** Rule name. */
-    name: string;
-    /** Rule description. */
-    description: string;
-    /** JSON Schema match criteria. */
-    match: Record<string, unknown>;
-    /** Schema array with set keywords. */
-    schema: unknown[];
-    /** Declarative render config. */
-    render?: Record<string, unknown>;
-    /** Handlebars template name. */
-    template?: string;
-    /** Render output format. */
-    renderAs?: string;
-}
-/** Request shape for watcher scan queries. */
-interface WatcherScanRequest {
-    filter: Record<string, unknown>;
-    limit?: number;
-    cursor?: string;
-    fields?: string[];
-    countOnly?: boolean;
-}
-/** A single point returned from watcher scan. */
-interface WatcherScanPoint {
-    id?: string | number;
-    payload?: Record<string, unknown>;
-}
-/** Response shape for watcher scan queries. */
-interface WatcherScanResult {
-    points: WatcherScanPoint[];
-    cursor: string | null;
-}
-/**
- * Interface for watcher HTTP operations.
- *
- * Implementations handle retry with backoff internally.
- */
-interface WatcherClient {
-    /**
-     * Register virtual inference rules with the watcher.
-     *
-     * @param source - Source identifier (e.g. 'jeeves-meta').
-     * @param rules - Array of inference rules to register.
-     */
-    registerRules(source: string, rules: InferenceRuleSpec[]): Promise<void>;
-    /**
-     * Walk filesystem using glob patterns.
-     *
-     * @param globs - Array of glob patterns to match against.
-     * @returns Promise resolving to array of matching file paths.
-     */
-    walk(globs: string[]): Promise<string[]>;
-    /**
-     * Run a filter-only point scan against the watcher index.
-     *
-     * Optional so narrow test doubles do not need to implement archive-read
-     * support unless a test exercises that path.
-     *
-     * @param request - Scan filter, pagination, and projection options.
-     * @returns Matching points and the next cursor.
-     */
-    scan?(request: WatcherScanRequest): Promise<WatcherScanResult>;
-}
-
-/**
- * Zod schema for jeeves-meta service configuration.
- *
- * The service config is a strict superset of the core (library-compatible) meta config.
- *
- * @module schema/config
- */
-
-/** Zod schema for the core (library-compatible) meta configuration. */
-declare const metaConfigSchema: z.ZodObject<{
-    watcherUrl: z.ZodURL;
-    gatewayUrl: z.ZodDefault<z.ZodURL>;
-    gatewayApiKey: z.ZodOptional<z.ZodString>;
-    architectEvery: z.ZodDefault<z.ZodNumber>;
-    depthWeight: z.ZodDefault<z.ZodNumber>;
-    maxArchive: z.ZodDefault<z.ZodNumber>;
-    maxLines: z.ZodDefault<z.ZodNumber>;
-    architectTimeout: z.ZodDefault<z.ZodNumber>;
-    builderTimeout: z.ZodDefault<z.ZodNumber>;
-    criticTimeout: z.ZodDefault<z.ZodNumber>;
-    thinking: z.ZodDefault<z.ZodString>;
-    defaultArchitect: z.ZodOptional<z.ZodString>;
-    defaultCritic: z.ZodOptional<z.ZodString>;
-    skipUnchanged: z.ZodDefault<z.ZodBoolean>;
-    metaProperty: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    metaArchiveProperty: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-/** Inferred type for core meta configuration. */
-type MetaConfig = z.infer<typeof metaConfigSchema>;
-/** Zod schema for jeeves-meta service configuration (superset of MetaConfig). */
-declare const serviceConfigSchema: z.ZodObject<{
-    watcherUrl: z.ZodURL;
-    gatewayUrl: z.ZodDefault<z.ZodURL>;
-    gatewayApiKey: z.ZodOptional<z.ZodString>;
-    architectEvery: z.ZodDefault<z.ZodNumber>;
-    depthWeight: z.ZodDefault<z.ZodNumber>;
-    maxArchive: z.ZodDefault<z.ZodNumber>;
-    maxLines: z.ZodDefault<z.ZodNumber>;
-    architectTimeout: z.ZodDefault<z.ZodNumber>;
-    builderTimeout: z.ZodDefault<z.ZodNumber>;
-    criticTimeout: z.ZodDefault<z.ZodNumber>;
-    thinking: z.ZodDefault<z.ZodString>;
-    defaultArchitect: z.ZodOptional<z.ZodString>;
-    defaultCritic: z.ZodOptional<z.ZodString>;
-    skipUnchanged: z.ZodDefault<z.ZodBoolean>;
-    metaProperty: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    metaArchiveProperty: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    port: z.ZodDefault<z.ZodNumber>;
-    schedule: z.ZodDefault<z.ZodString>;
-    reportChannel: z.ZodOptional<z.ZodString>;
-    reportTarget: z.ZodOptional<z.ZodString>;
-    serverBaseUrl: z.ZodOptional<z.ZodString>;
-    watcherHealthIntervalMs: z.ZodDefault<z.ZodNumber>;
-    logging: z.ZodDefault<z.ZodObject<{
-        level: z.ZodDefault<z.ZodString>;
-        file: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    autoSeed: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
-        match: z.ZodString;
-        steer: z.ZodOptional<z.ZodString>;
-        crossRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>>>>;
-}, z.core.$strip>;
-/** Inferred type for service configuration. */
-type ServiceConfig = z.infer<typeof serviceConfigSchema>;
-
-/**
- * Structured error from a synthesis step failure.
- *
- * @module schema/error
- */
-
-/** Zod schema for synthesis step errors. */
-declare const metaErrorSchema: z.ZodObject<{
-    step: z.ZodEnum<{
-        architect: "architect";
-        builder: "builder";
-        critic: "critic";
-    }>;
-    code: z.ZodString;
-    message: z.ZodString;
-}, z.core.$strip>;
-/** Inferred type for synthesis step errors. */
-type MetaError = z.infer<typeof metaErrorSchema>;
-
-/**
- * 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
- */
-
-/** Phase names in pipeline order. */
-declare const phaseNames: readonly ["architect", "builder", "critic"];
-/** A single synthesis phase name. */
-type PhaseName = (typeof phaseNames)[number];
-/** Valid states for a synthesis phase. */
-declare const phaseStatuses: readonly ["fresh", "stale", "pending", "running", "failed"];
-/** A single phase status value. */
-type PhaseStatus = (typeof phaseStatuses)[number];
-/** Per-phase state record. */
-type PhaseState = Record<PhaseName, PhaseStatus>;
-/** Zod schema for the reserved (underscore-prefixed) meta.json properties. */
-declare const metaJsonSchema: z.ZodObject<{
-    _id: z.ZodOptional<z.ZodUUID>;
-    _steer: z.ZodOptional<z.ZodString>;
-    _crossRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    _architect: z.ZodOptional<z.ZodString>;
-    _builder: z.ZodOptional<z.ZodString>;
-    _critic: z.ZodOptional<z.ZodString>;
-    _generatedAt: z.ZodOptional<z.ZodISODateTime>;
-    _content: z.ZodOptional<z.ZodString>;
-    _structureHash: z.ZodOptional<z.ZodString>;
-    _synthesisCount: z.ZodOptional<z.ZodNumber>;
-    _feedback: z.ZodOptional<z.ZodString>;
-    _archived: z.ZodOptional<z.ZodBoolean>;
-    _archivedAt: z.ZodOptional<z.ZodISODateTime>;
-    _depth: z.ZodOptional<z.ZodNumber>;
-    _emphasis: z.ZodOptional<z.ZodNumber>;
-    _architectTokens: z.ZodOptional<z.ZodNumber>;
-    _builderTokens: z.ZodOptional<z.ZodNumber>;
-    _criticTokens: z.ZodOptional<z.ZodNumber>;
-    _architectTokensAvg: z.ZodOptional<z.ZodNumber>;
-    _builderTokensAvg: z.ZodOptional<z.ZodNumber>;
-    _criticTokensAvg: z.ZodOptional<z.ZodNumber>;
-    _state: z.ZodOptional<z.ZodUnknown>;
-    _error: z.ZodOptional<z.ZodObject<{
-        step: z.ZodEnum<{
-            architect: "architect";
-            builder: "builder";
-            critic: "critic";
-        }>;
-        code: z.ZodString;
-        message: z.ZodString;
-    }, z.core.$strip>>;
-    _disabled: z.ZodOptional<z.ZodBoolean>;
-    _phaseState: z.ZodOptional<z.ZodObject<{
-        architect: z.ZodEnum<{
-            fresh: "fresh";
-            stale: "stale";
-            pending: "pending";
-            running: "running";
-            failed: "failed";
-        }>;
-        builder: z.ZodEnum<{
-            fresh: "fresh";
-            stale: "stale";
-            pending: "pending";
-            running: "running";
-            failed: "failed";
-        }>;
-        critic: z.ZodEnum<{
-            fresh: "fresh";
-            stale: "stale";
-            pending: "pending";
-            running: "running";
-            failed: "failed";
-        }>;
-    }, z.core.$strip>>;
-}, z.core.$loose>;
-/** Inferred type for meta.json. */
-type MetaJson = z.infer<typeof metaJsonSchema>;
-
 /**
- * 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.
- */
-declare function readLatestArchive(metaPath: string): Promise<MetaJson | null>;
-
-/**
- * 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.
- */
-declare function createSnapshot(metaPath: string, meta: MetaJson): Promise<string>;
-
-/**
- * Shared constants for the jeeves-meta service package.
- *
- * @module constants
- */
-/** Default HTTP port for the jeeves-meta service. */
-declare const DEFAULT_PORT = 1938;
-/** Default port as a string (for Commander CLI defaults). */
-declare const DEFAULT_PORT_STR: string;
-/** Service name identifier. */
-declare const SERVICE_NAME = "jeeves-meta";
-/** Service version, read from package.json at startup. */
-declare const SERVICE_VERSION: string;
-
-/**
- * Custom CLI commands for the jeeves-meta service.
- *
- * Registered via `descriptor.customCliCommands` and added to the
- * standard service CLI produced by `createServiceCli`.
- *
- * @module customCliCommands
- */
-
-/** Register all custom meta commands on the parent program. */
-declare function registerCustomCliCommands(program: Command): void;
-
-/**
- * Hybrid 3-layer synthesis queue.
- *
- * Layer 1: Current — the single item currently executing (at most one).
- * Layer 2: Overrides — items manually enqueued via POST /synthesize with path.
- *          FIFO among overrides, ahead of automatic candidates.
- * Layer 3: Automatic — computed on read, not persisted. All metas with a
- *          pending phase, ranked by scheduler priority.
- *
- * Legacy: `pending` array is the union of overrides + automatic.
- *
- * @module queue
- */
-
-/** A queued synthesis work item. */
-interface QueueItem {
-    path: string;
-    priority: boolean;
-    enqueuedAt: string;
-}
-/** An override entry in the explicit queue layer. */
-interface OverrideEntry {
-    path: string;
-    enqueuedAt: string;
-}
-/** The currently executing item with phase info. */
-interface CurrentItem {
-    path: string;
-    phase: PhaseName;
-    startedAt: string;
-}
-/** Result returned by {@link SynthesisQueue.enqueue}. */
-interface EnqueueResult {
-    position: number;
-    alreadyQueued: boolean;
-}
-/** Snapshot of queue state for the /status endpoint. */
-interface QueueState {
-    depth: number;
-    items: Array<{
-        path: string;
-        priority: boolean;
-        enqueuedAt: string;
-    }>;
-}
-/**
- * Hybrid 3-layer synthesis queue.
- *
- * Only one synthesis runs at a time. Override items (explicit triggers)
- * take priority over automatic candidates.
- */
-declare class SynthesisQueue {
-    /** Legacy queue (used by processQueue for backward compat). */
-    private queue;
-    private currentItem;
-    private processing;
-    private logger;
-    private onEnqueueCallback;
-    /** Explicit override entries (3-layer model). */
-    private overrideEntries;
-    /** Currently executing item with phase info (3-layer model). */
-    private currentPhaseItem;
-    constructor(logger: Logger);
-    /** Set a callback to invoke when a new (non-duplicate) item is enqueued. */
-    onEnqueue(callback: () => void): void;
-    /**
-     * Add an explicit override entry (from POST /synthesize with path).
-     * Deduped by path. Returns position and whether already queued.
-     */
-    enqueueOverride(path: string): EnqueueResult;
-    /** Dequeue the next override entry, or undefined if empty. */
-    dequeueOverride(): OverrideEntry | undefined;
-    /** Get all override entries (shallow copy). */
-    get overrides(): OverrideEntry[];
-    /** Clear all override entries. Returns count removed. */
-    clearOverrides(): number;
-    /** Check if a path is in the override layer. */
-    hasOverride(path: string): boolean;
-    /** Set the currently executing phase item. */
-    setCurrentPhase(path: string, phase: PhaseName): void;
-    /** Clear the current phase item. */
-    clearCurrentPhase(): void;
-    /** The currently executing phase item, or null. */
-    get currentPhase(): CurrentItem | null;
-    /**
-     * Add a path to the synthesis queue.
-     *
-     * @param path - Meta path to synthesize.
-     * @param priority - If true, insert at front of queue.
-     * @returns Position and whether the path was already queued.
-     */
-    enqueue(path: string, priority?: boolean): EnqueueResult;
-    /** Remove and return the next item from the queue. */
-    dequeue(): QueueItem | undefined;
-    /** Mark the currently-running synthesis as complete. */
-    complete(): void;
-    /** Number of items waiting in the queue (excludes current). */
-    get depth(): number;
-    /** The item currently being synthesized, or null. */
-    get current(): QueueItem | null;
-    /** A shallow copy of the queued items. */
-    get items(): QueueItem[];
-    /** A shallow copy of the pending items (alias for items). */
-    get pending(): QueueItem[];
-    /**
-     * Remove all pending items from the queue.
-     * Does not affect the currently-running item.
-     *
-     * @returns The number of items removed.
-     */
-    clear(): number;
-    /** Check whether a path is in the queue or currently being synthesized. */
-    has(path: string): boolean;
-    /** Get the 0-indexed position of a path in the queue. */
-    getPosition(path: string): number | null;
-    /** Dequeue the next item: overrides first, then legacy queue. */
-    private nextItem;
-    /** Return a snapshot of queue state for the /status endpoint. */
-    getState(): QueueState;
-    /**
-     * Process queued items one at a time until all queues are empty.
-     *
-     * Override entries are processed first (FIFO), then legacy queue items.
-     * Re-entry is prevented: if already processing, the call returns
-     * immediately. Errors are logged and do not block subsequent items.
-     *
-     * @param synthesizeFn - Async function that performs synthesis for a path.
-     */
-    processQueue(synthesizeFn: (path: string) => Promise<void>): Promise<void>;
-}
-
-/**
- * Virtual rule registration with jeeves-watcher.
- *
- * Service registers inference rules at startup (with retry) and
- * re-registers opportunistically when watcher restart is detected.
- *
- * @module rules
- */
-
-/**
- * Manages virtual rule registration with watcher.
- *
- * - Registers at startup with exponential retry
- * - Tracks watcher uptime for restart detection
- * - Re-registers opportunistically when uptime decreases
- */
-declare class RuleRegistrar {
-    private readonly config;
-    private readonly logger;
-    private readonly watcherClient;
-    private lastWatcherUptime;
-    private registered;
-    constructor(config: MetaConfig, logger: Logger, watcher: WatcherClient);
-    /** Whether rules have been successfully registered. */
-    get isRegistered(): boolean;
-    /**
-     * Register rules with watcher. Retries with exponential backoff.
-     * Non-blocking — logs errors but never throws.
-     */
-    register(): Promise<void>;
-    /**
-     * Check watcher uptime and re-register if it decreased (restart detected).
-     *
-     * @param currentUptime - Current watcher uptime in seconds.
-     */
-    checkAndReregister(currentUptime: number): Promise<void>;
-}
-
-/**
- * HTTP implementation of the WatcherClient interface.
- *
- * Talks to jeeves-watcher's POST /walk and POST /rules/register endpoints
- * with retry and exponential backoff.
- *
- * @module watcher-client/HttpWatcherClient
- */
-
-/** Options for creating an HttpWatcherClient. */
-interface HttpWatcherClientOptions {
-    /** Base URL for the watcher service (e.g. "http://localhost:1936"). */
-    baseUrl: string;
-    /** Maximum retry attempts for transient failures. Default: 3. */
-    maxRetries?: number;
-    /** Base delay in ms for exponential backoff. Default: 1000. */
-    backoffBaseMs?: number;
-    /** Multiplier for backoff. Default: 4 (1s, 4s, 16s). */
-    backoffFactor?: number;
-    /** Per-request timeout in ms. Default: 10000. */
-    timeoutMs?: number;
-}
-/**
- * HTTP-based WatcherClient implementation with retry.
- */
-declare class HttpWatcherClient implements WatcherClient {
-    private readonly baseUrl;
-    private readonly maxRetries;
-    private readonly backoffBaseMs;
-    private readonly backoffFactor;
-    private readonly timeoutMs;
-    constructor(options: HttpWatcherClientOptions);
-    /** POST JSON with retry. */
-    private post;
-    registerRules(source: string, rules: InferenceRuleSpec[]): Promise<void>;
-    walk(globs: string[]): Promise<string[]>;
-    scan(request: WatcherScanRequest): Promise<WatcherScanResult>;
-}
-
-/**
- * Croner-based scheduler that discovers the highest-priority ready phase
- * across the corpus each tick and enqueues it for execution.
- *
- * @module scheduler
- */
-
-/**
- * Periodic scheduler that discovers the highest-priority ready phase
- * across all metas and enqueues it for execution.
- *
- * Supports adaptive backoff when no candidates are found and hot-reloadable
- * cron expressions via {@link Scheduler.updateSchedule}.
- */
-declare class Scheduler {
-    private job;
-    private backoffMultiplier;
-    private tickCount;
-    private readonly config;
-    private readonly queue;
-    private readonly logger;
-    private readonly watcher;
-    private registrar;
-    private currentExpression;
-    constructor(config: ServiceConfig, queue: SynthesisQueue, logger: Logger, watcher: HttpWatcherClient);
-    /** Set the rule registrar for watcher restart detection. */
-    setRegistrar(registrar: RuleRegistrar): void;
-    /** Start the cron job. */
-    start(): void;
-    /** Stop the cron job. */
-    stop(): void;
-    /** Hot-reload the cron schedule expression. */
-    updateSchedule(expression: string): void;
-    /** Reset backoff multiplier (call after successful phase execution). */
-    resetBackoff(): void;
-    /** Whether the scheduler is currently running. */
-    get isRunning(): boolean;
-    /** Next scheduled tick time, or null if not running. */
-    get nextRunAt(): Date | null;
-    /**
-     * Single tick: discover the highest-priority ready phase and enqueue it.
-     *
-     * Applies adaptive backoff when no candidates are found.
-     */
-    private tick;
-    /**
-     * Discover the highest-priority ready phase across the corpus.
-     *
-     * Uses phase-state-aware scheduling: priority order is
-     * critic (band 1) \> builder (band 2) \> architect (band 3),
-     * with weighted staleness as tiebreaker within a band.
-     */
-    private discoverNextPhase;
-}
-
-/**
- * Shared live config hot-reload support.
- *
- * Used by both file-watch reloads in bootstrap and POST /config/apply
- * via the component descriptor's onConfigApply callback.
- *
- * @module configHotReload
- */
-
-/**
- * Fields that require a service restart to take effect.
- *
- * Shared between the descriptor's `onConfigApply` and the file-watcher
- * hot-reload in `bootstrap.ts`.
- */
-declare const RESTART_REQUIRED_FIELDS: readonly ["port", "watcherUrl", "gatewayUrl", "gatewayApiKey", "defaultArchitect", "defaultCritic"];
-
-/**
- * Load and resolve jeeves-meta service config.
- *
- * Supports \@file: indirection and environment-variable substitution (dollar-brace pattern).
- *
- * @module configLoader
- */
-
-/**
- * Migrate legacy config path to the new canonical location.
- *
- * If the old path `{configRoot}/jeeves-meta.config.json` exists and the new
- * path `{configRoot}/jeeves-meta/config.json` does NOT exist, copies the file
- * to the new location and logs a warning.
- *
- * @param configRoot - Root directory for configuration files.
- * @param warn - Optional callback for logging the migration warning.
- */
-declare function migrateConfigPath(configRoot: string, warn?: (msg: string) => void): void;
-/**
- * Resolve config path from --config flag or JEEVES_META_CONFIG env var.
- *
- * @param args - CLI arguments (process.argv.slice(2)).
- * @returns Resolved config path.
- * @throws If no config path found.
- */
-declare function resolveConfigPath(args: string[]): string;
-/**
- * Load service config from a JSON file.
- *
- * Resolves \@file: references for defaultArchitect and defaultCritic,
- * and substitutes environment-variable placeholders throughout.
- *
- * @param configPath - Path to config JSON file.
- * @returns Validated ServiceConfig.
- */
-declare function loadServiceConfig(configPath: string): ServiceConfig;
-
-/**
- * Jeeves component descriptor for jeeves-meta.
- *
- * Single source of truth consumed by the service CLI, plugin writer, and
- * config-apply pipeline.
- *
- * @module descriptor
- */
-
-/**
- * Parsed jeeves-meta component descriptor.
- */
-declare const metaDescriptor: JeevesComponentDescriptor;
-
-/**
- * Types for meta discovery and ownership tree.
- *
- * @module discovery/types
- */
-/** A discovered meta node in the ownership tree. */
-interface MetaNode {
-    /** Absolute path to the .meta directory. */
-    metaPath: string;
-    /** Absolute path to the parent directory that this meta owns. */
-    ownerPath: string;
-    /** Depth in the ownership tree (root = 0). */
-    treeDepth: number;
-    /** Child meta nodes (subtrees with their own .meta/). */
-    children: MetaNode[];
-    /** Parent meta node, or null for roots. */
-    parent: MetaNode | null;
-}
-/** The full ownership tree discovered from watchPaths. */
-interface OwnershipTree {
-    /** All discovered meta nodes, keyed by metaPath. */
-    nodes: Map<string, MetaNode>;
-    /** Root nodes (metas with no parent meta). */
-    roots: MetaNode[];
-}
-
-/**
- * Unified meta listing: scan, dedup, enrich.
- *
- * Single source of truth for all consumers that need a list of metas
- * with enriched metadata. Replaces duplicated scan+dedup logic in
- * plugin tools, CLI, and prompt injection.
- *
- * @module discovery/listMetas
- */
-
-/** Enriched meta entry returned by listMetas(). */
-interface MetaEntry {
-    /** Normalized .meta/ directory path. */
-    path: string;
-    /** Tree depth (0 = leaf, higher = more abstract). */
-    depth: number;
-    /** Scheduling emphasis multiplier. */
-    emphasis: number;
-    /** Seconds since last synthesis, or Infinity if never synthesized. */
-    stalenessSeconds: number;
-    /** ISO timestamp of last synthesis, or null. */
-    lastSynthesized: string | null;
-    /** Whether the last synthesis had an error. */
-    hasError: boolean;
-    /** Whether this meta is currently locked. */
-    locked: boolean;
-    /** Whether this meta is disabled (skipped during staleness scheduling). */
-    disabled: boolean;
-    /** Cumulative architect tokens, or null if never run. */
-    architectTokens: number | null;
-    /** Cumulative builder tokens, or null if never run. */
-    builderTokens: number | null;
-    /** Cumulative critic tokens, or null if never run. */
-    criticTokens: number | null;
-    /** Number of direct children in the ownership tree. */
-    children: number;
-    /** The underlying MetaNode from the ownership tree. */
-    node: MetaNode;
-    /** The parsed meta.json content. */
-    meta: MetaJson;
-}
-/** Summary statistics computed from the meta list. */
-interface MetaListSummary {
-    total: number;
-    stale: number;
-    errors: number;
-    locked: number;
-    disabled: number;
-    neverSynthesized: number;
-    tokens: {
-        architect: number;
-        builder: number;
-        critic: number;
-    };
-    stalestPath: string | null;
-    lastSynthesizedPath: string | null;
-    lastSynthesizedAt: string | null;
-}
-/** Full result from listMetas(). */
-interface MetaListResult {
-    summary: MetaListSummary;
-    entries: MetaEntry[];
-    tree: OwnershipTree;
-}
-/**
- * Discover, deduplicate, and enrich all metas.
- *
- * This is the single consolidated function that replaces all duplicated
- * scan+dedup+enrich logic across the codebase. All enrichment comes from
- * reading meta.json on disk (the canonical source).
- *
- * @param config - Validated synthesis config.
- * @param watcher - Watcher HTTP client for discovery.
- * @returns Enriched meta list with summary statistics and ownership tree.
- */
-declare function listMetas(config: MetaConfig, watcher: WatcherClient): Promise<MetaListResult>;
-
-/**
- * Discover .meta/ directories via watcher `/walk` endpoint.
- *
- * Uses filesystem enumeration through the watcher (not Qdrant) to find
- * all `.meta/meta.json` files and returns deduplicated meta directory paths.
- *
- * @module discovery/discoverMetas
- */
-
-/**
- * Discover all .meta/ directories via watcher walk.
- *
- * Uses the watcher's `/walk` endpoint to find all `.meta/meta.json` files
- * and returns deduplicated meta directory paths.
- *
- * @param watcher - WatcherClient for walk queries.
- * @returns Array of normalized .meta/ directory paths.
- */
-declare function discoverMetas(watcher: WatcherClient): Promise<string[]>;
-
-/**
- * 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
- */
-
-/**
- * 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.
- */
-declare function buildOwnershipTree(metaPaths: string[]): OwnershipTree;
-/**
- * Find a node in the ownership tree by meta path or owner path.
- *
- * @param tree - The ownership tree to search.
- * @param targetPath - Path to search for (meta path or owner path).
- * @returns The matching node, or undefined if not found.
- */
-declare function findNode(tree: OwnershipTree, targetPath: string): MetaNode | undefined;
-
-/**
- * Pino logger factory.
- *
- * @module logger
- */
-
-/** Minimal logger interface accepted by library functions. */
-interface MinimalLogger {
-    debug: (obj: Record<string, unknown>, msg: string) => void;
-    info: (obj: Record<string, unknown>, msg: string) => void;
-    warn: (obj: Record<string, unknown>, msg: string) => void;
-    error: (obj: Record<string, unknown>, msg: string) => void;
-}
-/** Logger configuration options. */
-interface LoggerConfig {
-    /** Log level (default: 'info'). */
-    level?: string;
-    /** Optional file path to write logs to. */
-    file?: string;
-}
-/**
- * Create a pino logger instance.
- *
- * @param config - Optional logger configuration.
- * @returns Configured pino logger.
- */
-declare function createLogger(config?: LoggerConfig): pino.Logger;
-
-/**
- * Compute the file scope owned by a meta node.
- *
- * A meta owns: parent dir + all descendants, minus:
- * - Its own .meta/ subtree (outputs, not inputs)
- * - Child meta ownerPath subtrees (except their .meta/meta.json for rollups)
- *
- * All filesystem enumeration delegated to the watcher's `/walk` endpoint.
- *
- * @module discovery/scope
- */
-
-/**
- * Get the scope path prefix for a meta node.
- */
-declare function getScopePrefix(node: MetaNode): string;
-/**
- * Filter a list of file paths to only those in scope for a meta node.
- *
- * Excludes:
- * - The node's own .meta/ subtree (synthesis outputs are not scope inputs)
- * - Child meta ownerPath subtrees (except child .meta/meta.json for rollups)
- *
- * Watcher walk returns normalized forward-slash paths.
- */
-declare function filterInScope(node: MetaNode, files: string[]): string[];
-
-/**
- * Exponential moving average helper for token tracking.
- *
- * @module ema
- */
-/**
- * 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.
- */
-declare function computeEma(current: number, previous: number | undefined, decay?: number): number;
-
-/**
- * Shared error utilities.
- *
- * @module errors
- */
-
-/**
- * Wrap an unknown caught value into a MetaError.
- *
- * @param step - Which synthesis step failed.
- * @param err - The caught error value.
- * @param code - Error classification code.
- * @returns A structured MetaError.
- */
-declare function toMetaError(step: MetaError['step'], err: unknown, code?: string): MetaError;
-
-/**
- * File-system lock for preventing concurrent synthesis on the same meta.
- *
- * Lock file: .meta/.lock containing `_lockPid` + `_lockStartedAt` (underscore-prefixed
- * reserved keys, consistent with meta.json conventions).
- * Stale timeout: 30 minutes.
- *
- * @module lock
- */
-/**
- * Resolve a path to a .meta directory.
- *
- * If the path already ends with '.meta', returns it as-is.
- * Otherwise, appends '.meta' as a subdirectory.
- *
- * @param inputPath - Path that may or may not end with '.meta'.
- * @returns The resolved .meta directory path.
- */
-declare function resolveMetaDir(inputPath: string): string;
-/** Parsed state of a .lock file. */
-interface LockState {
-    /** Whether the lock file exists. */
-    exists: boolean;
-    /** Whether the lock contains a staged synthesis result. */
-    staged: boolean;
-    /** Whether the lock is actively held (non-stale PID lock). */
-    active: boolean;
-    /** Raw parsed data, or null if missing/corrupt. */
-    data: Record<string, unknown> | null;
-}
-/**
- * Read and classify the state of a .meta/.lock file.
- *
- * @param metaPath - Absolute path to the .meta directory.
- * @returns Parsed lock state.
- */
-declare function readLockState(metaPath: string): LockState;
-/**
- * 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).
- */
-declare function acquireLock(metaPath: string): boolean;
-/**
- * Release a lock on a .meta directory.
- *
- * @param metaPath - Absolute path to the .meta directory.
- */
-declare function releaseLock(metaPath: string): void;
-/**
- * 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.
- */
-declare function isLocked(metaPath: string): boolean;
-/**
- * Clean up stale lock files on startup.
- *
- * For each .meta directory found via the provided paths:
- * - If lock contains PID-only data (synthesis incomplete), delete it.
- * - If lock contains staged result (_id present), log warning and delete.
- *
- * @param metaPaths - Array of .meta directory paths to check.
- * @param logger - Optional logger for warnings.
- */
-declare function cleanupStaleLocks(metaPaths: string[], logger?: {
-    warn: (obj: Record<string, unknown>, msg: string) => void;
-}): void;
-
-/**
- * Normalize file paths to forward slashes for consistency with watcher-indexed paths.
- *
- * Watcher indexes paths with forward slashes (`j:/domains/...`). This utility
- * ensures all paths in the library use the same convention, regardless of
- * the platform's native separator.
- *
- * @module normalizePath
- */
-/**
- * Normalize a file path to forward slashes.
- *
- * @param p - File path (may contain backslashes).
- * @returns Path with all backslashes replaced by forward slashes.
- */
-declare function normalizePath(p: string): string;
-
-/**
- * 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.
- */
-declare function computeStructureHash(filePaths: string[]): string;
-
-/**
- * MetaExecutor implementation using the OpenClaw gateway HTTP API.
- *
- * Lives in the library package so both plugin and runner can import it.
- * Spawns sub-agent sessions via the gateway's `/tools/invoke` endpoint,
- * polls for completion, and extracts output text.
- *
- * @module executor/GatewayExecutor
- */
-
-/** Options for the GatewayExecutor. */
-interface GatewayExecutorOptions {
-    /** OpenClaw gateway base URL. Default: http://127.0.0.1:18789 */
-    gatewayUrl?: string;
-    /** Bearer token for gateway authentication. */
-    apiKey?: string;
-    /** Polling interval in ms. Default: 5000. */
-    pollIntervalMs?: number;
-    /** Workspace directory for output staging. Default: OS temp dir + /jeeves-meta. */
-    workspaceDir?: string;
-}
-/**
- * MetaExecutor that spawns OpenClaw sessions via the gateway's
- * `/tools/invoke` endpoint.
- *
- * Used by both the OpenClaw plugin (in-process tool calls) and the
- * runner/CLI (external invocation). Constructs from `gatewayUrl` and
- * optional `apiKey` — typically sourced from `MetaConfig`.
- */
-declare class GatewayExecutor implements MetaExecutor {
-    private readonly gatewayUrl;
-    private readonly apiKey;
-    private readonly pollIntervalMs;
-    private readonly workspaceDir;
-    private controller;
-    constructor(options?: GatewayExecutorOptions);
-    /** Remove a temp output file if it exists. */
-    private cleanupOutputFile;
-    /** Invoke a gateway tool via the /tools/invoke HTTP endpoint. */
-    private invoke;
-    /** Look up totalTokens for a session via sessions_list. */
-    private getSessionTokens;
-    /** Whether this executor has been aborted by the operator. */
-    get aborted(): boolean;
-    /** Abort the currently running spawn, if any. */
-    abort(): void;
-    spawn(task: string, options?: MetaSpawnOptions): Promise<MetaSpawnResult>;
-}
-
-/**
- * Build task prompts for each synthesis step.
- *
- * Prompts are compiled as Handlebars templates with access to config,
- * meta, and scope context. The architect can write template expressions
- * into its _builder output; these resolve when the builder task is compiled.
- *
- * @module orchestrator/buildTask
- */
-
-/**
- * Build the architect task prompt.
- *
- * @param ctx - Synthesis context.
- * @param meta - Current meta.json.
- * @param config - Synthesis config.
- * @returns The architect task prompt string.
- */
-declare function buildArchitectTask(ctx: MetaContext, meta: MetaJson, config: MetaConfig): string;
-/**
- * Build the builder task prompt.
- *
- * @param ctx - Synthesis context.
- * @param meta - Current meta.json.
- * @param config - Synthesis config.
- * @returns The builder task prompt string.
- */
-declare function buildBuilderTask(ctx: MetaContext, meta: MetaJson, config: MetaConfig): string;
-/**
- * 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.
- */
-declare function buildCriticTask(ctx: MetaContext, meta: MetaJson, config: MetaConfig): string;
-
-/**
- * Build the MetaContext 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
- */
-
-/**
- * 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.
- */
-declare function buildContextPackage(node: MetaNode, meta: MetaJson, watcher: WatcherClient, logger?: MinimalLogger): Promise<MetaContext>;
-
-/**
- * Parse subprocess outputs for each synthesis step.
- *
- * - Architect: returns text \> _builder
- * - Builder: returns JSON \> _content + structured fields
- * - Critic: returns text \> _feedback
- *
- * @module orchestrator/parseOutput
- */
-/** Parsed builder output. */
-interface BuilderOutput {
-    /** Narrative synthesis content. */
-    content: string;
-    /** Additional structured fields (non-underscore keys). */
-    fields: Record<string, unknown>;
-    /** Opaque state for progressive synthesis, if provided by the builder. */
-    state?: unknown;
-}
-/**
- * Parse architect output. The architect returns a task brief as text.
- *
- * @param output - Raw subprocess output.
- * @returns The task brief string.
- */
-declare function parseArchitectOutput(output: string): string;
-/**
- * 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.
- */
-declare function parseBuilderOutput(output: string): BuilderOutput;
-/**
- * Parse critic output. The critic returns evaluation text.
- *
- * @param output - Raw subprocess output.
- * @returns The feedback string.
- */
-declare function parseCriticOutput(output: string): string;
-
-/**
- * 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
- */
-
-/** Options for merging synthesis results. */
-interface MergeOptions {
-    /** Path to .meta directory. */
-    metaPath: string;
-    /** Current meta.json content. */
-    current: MetaJson;
-    /** Architect prompt used (or existing). */
-    architect: string;
-    /** Builder task brief (new or cached). */
-    builder: string;
-    /** Critic prompt used (or existing). */
-    critic: string;
-    /** Builder output (content + structured fields), or null if builder failed. */
-    builderOutput: BuilderOutput | null;
-    /** Critic feedback, or null if critic failed. */
-    feedback: string | null;
-    /** New structure hash. */
-    structureHash: string;
-    /** New synthesis count. */
-    synthesisCount: number;
-    /** Error from any step, or null on full success. */
-    error: MetaError | null;
-    /** Token count from architect step. */
-    architectTokens?: number;
-    /** Token count from builder step. */
-    builderTokens?: number;
-    /** Token count from critic step. */
-    criticTokens?: number;
-    /** Override output path (default: metaPath/meta.json). Used for lock staging. */
-    outputPath?: string;
-    /** Opaque state from builder output for progressive synthesis. */
-    state?: unknown;
-    /**
-     * When true, preserve _content and _generatedAt from current meta.
-     * Used for timeout recovery where state advanced but content did not.
-     */
-    stateOnly?: boolean;
-    /** Phase state record to persist. */
-    phaseState?: PhaseState;
-}
-/**
- * Merge results into meta.json and write atomically.
- *
- * @param options - Merge options.
- * @returns The updated MetaJson.
- * @throws If validation fails (malformed output).
- */
-declare function mergeAndWrite(options: MergeOptions): Promise<MetaJson>;
-
-/**
- * Progress reporting via OpenClaw gateway `/tools/invoke` → `message` tool.
- *
- * @module progress
- */
-
-type ProgressPhase = 'architect' | 'builder' | 'critic';
-type ProgressEvent = {
-    type: 'synthesis_start' | 'phase_start' | 'phase_complete' | 'synthesis_complete' | 'error';
-    /** Owner path (not .meta path) of the entity being synthesized. */
-    path: string;
-    phase?: ProgressPhase;
-    tokens?: number;
-    durationMs?: number;
-    error?: string;
-};
-type ProgressReporterConfig = {
-    gatewayUrl: string;
-    gatewayApiKey?: string;
-    /**
-     * Messaging channel name (e.g. 'slack'). When set alongside reportTarget,
-     * included in the gateway message payload as `channel`.
-     * Legacy: if reportTarget is unset, reportChannel is used as the target
-     * (single-channel mode, backward compatible).
-     */
-    reportChannel?: string;
-    /** Channel/user ID to send messages to. Takes priority over reportChannel as target. */
-    reportTarget?: string;
-    /** Optional base URL for the service, used to construct entity links. */
-    serverBaseUrl?: string;
-};
-declare function formatProgressEvent(event: ProgressEvent, serverBaseUrl?: string): string;
-declare class ProgressReporter {
-    private readonly config;
-    private readonly logger;
-    constructor(config: ProgressReporterConfig, logger: Logger);
-    report(event: ProgressEvent): Promise<void>;
-}
-
-/**
- * Main orchestration entry point — discovery, scheduling, candidate selection.
- *
- * @module orchestrator/orchestrate
- */
-
-/** Callback for synthesis progress events. */
-type ProgressCallback$1 = (event: ProgressEvent) => void | Promise<void>;
-/** Result of a single orchestration cycle. */
-interface OrchestrateResult {
-    /** Whether a synthesis was performed. */
-    synthesized: boolean;
-    /** Path to the meta that was synthesized, if any. */
-    metaPath?: string;
-    /** Error if synthesis failed. */
-    error?: MetaError;
-}
-/**
- * Run a single synthesis cycle.
- *
- * Selects the stalest candidate (or a specific target) and runs the
- * full architect/builder/critic pipeline.
- *
- * @param config - Validated synthesis config.
- * @param executor - Pluggable LLM executor.
- * @param watcher - Watcher HTTP client.
- * @param targetPath - Optional: specific meta/owner path to synthesize instead of stalest candidate.
- * @returns Array with a single result.
- */
-declare function orchestrate(config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, targetPath?: string, onProgress?: ProgressCallback$1, logger?: MinimalLogger): Promise<OrchestrateResult[]>;
-
-/**
- * Per-phase executors for the phase-state machine.
- *
- * Each function runs exactly one phase on one meta, updates _phaseState
- * via pure transitions, and persists via the lock-staged write.
- *
- * @module orchestrator/runPhase
- */
-
-/** Callback for synthesis progress events. */
-type ProgressCallback = (event: ProgressEvent) => void | Promise<void>;
-/** Result of running a single phase. */
-interface PhaseResult {
-    /** Whether the phase executed (vs. was skipped). */
-    executed: boolean;
-    /** Updated phase state after execution. */
-    phaseState: PhaseState;
-    /** Updated meta.json content (if written). */
-    updatedMeta?: MetaJson;
-    /** Error if the phase failed. */
-    error?: MetaError;
-    /** Whether the full cycle is now complete (all phases fresh). */
-    cycleComplete?: boolean;
-}
-declare function runArchitect(node: MetaNode, currentMeta: MetaJson, phaseState: PhaseState, config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, structureHash: string, onProgress?: ProgressCallback, logger?: MinimalLogger): Promise<PhaseResult>;
-declare function runBuilder(node: MetaNode, currentMeta: MetaJson, phaseState: PhaseState, config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, structureHash: string, onProgress?: ProgressCallback, logger?: MinimalLogger): Promise<PhaseResult>;
-declare function runCritic(node: MetaNode, currentMeta: MetaJson, phaseState: PhaseState, config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, structureHash: string, onProgress?: ProgressCallback, logger?: MinimalLogger): Promise<PhaseResult>;
-
-/**
- * Phase-aware orchestration entry point.
- *
- * Replaces the old staleness-based orchestrate() with phase-state-machine
- * scheduling: each tick discovers all metas, computes invalidation,
- * auto-retries failed phases, selects the best phase candidate, and
- * executes exactly one phase.
- *
- * @module orchestrator/orchestratePhase
- */
-
-/** Callback for synthesis progress events. */
-type PhaseProgressCallback = (event: ProgressEvent) => void | Promise<void>;
-/** Result of a single phase-aware orchestration tick. */
-interface OrchestratePhaseResult {
-    /** Whether a phase was executed. */
-    executed: boolean;
-    /** Path to the meta that was selected. */
-    metaPath?: string;
-    /** Which phase was run. */
-    phase?: PhaseName;
-    /** The phase result (if executed). */
-    phaseResult?: PhaseResult;
-    /** Whether a full synthesis cycle completed (all phases fresh). */
-    cycleComplete?: boolean;
-}
-/**
- * Run a single phase-aware orchestration tick.
- *
- * When targetPath is provided (override entry), runs the owed phase for
- * that specific meta. Otherwise, discovers all metas, computes invalidation,
- * and selects the best phase candidate corpus-wide.
- */
-declare function orchestratePhase(config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, targetPath?: string, onProgress?: PhaseProgressCallback, logger?: MinimalLogger): Promise<OrchestratePhaseResult>;
-
-/**
- * Weighted staleness formula for candidate selection.
- *
- * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
- *
- * @module scheduling/weightedFormula
- */
-
-/** A candidate meta with computed staleness. */
-interface StalenessCandidate {
-    /** The meta node. */
-    node: MetaNode;
-    /** Current meta.json content. */
-    meta: MetaJson;
-    /** Actual staleness in seconds. */
-    actualStaleness: number;
-    /** Effective staleness after depth weighting. */
-    effectiveStaleness: number;
-}
-/**
- * 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.
- */
-declare function computeEffectiveStaleness(candidates: Array<{
-    node: MetaNode;
-    meta: MetaJson;
-    actualStaleness: number;
-}>, depthWeight: number): StalenessCandidate[];
-
-/**
- * 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.
- */
-declare function selectCandidate(candidates: StalenessCandidate[]): StalenessCandidate | null;
-
-/**
- * Staleness detection via watcher walk.
- *
- * A meta is stale when any watched file in its scope was modified after
- * `_generatedAt`.
- *
- * @module scheduling/staleness
- */
-
-/**
- * Check if a meta is stale.
- *
- * Uses watcher `/walk` to enumerate watched files under the scope prefix,
- * then applies a local mtime check (fast) to detect any modifications since
- * `_generatedAt`. Short-circuits on first match.
- *
- * @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`.
- */
-declare function isStale(scopePrefix: string, meta: MetaJson, watcher: WatcherClient): Promise<boolean>;
-/** Maximum staleness for never-synthesized metas (1 year in seconds). */
-declare const MAX_STALENESS_SECONDS: number;
-/**
- * Compute actual staleness in seconds (now minus _generatedAt).
- *
- * Never-synthesized metas are capped at {@link MAX_STALENESS_SECONDS}
- * (1 year) so that depth weighting can differentiate them. Without
- * bounding, `Infinity * depthFactor` = `Infinity` for all depths.
- *
- * @param meta - Current meta.json content.
- * @returns Staleness in seconds, capped at 1 year for never-synthesized metas.
- */
-declare function actualStaleness(meta: MetaJson): number;
-/**
- * Check whether the architect step should be triggered.
- *
- * @param meta - Current meta.json.
- * @param structureChanged - Whether the structure hash changed.
- * @param steerChanged - Whether the steer directive changed.
- * @param architectEvery - Config: run architect every N cycles.
- * @returns True if the architect step should run.
- */
-declare function isArchitectTriggered(meta: MetaJson, structureChanged: boolean, steerChanged: boolean, architectEvery: number): boolean;
-/**
- * Detect whether the steer directive changed since the last archive.
- *
- * @param currentSteer - Current _steer value (or undefined).
- * @param archiveSteer - Archive _steer value (or undefined).
- * @param hasArchive - Whether an archive snapshot exists.
- * @returns True if steer changed.
- */
-declare function hasSteerChanged(currentSteer: string | undefined, archiveSteer: string | undefined, hasArchive: boolean): boolean;
-
-/**
- * Route registration for jeeves-meta service.
- *
- * @module routes
- */
-
-/** Runtime stats tracked by the service. */
-interface ServiceStats {
-    totalSyntheses: number;
-    totalTokens: number;
-    totalErrors: number;
-    lastCycleDurationMs: number | null;
-    lastCycleAt: string | null;
-}
-/** Dependencies injected into route handlers. */
-interface RouteDeps {
-    config: ServiceConfig;
-    logger: Logger;
-    queue: SynthesisQueue;
-    watcher: WatcherClient;
-    scheduler: Scheduler | null;
-    stats: ServiceStats;
-    /** Rule registrar for reporting registration state in /status. */
-    registrar?: RuleRegistrar;
-    /** Executor instance for abort support. */
-    executor?: Pick<GatewayExecutor, 'abort'>;
-    /** Set to true during graceful shutdown. */
-    shuttingDown?: boolean;
-    /** Runtime config file path for config-apply. */
-    configPath?: string;
-}
-/** Register all HTTP routes on the Fastify instance. */
-declare function registerRoutes(app: FastifyInstance, deps: RouteDeps): void;
-
-/**
- * Post-registration verification of virtual rule application.
- *
- * After rules are registered with the watcher, verifies that .meta/meta.json
- * files are discoverable via watcher walk (which depends on virtual rules
- * being applied). Logs a warning if expected metas are not found.
- *
- * @module rules/verify
- */
-
-/**
- * Verify that virtual rules are applied to indexed .meta/meta.json files.
- *
- * Runs a discovery pass and logs the result. If no metas are found but
- * the filesystem likely has some, logs a warning suggesting reindex.
- *
- * @param watcher - WatcherClient for discovery.
- * @param logger - Logger for reporting results.
- * @returns Number of metas discovered.
- */
-declare function verifyRuleApplication(watcher: WatcherClient, logger: MinimalLogger): Promise<number>;
-
-/** Options for creating the server. */
-interface ServerOptions {
-    /** Pino logger instance. */
-    logger: Logger;
-    /** Shared route dependencies (mutable — late-bound properties like registrar are set after creation). */
-    deps: RouteDeps;
-}
-/**
- * Create and configure the Fastify server.
- *
- * @param options - Server creation options.
- * @returns Configured Fastify instance (not yet listening).
- */
-declare function createServer(options: ServerOptions): fastify.FastifyInstance<node_http.Server<typeof node_http.IncomingMessage, typeof node_http.ServerResponse>, node_http.IncomingMessage, node_http.ServerResponse<node_http.IncomingMessage>, FastifyBaseLogger, fastify.FastifyTypeProviderDefault> & PromiseLike<fastify.FastifyInstance<node_http.Server<typeof node_http.IncomingMessage, typeof node_http.ServerResponse>, node_http.IncomingMessage, node_http.ServerResponse<node_http.IncomingMessage>, FastifyBaseLogger, fastify.FastifyTypeProviderDefault>> & {
-    __linterBrands: "SafePromiseLike";
-};
-
-/**
- * Graceful shutdown handler.
- *
- * On SIGTERM/SIGINT: stops scheduler, drains queue, cleans up locks.
- *
- * @module shutdown
- */
-
-interface ShutdownDeps {
-    server: {
-        close: () => Promise<void>;
-    };
-    scheduler: Scheduler | null;
-    queue: SynthesisQueue;
-    logger: Logger;
-    routeDeps?: RouteDeps;
-    /** Optional cleanup callback (e.g., stop health check). */
-    onShutdown?: () => void;
-}
-/**
- * Register shutdown handlers for SIGTERM and SIGINT.
- *
- * Flow:
- * 1. Stop scheduler (no new ticks)
- * 2. If synthesis in progress, release its lock
- * 3. Close Fastify server
- * 4. Exit
- */
-declare function registerShutdownHandlers(deps: ShutdownDeps): void;
-
-/**
- * Service bootstrap — wire up all components and start listening.
- *
- * @module bootstrap
- */
-
-/**
- * Bootstrap the service: create logger, build server, start listening,
- * wire scheduler, queue processing, rule registration, config hot-reload,
- * startup lock cleanup, and shutdown.
- *
- * @param config - Validated service configuration.
- * @param configPath - Optional path to config file for hot-reload.
- */
-declare function startService(config: ServiceConfig, configPath?: string): Promise<void>;
-
-export { DEFAULT_PORT, DEFAULT_PORT_STR, GatewayExecutor, HttpWatcherClient, MAX_STALENESS_SECONDS, ProgressReporter, RESTART_REQUIRED_FIELDS, RuleRegistrar, SERVICE_NAME, SERVICE_VERSION, Scheduler, SynthesisQueue, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildOwnershipTree, cleanupStaleLocks, computeEffectiveStaleness, computeEma, computeStructureHash, createLogger, createServer, createSnapshot, discoverMetas, filterInScope, findNode, formatProgressEvent, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, listMetas, loadServiceConfig, mergeAndWrite, metaConfigSchema, metaDescriptor, metaErrorSchema, metaJsonSchema, migrateConfigPath, normalizePath, orchestrate, orchestratePhase, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerCustomCliCommands, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, runArchitect, runBuilder, runCritic, selectCandidate, serviceConfigSchema, startService, toMetaError, verifyRuleApplication };
-export type { BuilderOutput, EnqueueResult, GatewayExecutorOptions, HttpWatcherClientOptions, InferenceRuleSpec, LockState, LoggerConfig, MergeOptions, MetaConfig, MetaContext, MetaEntry, MetaError, MetaExecutor, MetaJson, MetaListResult, MetaListSummary, MetaNode, MetaSpawnOptions, MetaSpawnResult, MinimalLogger, OrchestratePhaseResult, OrchestrateResult, OwnershipTree, PhaseProgressCallback, PhaseResult, ProgressCallback$1 as ProgressCallback, ProgressEvent, ProgressPhase, ProgressReporterConfig, QueueItem, QueueState, RouteDeps, ServerOptions, ServiceConfig, ServiceStats, StalenessCandidate, WatcherClient, WatcherScanPoint, WatcherScanRequest, WatcherScanResult };
+ * Jeeves Meta Service — knowledge synthesis HTTP service for the Jeeves platform.
+ *
+ * @packageDocumentation
+ */
+export { createSnapshot, listArchiveFiles, pruneArchive, readLatestArchive, } from './archive/index.js';
+export { DEFAULT_PORT, DEFAULT_PORT_STR, SERVICE_NAME, SERVICE_VERSION, } from './constants.js';
+export { registerCustomCliCommands } from './customCliCommands.js';
+export { metaDescriptor, RESTART_REQUIRED_FIELDS } from './descriptor.js';
+export { loadServiceConfig, migrateConfigPath, resolveConfigPath, } from './configLoader.js';
+export { buildOwnershipTree, discoverMetas, filterInScope, findNode, getScopePrefix, listMetas, type MetaEntry, type MetaListResult, type MetaListSummary, type MetaNode, type OwnershipTree, } from './discovery/index.js';
+export { computeEma } from './ema.js';
+export { toMetaError } from './errors.js';
+export { acquireLock, cleanupStaleLocks, isLocked, type LockState, readLockState, releaseLock, resolveMetaDir, } from './lock.js';
+export { normalizePath } from './normalizePath.js';
+export { computeStructureHash } from './structureHash.js';
+export { GatewayExecutor, type GatewayExecutorOptions, } from './executor/index.js';
+export type { InferenceRuleSpec, MetaContext, MetaExecutor, MetaSpawnOptions, MetaSpawnResult, WatcherClient, WatcherScanPoint, WatcherScanRequest, WatcherScanResult, } from './interfaces/index.js';
+export type { LoggerConfig } from './logger/index.js';
+export { createLogger, type MinimalLogger } from './logger/index.js';
+export { buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, type BuilderOutput, orchestratePhase, type OrchestratePhaseResult, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, type PhaseProgressCallback, type PhaseResult, runArchitect, runBuilder, runCritic, } from './orchestrator/index.js';
+export { formatProgressEvent, type ProgressEvent, type ProgressPhase, ProgressReporter, type ProgressReporterConfig, } from './progress/index.js';
+export { actualStaleness, computeEffectiveStaleness, hasSteerChanged, isArchitectTriggered, isStale, MAX_STALENESS_SECONDS, type StalenessCandidate, } from './scheduling/index.js';
+export { type MetaConfig, metaConfigSchema, type MetaError, metaErrorSchema, type MetaJson, metaJsonSchema, type ServiceConfig, serviceConfigSchema, } from './schema/index.js';
+export { Scheduler } from './scheduler/index.js';
+export { type EnqueueResult, type QueueItem, type QueueState, SynthesisQueue, } from './queue/index.js';
+export { registerRoutes, type RouteDeps, type ServiceStats, } from './routes/index.js';
+export { RuleRegistrar } from './rules/index.js';
+export { verifyRuleApplication } from './rules/verify.js';
+export { sleepAsync as sleep } from '@karmaniverous/jeeves';
+export type { ServerOptions } from './server.js';
+export { createServer } from './server.js';
+export { registerShutdownHandlers } from './shutdown/index.js';
+export { HttpWatcherClient, type HttpWatcherClientOptions, } from './watcher-client/index.js';
+export { startService } from './bootstrap.js';