@karmaniverous/jeeves-meta 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,825 @@
+import { z } from 'zod';
+
+/**
+ * List archive snapshot files in chronological order.
+ *
+ * @module archive/listArchive
+ */
+/**
+ * List archive .json files sorted chronologically (oldest first).
+ *
+ * @param metaPath - Absolute path to the .meta directory.
+ * @returns Array of absolute paths to archive files, or empty if none.
+ */
+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): number;
+
+/**
+ * Zod schema for jeeves-meta configuration.
+ *
+ * Consumers load config however they want (file, env, constructor).
+ * The library validates via this schema.
+ *
+ * @module schema/config
+ */
+
+/** Zod schema for jeeves-meta configuration. */
+declare const synthConfigSchema: z.ZodObject<{
+    watchPaths: z.ZodArray<z.ZodString>;
+    watcherUrl: z.ZodURL;
+    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>;
+    defaultArchitect: z.ZodString;
+    defaultCritic: z.ZodString;
+    skipUnchanged: z.ZodDefault<z.ZodBoolean>;
+    batchSize: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** Inferred type for jeeves-meta configuration. */
+type SynthConfig = z.infer<typeof synthConfigSchema>;
+
+/**
+ * Structured error from a synthesis step failure.
+ *
+ * @module schema/error
+ */
+
+/** Zod schema for synthesis step errors. */
+declare const synthErrorSchema: 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 SynthError = z.infer<typeof synthErrorSchema>;
+
+/**
+ * Zod schema for .meta/meta.json files.
+ *
+ * Reserved properties are underscore-prefixed and engine-managed.
+ * All other keys are open schema (builder output).
+ *
+ * @module schema/meta
+ */
+
+/** Zod schema for the reserved (underscore-prefixed) meta.json properties. */
+declare const metaJsonSchema: z.ZodObject<{
+    _id: z.ZodUUID;
+    _steer: z.ZodOptional<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>;
+    _error: z.ZodOptional<z.ZodObject<{
+        step: z.ZodEnum<{
+            architect: "architect";
+            builder: "builder";
+            critic: "critic";
+        }>;
+        code: z.ZodString;
+        message: z.ZodString;
+    }, 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): 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): string;
+
+/**
+ * Ensure meta.json exists in each .meta/ directory.
+ *
+ * If meta.json is missing, creates it with a generated UUID.
+ *
+ * @module discovery/ensureMetaJson
+ */
+
+/**
+ * Ensure meta.json exists at the given .meta/ path.
+ *
+ * @param metaPath - Absolute path to a .meta/ directory.
+ * @returns The meta.json content (existing or newly created).
+ */
+declare function ensureMetaJson(metaPath: string): MetaJson;
+
+/**
+ * Glob watchPaths for .meta/ directories.
+ *
+ * Walks each watchPath recursively, collecting directories named '.meta'
+ * that contain (or will contain) a meta.json file.
+ *
+ * @module discovery/globMetas
+ */
+/**
+ * Recursively find all .meta/ directories under the given paths.
+ *
+ * @param watchPaths - Root directories to search.
+ * @returns Array of absolute paths to .meta/ directories.
+ */
+declare function globMetas(watchPaths: string[]): string[];
+
+/**
+ * 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[];
+}
+
+/**
+ * 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;
+
+/**
+ * Compute the file scope owned by a meta node.
+ *
+ * A meta owns: parent dir + all descendants, minus child .meta/ subtrees.
+ * For child subtrees, it consumes the child's .meta/meta.json as a rollup input.
+ *
+ * @module discovery/scope
+ */
+
+/**
+ * Get the scope path prefix for a meta node.
+ *
+ * This is the ownerPath — all files under this path are in scope,
+ * except subtrees owned by child metas.
+ *
+ * @param node - The meta node to compute scope for.
+ * @returns The scope path prefix.
+ */
+declare function getScopePrefix(node: MetaNode): string;
+/**
+ * Get paths that should be excluded from the scope (child meta subtrees).
+ *
+ * @param node - The meta node to compute exclusions for.
+ * @returns Array of path prefixes to exclude from scope queries.
+ */
+declare function getScopeExclusions(node: MetaNode): string[];
+/**
+ * Filter a list of file paths to only those in scope for a meta node.
+ *
+ * Includes files under ownerPath, excludes files under child meta ownerPaths,
+ * but includes child .meta/meta.json files as rollup inputs.
+ *
+ * @param node - The meta node.
+ * @param files - Array of file paths to filter.
+ * @returns Filtered array of in-scope file paths.
+ */
+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;
+
+/**
+ * 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/SynthContext
+ */
+/**
+ * Context package for a single synthesis cycle.
+ *
+ * The orchestrator computes this once per cycle from the meta path,
+ * ownership tree, watcher scan results, and filesystem reads.
+ */
+interface SynthContext {
+    /** 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>;
+    /** _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;
+    /** Archive snapshot file paths (for steer change detection, etc.). */
+    archives: string[];
+}
+
+/**
+ * Pluggable executor interface for LLM subprocess invocation.
+ *
+ * @module interfaces/SynthExecutor
+ */
+/** Options for spawning a synthesis subprocess. */
+interface SynthSpawnOptions {
+    /** Model override for this subprocess. */
+    model?: string;
+    /** Timeout in seconds. */
+    timeout?: number;
+}
+/** Result of a spawn call, including optional token usage. */
+interface SynthSpawnResult {
+    /** 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 SynthExecutor {
+    /**
+     * 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?: SynthSpawnOptions): Promise<SynthSpawnResult>;
+}
+
+/**
+ * Abstraction over the jeeves-watcher HTTP API.
+ *
+ * The orchestrator uses this for structured queries (POST /scan)
+ * and virtual rule registration. Subprocesses use watcher_search
+ * directly via tools.
+ *
+ * @module interfaces/WatcherClient
+ */
+/** A file returned from a scan query. */
+interface ScanFile {
+    /** Absolute file path. */
+    file_path: string;
+    /** Last modified time as Unix seconds. */
+    modified_at: number;
+    /** SHA-256 hash of file content. */
+    content_hash: string;
+    /** Additional payload fields requested via `fields`. */
+    [key: string]: unknown;
+}
+/** Parameters for a scan request. */
+interface ScanParams {
+    /** Required file path prefix to match. */
+    pathPrefix: string;
+    /** Filter files modified after this Unix timestamp (seconds). */
+    modifiedAfter?: number;
+    /** Which payload fields to return (default: all). */
+    fields?: string[];
+    /** Maximum results per page. */
+    limit?: number;
+    /** Pagination cursor from previous response. */
+    cursor?: string;
+}
+/** Response from a scan request. */
+interface ScanResponse {
+    /** Deduplicated file results (one per file). */
+    files: ScanFile[];
+    /** Pagination cursor. Absent when no more results. */
+    next?: string;
+}
+/** 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;
+}
+/**
+ * Interface for watcher HTTP operations.
+ *
+ * Implementations handle retry with backoff internally.
+ */
+interface WatcherClient {
+    /**
+     * Query indexed files by path prefix and optional filters.
+     * Qdrant has no native prefix match; the watcher handles this internally.
+     */
+    scan(params: ScanParams): Promise<ScanResponse>;
+    /**
+     * 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>;
+    /**
+     * Unregister virtual inference rules by source.
+     *
+     * @param source - Source identifier to unregister.
+     */
+    unregisterRules(source: string): Promise<void>;
+}
+
+/**
+ * Build task prompts for each synthesis step.
+ *
+ * @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: SynthContext, meta: MetaJson, config: SynthConfig): 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: SynthContext, meta: MetaJson, config: SynthConfig): 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: SynthContext, meta: MetaJson, config: SynthConfig): string;
+
+/**
+ * Build the SynthContext for a synthesis cycle.
+ *
+ * Computes shared inputs once: scope files, delta files, child meta outputs,
+ * previous content/feedback, steer, and archive paths.
+ *
+ * @module orchestrator/contextPackage
+ */
+
+/**
+ * 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): Promise<SynthContext>;
+
+/**
+ * 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>;
+}
+/**
+ * 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: SynthError | null;
+    /** Token count from architect step. */
+    architectTokens?: number;
+    /** Token count from builder step. */
+    builderTokens?: number;
+    /** Token count from critic step. */
+    criticTokens?: number;
+}
+/**
+ * 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): MetaJson;
+
+/**
+ * Main orchestration function — the 13-step synthesis cycle.
+ *
+ * Wires together discovery, scheduling, archiving, executor calls,
+ * and merge/write-back.
+ *
+ * @module orchestrator/orchestrate
+ */
+
+/** 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?: SynthError;
+}
+/**
+ * Run synthesis cycles up to batchSize.
+ *
+ * Calls orchestrateOnce() in a loop, stopping when batchSize is reached
+ * or no more candidates are available.
+ *
+ * @param config - Validated synthesis config.
+ * @param executor - Pluggable LLM executor.
+ * @param watcher - Watcher HTTP client.
+ * @returns Array of results, one per cycle attempted.
+ */
+declare function orchestrate(config: SynthConfig, executor: SynthExecutor, watcher: WatcherClient): Promise<OrchestrateResult[]>;
+
+/**
+ * Factory for creating a bound synthesis engine.
+ *
+ * @module engine
+ */
+
+/** A bound synthesis engine instance. */
+interface SynthEngine {
+    /** Run synthesis cycles up to batchSize. */
+    synthesize(): Promise<OrchestrateResult[]>;
+    /** Run synthesis targeting a specific path. */
+    synthesizePath(ownerPath: string): Promise<OrchestrateResult[]>;
+    /** The bound config. */
+    readonly config: SynthConfig;
+}
+/**
+ * Create a synthesis engine with bound config, executor, and watcher client.
+ *
+ * @param config - Validated synthesis config.
+ * @param executor - Pluggable LLM executor.
+ * @param watcher - Watcher HTTP client.
+ * @returns A bound engine instance.
+ */
+declare function createSynthEngine(config: SynthConfig, executor: SynthExecutor, watcher: WatcherClient): SynthEngine;
+
+/**
+ * Shared error utilities.
+ *
+ * @module errors
+ */
+
+/**
+ * Wrap an unknown caught value into a SynthError.
+ *
+ * @param step - Which synthesis step failed.
+ * @param err - The caught error value.
+ * @param code - Error classification code.
+ * @returns A structured SynthError.
+ */
+declare function toSynthError(step: SynthError['step'], err: unknown, code?: string): SynthError;
+
+/**
+ * File-system lock for preventing concurrent synthesis on the same meta.
+ *
+ * Lock file: .meta/.lock containing PID + timestamp.
+ * Stale timeout: 30 minutes.
+ *
+ * @module lock
+ */
+/**
+ * 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;
+
+/**
+ * Paginated scan helper for exhaustive scope enumeration.
+ *
+ * @module paginatedScan
+ */
+
+/**
+ * Perform a paginated scan that follows cursor tokens until exhausted.
+ *
+ * @param watcher - WatcherClient instance.
+ * @param params - Base scan parameters (cursor is managed internally).
+ * @returns All matching files across all pages.
+ */
+declare function paginatedScan(watcher: WatcherClient, params: Omit<ScanParams, 'cursor'>): Promise<ScanFile[]>;
+
+/**
+ * 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 scan.
+ *
+ * A meta is stale when any file in its scope was modified after _generatedAt.
+ *
+ * @module scheduling/staleness
+ */
+
+/**
+ * Check if a meta is stale by querying the watcher for modified files.
+ *
+ * @param scopePrefix - Path prefix for this meta's scope.
+ * @param meta - Current meta.json content.
+ * @param watcher - WatcherClient instance.
+ * @returns True if any file in scope was modified after _generatedAt.
+ */
+declare function isStale(scopePrefix: string, meta: MetaJson, watcher: WatcherClient): Promise<boolean>;
+/**
+ * Compute actual staleness in seconds (now minus _generatedAt).
+ *
+ * @param meta - Current meta.json content.
+ * @returns Staleness in seconds, or Infinity if never synthesized.
+ */
+declare function actualStaleness(meta: MetaJson): number;
+
+/**
+ * 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;
+
+/**
+ * HTTP implementation of the WatcherClient interface.
+ *
+ * Talks to jeeves-watcher's POST /scan and POST /rules endpoints
+ * with retry and exponential backoff.
+ *
+ * @module watcher-client/HttpWatcherClient
+ */
+
+/** 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;
+}
+/**
+ * HTTP-based WatcherClient implementation with retry.
+ */
+declare class HttpWatcherClient implements WatcherClient {
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly backoffBaseMs;
+    private readonly backoffFactor;
+    constructor(options: HttpWatcherClientOptions);
+    /** POST JSON with retry. */
+    private post;
+    scan(params: ScanParams): Promise<ScanResponse>;
+    registerRules(source: string, rules: InferenceRuleSpec[]): Promise<void>;
+    unregisterRules(source: string): Promise<void>;
+}
+
+export { HttpWatcherClient, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildOwnershipTree, computeEffectiveStaleness, computeEma, computeStructureHash, createSnapshot, createSynthEngine, ensureMetaJson, filterInScope, getScopeExclusions, getScopePrefix, globMetas, isLocked, isStale, listArchiveFiles, mergeAndWrite, metaJsonSchema, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, releaseLock, selectCandidate, synthConfigSchema, synthErrorSchema, toSynthError };
+export type { BuilderOutput, HttpWatcherClientOptions, InferenceRuleSpec, MergeOptions, MetaJson, MetaNode, OrchestrateResult, OwnershipTree, ScanFile, ScanParams, ScanResponse, StalenessCandidate, SynthConfig, SynthContext, SynthEngine, SynthError, SynthExecutor, SynthSpawnOptions, SynthSpawnResult, WatcherClient };