@karmaniverous/jeeves-meta 0.14.0 → 0.15.0

package/dist/index.d.ts

@@ -111,6 +111,12 @@ interface MetaExecutor {
      * @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;
 }
 
 /**
@@ -283,6 +289,16 @@ type MetaError = z.infer<typeof metaErrorSchema>;
  * @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>;
@@ -317,6 +333,29 @@ declare const metaJsonSchema: z.ZodObject<{
         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>;
@@ -380,11 +419,15 @@ declare const SERVICE_VERSION: string;
 declare function registerCustomCliCommands(program: Command): void;
 
 /**
- * Single-threaded synthesis queue with priority support and deduplication.
+ * 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.
  *
- * The scheduler enqueues the stalest candidate each tick. HTTP-triggered
- * synthesis requests get priority (inserted at front). A path appears at
- * most once in the queue; re-triggering returns the current position.
+ * Legacy: `pending` array is the union of overrides + automatic.
  *
  * @module queue
  */
@@ -395,6 +438,17 @@ interface QueueItem {
     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;
@@ -410,28 +464,44 @@ interface QueueState {
     }>;
 }
 /**
- * Single-threaded synthesis queue.
+ * Hybrid 3-layer synthesis queue.
  *
- * Only one synthesis runs at a time. Priority items are inserted at the
- * front of the queue. Duplicate paths are rejected with their current
- * position returned.
+ * 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;
-    /**
-     * Create a new SynthesisQueue.
-     *
-     * @param logger - Pino logger instance.
-     */
+    /** 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;
     /**
-     * Set a callback to invoke when a new (non-duplicate) item is enqueued.
+     * Add an explicit override entry (from POST /synthesize with path).
+     * Deduped by path. Returns position and whether already queued.
      */
-    onEnqueue(callback: () => void): void;
+    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.
      *
@@ -440,11 +510,7 @@ declare class SynthesisQueue {
      * @returns Position and whether the path was already queued.
      */
     enqueue(path: string, priority?: boolean): EnqueueResult;
-    /**
-     * Remove and return the next item from the queue.
-     *
-     * @returns The next QueueItem, or undefined if the queue is empty.
-     */
+    /** Remove and return the next item from the queue. */
     dequeue(): QueueItem | undefined;
     /** Mark the currently-running synthesis as complete. */
     complete(): void;
@@ -458,35 +524,23 @@ declare class SynthesisQueue {
     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.
-     *
-     * @param path - Meta path to look up.
-     * @returns True if the path is queued or currently running.
-     */
+    /** 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.
-     *
-     * @param path - Meta path to look up.
-     * @returns Position index, or null if not found in the queue.
-     */
+    /** Get the 0-indexed position of a path in the queue. */
     getPosition(path: string): number | null;
-    /**
-     * Return a snapshot of queue state for the /status endpoint.
-     *
-     * @returns Queue depth and item list.
-     */
+    /** 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 the queue is empty.
+     * 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.
      *
@@ -573,14 +627,15 @@ declare class HttpWatcherClient implements WatcherClient {
 }
 
 /**
- * Croner-based scheduler that discovers the stalest meta candidate each tick
- * and enqueues it for synthesis.
+ * 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 stale meta candidates and enqueues them.
+ * 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}.
@@ -604,23 +659,26 @@ declare class Scheduler {
     stop(): void;
     /** Hot-reload the cron schedule expression. */
     updateSchedule(expression: string): void;
-    /** Reset backoff multiplier (call after successful synthesis). */
+    /** 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 stalest candidate and enqueue it.
+     * Single tick: discover the highest-priority ready phase and enqueue it.
      *
-     * Skips if the queue is currently processing. Applies adaptive backoff
-     * when no candidates are found.
+     * Applies adaptive backoff when no candidates are found.
      */
     private tick;
     /**
-     * Discover the stalest meta candidate via watcher.
+     * 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 discoverStalest;
+    private discoverNextPhase;
 }
 
 /**
@@ -1073,6 +1131,8 @@ declare class GatewayExecutor implements MetaExecutor {
     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>;
@@ -1224,6 +1284,8 @@ interface MergeOptions {
      * 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.
@@ -1280,7 +1342,7 @@ declare class ProgressReporter {
  */
 
 /** Callback for synthesis progress events. */
-type ProgressCallback = (event: ProgressEvent) => void | Promise<void>;
+type ProgressCallback$1 = (event: ProgressEvent) => void | Promise<void>;
 /** Result of a single orchestration cycle. */
 interface OrchestrateResult {
     /** Whether a synthesis was performed. */
@@ -1302,7 +1364,70 @@ interface OrchestrateResult {
  * @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, logger?: MinimalLogger): Promise<OrchestrateResult[]>;
+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.
@@ -1532,5 +1657,5 @@ declare function registerShutdownHandlers(deps: ShutdownDeps): void;
  */
 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, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerCustomCliCommands, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, 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, OrchestrateResult, OwnershipTree, ProgressCallback, ProgressEvent, ProgressPhase, ProgressReporterConfig, QueueItem, QueueState, RouteDeps, ServerOptions, ServiceConfig, ServiceStats, StalenessCandidate, WatcherClient, WatcherScanPoint, WatcherScanRequest, WatcherScanResult };
+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 };