@karmaniverous/jeeves-meta 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -39,7 +39,6 @@ declare function pruneArchive(metaPath: string, maxArchive: number): number;
 
 /** Zod schema for jeeves-meta configuration. */
 declare const synthConfigSchema: z.ZodObject<{
-    watchPaths: z.ZodArray<z.ZodString>;
     watcherUrl: z.ZodURL;
     gatewayUrl: z.ZodDefault<z.ZodURL>;
     gatewayApiKey: z.ZodOptional<z.ZodString>;
@@ -54,6 +53,12 @@ declare const synthConfigSchema: z.ZodObject<{
     defaultCritic: z.ZodString;
     skipUnchanged: z.ZodDefault<z.ZodBoolean>;
     batchSize: z.ZodDefault<z.ZodNumber>;
+    metaProperty: z.ZodDefault<z.ZodObject<{
+        domains: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    metaArchiveProperty: z.ZodDefault<z.ZodObject<{
+        domains: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Inferred type for jeeves-meta configuration. */
 type SynthConfig = z.infer<typeof synthConfigSchema>;
@@ -175,143 +180,6 @@ declare function loadSynthConfig(configPath: string): SynthConfig;
  */
 declare function resolveConfigPath(args: string[]): 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;
-/**
- * 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;
-
-/**
- * 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.
  *
@@ -467,6 +335,228 @@ interface WatcherClient {
     unregisterRules(source: string): Promise<void>;
 }
 
+/**
+ * Discover .meta/ directories via watcher scan.
+ *
+ * Replaces filesystem-based globMetas() with a watcher query
+ * that returns indexed .meta/meta.json points, filtered by domain.
+ *
+ * @module discovery/discoverMetas
+ */
+
+/**
+ * Build a Qdrant filter from config metaProperty.
+ *
+ * @param config - Synth config with metaProperty.
+ * @returns Qdrant filter object for scanning live metas.
+ */
+declare function buildMetaFilter(config: SynthConfig): Record<string, unknown>;
+/**
+ * Discover all .meta/ directories via watcher scan.
+ *
+ * Queries the watcher for indexed .meta/meta.json points using the
+ * configured domain filter. Returns deduplicated meta directory paths.
+ *
+ * @param config - Synth config (for domain filter).
+ * @param watcher - WatcherClient for scan queries.
+ * @returns Array of normalized .meta/ directory paths.
+ */
+declare function discoverMetas(config: SynthConfig, watcher: WatcherClient): Promise<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;
+/**
+ * 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;
+
+/**
+ * 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;
+/**
+ * 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;
+
+/**
+ * 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;
+
+/**
+ * SynthExecutor 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, 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:3000 */
+    gatewayUrl?: string;
+    /** API key for gateway authentication. */
+    apiKey?: string;
+    /** Polling interval in ms. Default: 5000. */
+    pollIntervalMs?: number;
+}
+/**
+ * SynthExecutor that spawns OpenClaw sessions via the gateway HTTP API.
+ *
+ * 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 `SynthConfig`.
+ */
+declare class GatewayExecutor implements SynthExecutor {
+    private readonly gatewayUrl;
+    private readonly apiKey;
+    private readonly pollIntervalMs;
+    constructor(options?: GatewayExecutorOptions);
+    spawn(task: string, options?: SynthSpawnOptions): Promise<SynthSpawnResult>;
+}
+
+/**
+ * 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;
+
+/**
+ * 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;
+
 /**
  * Build task prompts for each synthesis step.
  *
@@ -635,130 +725,10 @@ interface OrchestrateResult {
  * @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 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;
-
-/**
- * SynthExecutor 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, 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:3000 */
-    gatewayUrl?: string;
-    /** API key for gateway authentication. */
-    apiKey?: string;
-    /** Polling interval in ms. Default: 5000. */
-    pollIntervalMs?: number;
-}
-/**
- * SynthExecutor that spawns OpenClaw sessions via the gateway HTTP API.
- *
- * 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 `SynthConfig`.
- */
-declare class GatewayExecutor implements SynthExecutor {
-    private readonly gatewayUrl;
-    private readonly apiKey;
-    private readonly pollIntervalMs;
-    constructor(options?: GatewayExecutorOptions);
-    spawn(task: string, options?: SynthSpawnOptions): Promise<SynthSpawnResult>;
-}
-
-/**
- * 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;
-
-/**
- * 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;
+declare function orchestrate(config: SynthConfig, executor: SynthExecutor, watcher: WatcherClient, targetPath?: string): Promise<OrchestrateResult[]>;
 
 /**
  * Paginated scan helper for exhaustive scope enumeration.
@@ -925,5 +895,5 @@ declare class HttpWatcherClient implements WatcherClient {
     unregisterRules(source: string): Promise<void>;
 }
 
-export { GatewayExecutor, HttpWatcherClient, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildOwnershipTree, computeEffectiveStaleness, computeEma, computeStructureHash, createSnapshot, createSynthEngine, ensureMetaJson, filterInScope, findNode, getScopeExclusions, getScopePrefix, globMetas, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, loadSynthConfig, mergeAndWrite, metaJsonSchema, normalizePath, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, releaseLock, resolveConfigPath, selectCandidate, synthConfigSchema, synthErrorSchema, toSynthError };
-export type { BuilderOutput, GatewayExecutorOptions, HttpWatcherClientOptions, InferenceRuleSpec, MergeOptions, MetaJson, MetaNode, OrchestrateResult, OwnershipTree, ScanFile, ScanParams, ScanResponse, StalenessCandidate, SynthConfig, SynthContext, SynthEngine, SynthError, SynthExecutor, SynthSpawnOptions, SynthSpawnResult, WatcherClient };
+export { GatewayExecutor, HttpWatcherClient, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildMetaFilter, buildOwnershipTree, computeEffectiveStaleness, computeEma, computeStructureHash, createSnapshot, discoverMetas, filterInScope, findNode, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, loadSynthConfig, mergeAndWrite, metaJsonSchema, normalizePath, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, releaseLock, resolveConfigPath, selectCandidate, synthConfigSchema, synthErrorSchema, toSynthError };
+export type { BuilderOutput, GatewayExecutorOptions, HttpWatcherClientOptions, InferenceRuleSpec, MergeOptions, MetaJson, MetaNode, OrchestrateResult, OwnershipTree, ScanFile, ScanParams, ScanResponse, StalenessCandidate, SynthConfig, SynthContext, SynthError, SynthExecutor, SynthSpawnOptions, SynthSpawnResult, WatcherClient };