@karmaniverous/jeeves-meta 0.15.3 → 0.15.5

package/dist/interfaces/MetaContext.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+export 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[];
+}

package/dist/interfaces/MetaExecutor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pluggable executor interface for LLM subprocess invocation.
+ *
+ * @module interfaces/MetaExecutor
+ */
+/** Options for spawning a synthesis subprocess. */
+export 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. */
+export 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.
+ */
+export 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;
+}

package/dist/interfaces/WatcherClient.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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. */
+export 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. */
+export interface WatcherScanRequest {
+    filter: Record<string, unknown>;
+    limit?: number;
+    cursor?: string;
+    fields?: string[];
+    countOnly?: boolean;
+}
+/** A single point returned from watcher scan. */
+export interface WatcherScanPoint {
+    id?: string | number;
+    payload?: Record<string, unknown>;
+}
+/** Response shape for watcher scan queries. */
+export interface WatcherScanResult {
+    points: WatcherScanPoint[];
+    cursor: string | null;
+}
+/**
+ * Interface for watcher HTTP operations.
+ *
+ * Implementations handle retry with backoff internally.
+ */
+export 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>;
+}

package/dist/interfaces/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-exports for all interface modules.
+ *
+ * @module interfaces
+ */
+export type { MetaContext } from './MetaContext.js';
+export type { MetaExecutor, MetaSpawnOptions, MetaSpawnResult, } from './MetaExecutor.js';
+export type { InferenceRuleSpec, WatcherClient, WatcherScanPoint, WatcherScanRequest, WatcherScanResult, } from './WatcherClient.js';

package/dist/lock.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+export declare function resolveMetaDir(inputPath: string): string;
+/** Parsed state of a .lock file. */
+export 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.
+ */
+export 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).
+ */
+export declare function acquireLock(metaPath: string): boolean;
+/**
+ * Release a lock on a .meta directory.
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function cleanupStaleLocks(metaPaths: string[], logger?: {
+    warn: (obj: Record<string, unknown>, msg: string) => void;
+}): void;

package/dist/logger/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Pino logger factory.
+ *
+ * @module logger
+ */
+import pino from 'pino';
+/** Minimal logger interface accepted by library functions. */
+export 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. */
+export 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.
+ */
+export declare function createLogger(config?: LoggerConfig): pino.Logger;

package/dist/mtimeFilter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Filter file paths by modification time.
+ *
+ * Shared utility for staleness detection and delta file enumeration.
+ * Uses `fs.statSync` for fast local mtime checks on known paths.
+ *
+ * @module mtimeFilter
+ */
+/**
+ * Check if any file in the list was modified after the given timestamp.
+ *
+ * Short-circuits on first match for efficiency (staleness checks).
+ *
+ * @param files - Array of file paths to check.
+ * @param afterMs - Timestamp in milliseconds. Files with `mtimeMs > afterMs` match.
+ * @returns True if any file was modified after the timestamp.
+ */
+export declare function hasModifiedAfter(files: string[], afterMs: number): boolean;
+/**
+ * Filter files to only those modified after the given timestamp.
+ *
+ * @param files - Array of file paths to filter.
+ * @param afterMs - Timestamp in milliseconds. Files with `mtimeMs > afterMs` are included.
+ * @returns Filtered array of file paths.
+ */
+export declare function filterModifiedAfter(files: string[], afterMs: number): string[];

package/dist/normalizePath.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-export normalizePath from core.
+ *
+ * @module normalizePath
+ */
+export { normalizePath } from '@karmaniverous/jeeves-meta-core';

package/dist/orchestrator/buildTask.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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
+ */
+import type { MetaContext } from '../interfaces/index.js';
+import type { MetaConfig, MetaJson } from '../schema/index.js';
+/**
+ * Build the architect task prompt.
+ *
+ * @param ctx - Synthesis context.
+ * @param meta - Current meta.json.
+ * @param config - Synthesis config.
+ * @returns The architect task prompt string.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function buildCriticTask(ctx: MetaContext, meta: MetaJson, config: MetaConfig): string;

package/dist/orchestrator/contextPackage.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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
+ */
+import { type MetaNode } from '../discovery/index.js';
+import type { MetaContext, WatcherClient } from '../interfaces/index.js';
+import type { MinimalLogger } from '../logger/index.js';
+import type { MetaJson } from '../schema/index.js';
+/**
+ * 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.
+ */
+export declare function condenseScopeFiles(files: string[], maxIndividual?: number): string;
+/**
+ * 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.
+ */
+export declare function buildContextPackage(node: MetaNode, meta: MetaJson, watcher: WatcherClient, logger?: MinimalLogger): Promise<MetaContext>;

package/dist/orchestrator/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Orchestrator module — the main synthesis cycle.
+ *
+ * @module orchestrator
+ */
+export { buildArchitectTask, buildBuilderTask, buildCriticTask, } from './buildTask.js';
+export { buildContextPackage } from './contextPackage.js';
+export { orchestratePhase, type OrchestratePhaseResult, type PhaseProgressCallback, } from './orchestratePhase.js';
+export { type BuilderOutput, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, } from './parseOutput.js';
+export { type PhaseResult, runArchitect, runBuilder, runCritic, } from './runPhase.js';

package/dist/orchestrator/orchestratePhase.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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
+ */
+import type { MetaExecutor, WatcherClient } from '../interfaces/index.js';
+import type { MinimalLogger } from '../logger/index.js';
+import type { ProgressEvent } from '../progress/index.js';
+import type { MetaConfig, PhaseName } from '../schema/index.js';
+import { type PhaseResult } from './runPhase.js';
+/** Callback for synthesis progress events. */
+export type PhaseProgressCallback = (event: ProgressEvent) => void | Promise<void>;
+/** Result of a single phase-aware orchestration tick. */
+export 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.
+ */
+export declare function orchestratePhase(config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, targetPath?: string, onProgress?: PhaseProgressCallback, logger?: MinimalLogger): Promise<OrchestratePhaseResult>;

package/dist/orchestrator/parseOutput.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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. */
+export 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.
+ */
+export 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.
+ */
+export declare function parseBuilderOutput(output: string): BuilderOutput;
+/**
+ * Parse critic output. The critic returns evaluation text.
+ *
+ * @param output - Raw subprocess output.
+ * @returns The feedback string.
+ */
+export declare function parseCriticOutput(output: string): string;

package/dist/orchestrator/runPhase.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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
+ */
+import type { MetaNode } from '../discovery/index.js';
+import type { MetaExecutor, WatcherClient } from '../interfaces/index.js';
+import type { MinimalLogger } from '../logger/index.js';
+import type { ProgressEvent } from '../progress/index.js';
+import type { MetaConfig, MetaError, MetaJson, PhaseState } from '../schema/index.js';
+/** Callback for synthesis progress events. */
+export type ProgressCallback = (event: ProgressEvent) => void | Promise<void>;
+/** Result of running a single phase. */
+export 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;
+}
+/** Shared base options for all finalize calls. */
+export interface FinalizeBase {
+    metaPath: string;
+    current: MetaJson;
+    config: MetaConfig;
+    structureHash: string;
+}
+/** Write updated meta with phase state via lock staging. */
+export declare function persistPhaseState(base: FinalizeBase, phaseState: PhaseState, updates: Partial<MetaJson>): Promise<MetaJson>;
+export declare function runArchitect(node: MetaNode, currentMeta: MetaJson, phaseState: PhaseState, config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, structureHash: string, onProgress?: ProgressCallback, logger?: MinimalLogger): Promise<PhaseResult>;
+export declare function runBuilder(node: MetaNode, currentMeta: MetaJson, phaseState: PhaseState, config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, structureHash: string, onProgress?: ProgressCallback, logger?: MinimalLogger): Promise<PhaseResult>;
+export declare function runCritic(node: MetaNode, currentMeta: MetaJson, phaseState: PhaseState, config: MetaConfig, executor: MetaExecutor, watcher: WatcherClient, structureHash: string, onProgress?: ProgressCallback, logger?: MinimalLogger): Promise<PhaseResult>;

package/dist/phaseState/derivePhaseState.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Backward-compatible derivation of _phaseState from existing meta fields.
+ *
+ * When a meta is loaded from disk without _phaseState, this reconstructs
+ * the phase state from _content, _builder, _state, _error.step, and
+ * the architect-invalidating inputs.
+ *
+ * @module phaseState/derivePhaseState
+ */
+import type { MetaJson, PhaseState } from '../schema/index.js';
+/** Inputs needed to determine architect invalidation for derivation. */
+export interface DerivationInputs {
+    /** Whether _structureHash has changed vs. computed value. */
+    structureChanged: boolean;
+    /** Whether _steer changed vs. latest archive. */
+    steerChanged: boolean;
+    /** Whether _architect prompt changed. */
+    architectChanged: boolean;
+    /** Whether _crossRefs declaration changed. */
+    crossRefsChanged: boolean;
+    /** architectEvery config value. */
+    architectEvery: number;
+}
+/**
+ * Derive _phaseState from existing meta fields.
+ *
+ * If the meta already has _phaseState, returns it as-is.
+ *
+ * Otherwise, reconstructs from available fields:
+ * - Never-synthesized meta (no _content, no _builder): all phases start pending/stale.
+ * - Errored meta: the failed phase is mapped from _error.step.
+ * - Mid-cycle meta with cached _builder but no _content: builder pending.
+ * - Fully-fresh meta: all phases fresh.
+ * - Meta with stale architect inputs: architect pending, downstream stale.
+ *
+ * @param meta - The meta.json content.
+ * @param inputs - Optional derivation inputs. If not provided, a simpler
+ *   heuristic is used (no architect invalidation check).
+ * @returns The derived PhaseState.
+ */
+export declare function derivePhaseState(meta: MetaJson, inputs?: DerivationInputs): PhaseState;

package/dist/phaseState/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Phase-state machine module.
+ *
+ * @module phaseState
+ */
+export { type DerivationInputs, derivePhaseState } from './derivePhaseState.js';
+export { type ArchitectInvalidator, computeInvalidation, type InvalidationResult, type StalenessInputs, } from './invalidate.js';
+export { buildPhaseCandidates, type PhaseCandidate, type PhaseCandidateInput, rankPhaseCandidates, selectPhaseCandidate, } from './phaseScheduler.js';
+export { architectSuccess, builderSuccess, criticSuccess, enforceInvariant, freshPhaseState, getOwedPhase, getPriorityBand, initialPhaseState, invalidateArchitect, invalidateBuilder, isFullyFresh, phaseFailed, phaseRunning, retryAllFailed, retryPhase, } from './phaseTransitions.js';

package/dist/phaseState/invalidate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-tick invalidation pass.
+ *
+ * Computes architect-invalidating and builder-invalidating inputs for a meta,
+ * then applies the cascade to update _phaseState.
+ *
+ * @module phaseState/invalidate
+ */
+import type { MetaNode } from '../discovery/types.js';
+import type { MetaConfig, MetaJson, PhaseState } from '../schema/index.js';
+/** Architect-level invalidation reasons. */
+export type ArchitectInvalidator = 'structureHash' | 'steer' | '_architect' | '_crossRefs' | 'architectEvery';
+/** Staleness inputs for a meta (exposed in /preview). */
+export interface StalenessInputs {
+    structureHash: string;
+    steerChanged: boolean;
+    architectChanged: boolean;
+    crossRefsDeclChanged: boolean;
+    scopeMtimeMax: string | null;
+    crossRefContentChanged: boolean;
+}
+/** Result of computing invalidation for a single meta. */
+export interface InvalidationResult {
+    phaseState: PhaseState;
+    architectInvalidators: ArchitectInvalidator[];
+    stalenessInputs: StalenessInputs;
+    structureHash: string;
+    steerChanged: boolean;
+}
+/**
+ * Compute invalidation inputs and apply cascade for a single meta.
+ *
+ * @param meta - Current meta.json content with existing _phaseState.
+ * @param scopeFiles - Sorted file list from scope.
+ * @param config - MetaConfig for architectEvery.
+ * @param node - MetaNode for archive access.
+ * @param crossRefMetas - Map of cross-ref owner paths to their current _content.
+ * @param archiveCrossRefContent - Map of cross-ref owner paths to their archived _content.
+ * @returns Updated phase state and invalidation details.
+ */
+export declare function computeInvalidation(meta: MetaJson, scopeFiles: string[], config: MetaConfig, node: MetaNode, crossRefMetas?: Map<string, string | undefined>, archiveCrossRefContent?: Map<string, string | undefined>): Promise<InvalidationResult>;

package/dist/phaseState/phaseScheduler.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Corpus-wide phase scheduler.
+ *
+ * Selects the highest-priority ready phase across all metas.
+ * Priority: critic (band 1) \> builder (band 2) \> architect (band 3).
+ * Tiebreak within band: weighted staleness (§3.9).
+ *
+ * @module phaseState/phaseScheduler
+ */
+import type { MetaEntry } from '../discovery/listMetas.js';
+import type { MetaNode } from '../discovery/types.js';
+import type { MetaJson, PhaseName, PhaseState } from '../schema/index.js';
+/** Input for phase candidate selection (from listMetas entries). */
+export interface PhaseCandidateInput {
+    node: MetaNode;
+    meta: MetaJson;
+    phaseState: PhaseState;
+    actualStaleness: number;
+    locked: boolean;
+    disabled: boolean;
+    isOverride?: boolean;
+}
+/**
+ * Build phase candidates from listMetas entries.
+ *
+ * Derives phase state, auto-retries failed phases, and applies Tier 1
+ * cheap-invalidation (no I/O) for metas with persisted _phaseState.
+ * Used by orchestratePhase, queue route, and status route.
+ */
+export declare function buildPhaseCandidates(entries: MetaEntry[], architectEvery: number): PhaseCandidateInput[];
+/** A candidate for phase-level scheduling. */
+export interface PhaseCandidate {
+    node: MetaNode;
+    meta: MetaJson;
+    phaseState: PhaseState;
+    owedPhase: PhaseName;
+    band: 1 | 2 | 3;
+    actualStaleness: number;
+    effectiveStaleness: number;
+}
+/**
+ * Rank all eligible phase candidates by priority.
+ *
+ * Filters to pending phases, computes effective staleness, and sorts by
+ * band (ascending: critic first) then effective staleness (descending).
+ *
+ * Used by selectPhaseCandidate (returns first) and the queue route (returns all).
+ */
+export declare function rankPhaseCandidates(metas: PhaseCandidateInput[], depthWeight: number): PhaseCandidate[];
+/**
+ * Select the best phase candidate across the corpus.
+ *
+ * @param metas - Array of (node, meta, phaseState, stalenessSeconds) tuples.
+ * @param depthWeight - Config depthWeight for staleness tiebreak.
+ * @returns The winning candidate, or null if no phase is ready.
+ */
+export declare function selectPhaseCandidate(metas: PhaseCandidateInput[], depthWeight: number): PhaseCandidate | null;