@karmaniverous/jeeves-meta 0.4.1 → 0.5.0

package/dist/index.d.ts

@@ -82,6 +82,7 @@ declare const serviceConfigSchema: z.ZodObject<{
     port: z.ZodDefault<z.ZodNumber>;
     schedule: z.ZodDefault<z.ZodString>;
     reportChannel: z.ZodOptional<z.ZodString>;
+    watcherHealthIntervalMs: z.ZodDefault<z.ZodNumber>;
     logging: z.ZodDefault<z.ZodObject<{
         level: z.ZodDefault<z.ZodString>;
         file: z.ZodOptional<z.ZodString>;
@@ -185,6 +186,20 @@ declare function readLatestArchive(metaPath: string): MetaJson | null;
  */
 declare function createSnapshot(metaPath: string, meta: MetaJson): string;
 
+/**
+ * Shared constants for the jeeves-meta service package.
+ *
+ * @module constants
+ */
+/** Default HTTP port for the jeeves-meta service. */
+declare const DEFAULT_PORT = 1938;
+/** Default port as a string (for Commander CLI defaults). */
+declare const DEFAULT_PORT_STR: string;
+/** Service name identifier. */
+declare const SERVICE_NAME = "jeeves-meta";
+/** Service version, read from package.json at startup. */
+declare const SERVICE_VERSION: string;
+
 /**
  * Load and resolve jeeves-meta service config.
  *
@@ -224,7 +239,7 @@ declare function loadServiceConfig(configPath: string): ServiceConfig;
  * 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.
+ * ownership tree, watcher walk results, and filesystem reads.
  */
 interface MetaContext {
     /** Absolute path to the .meta directory. */
@@ -289,45 +304,11 @@ interface MetaExecutor {
 /**
  * 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.
+ * The service uses this for filesystem enumeration (POST /walk)
+ * and virtual rule registration (POST /rules/register).
  *
  * @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 {
-    /** File path prefix to match. Required unless filter is provided. */
-    pathPrefix?: string;
-    /** Qdrant filter object for structural queries. */
-    filter?: Record<string, unknown>;
-    /** 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. */
@@ -351,11 +332,6 @@ interface InferenceRuleSpec {
  * 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.
      *
@@ -364,72 +340,33 @@ interface WatcherClient {
      */
     registerRules(source: string, rules: InferenceRuleSpec[]): Promise<void>;
     /**
-     * Unregister virtual inference rules by source.
+     * Walk filesystem using glob patterns.
      *
-     * @param source - Source identifier to unregister.
+     * @param globs - Array of glob patterns to match against.
+     * @returns Promise resolving to array of matching file paths.
      */
-    unregisterRules(source: string): Promise<void>;
-}
-
-/**
- * Pino logger factory.
- *
- * @module logger
- */
-
-/** Minimal logger interface accepted by library functions. */
-interface MinimalLogger {
-    debug: (obj: Record<string, unknown>, msg: string) => void;
-    info: (obj: Record<string, unknown>, msg: string) => void;
-    warn: (obj: Record<string, unknown>, msg: string) => void;
-    error: (obj: Record<string, unknown>, msg: string) => void;
+    walk(globs: string[]): Promise<string[]>;
 }
-/** Logger configuration options. */
-interface LoggerConfig {
-    /** Log level (default: 'info'). */
-    level?: string;
-    /** Optional file path to write logs to. */
-    file?: string;
-}
-/**
- * Create a pino logger instance.
- *
- * @param config - Optional logger configuration.
- * @returns Configured pino logger.
- */
-declare function createLogger(config?: LoggerConfig): pino.Logger;
 
 /**
- * Discover .meta/ directories via watcher scan.
+ * Discover .meta/ directories via watcher `/walk` endpoint.
  *
- * Replaces filesystem-based globMetas() with a watcher query
- * that returns indexed .meta/meta.json points, filtered by domain.
+ * Uses filesystem enumeration through the watcher (not Qdrant) to find
+ * all `.meta/meta.json` files and returns deduplicated meta directory paths.
  *
  * @module discovery/discoverMetas
  */
 
 /**
- * Build a Qdrant filter from config metaProperty.
+ * Discover all .meta/ directories via watcher walk.
  *
- * Iterates all key-value pairs in `metaProperty` (a generic record)
- * to construct `must` clauses. Always appends `file_path: meta.json`
- * for deduplication.
+ * Uses the watcher's `/walk` endpoint to find all `.meta/meta.json` files
+ * and returns deduplicated meta directory paths.
  *
- * @param config - Meta config with metaProperty.
- * @returns Qdrant filter object for scanning live metas.
- */
-declare function buildMetaFilter(config: MetaConfig): 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 - Meta config (for domain filter).
- * @param watcher - WatcherClient for scan queries.
+ * @param watcher - WatcherClient for walk queries.
  * @returns Array of normalized .meta/ directory paths.
  */
-declare function discoverMetas(config: MetaConfig, watcher: WatcherClient, logger?: MinimalLogger): Promise<string[]>;
+declare function discoverMetas(watcher: WatcherClient): Promise<string[]>;
 
 /**
  * Types for meta discovery and ownership tree.
@@ -529,7 +466,7 @@ interface MetaListResult {
  * @param watcher - Watcher HTTP client for discovery.
  * @returns Enriched meta list with summary statistics and ownership tree.
  */
-declare function listMetas(config: MetaConfig, watcher: WatcherClient, logger?: MinimalLogger): Promise<MetaListResult>;
+declare function listMetas(config: MetaConfig, watcher: WatcherClient): Promise<MetaListResult>;
 
 /**
  * Build the ownership tree from discovered .meta/ paths.
@@ -564,7 +501,7 @@ declare function findNode(tree: OwnershipTree, targetPath: string): MetaNode | u
  * - Its own .meta/ subtree (outputs, not inputs)
  * - Child meta ownerPath subtrees (except their .meta/meta.json for rollups)
  *
- * Uses filesystem walks instead of watcher scans for performance.
+ * All filesystem enumeration delegated to the watcher's `/walk` endpoint.
  *
  * @module discovery/scope
  */
@@ -580,7 +517,7 @@ declare function getScopePrefix(node: MetaNode): string;
  * - The node's own .meta/ subtree (synthesis outputs are not scope inputs)
  * - Child meta ownerPath subtrees (except child .meta/meta.json for rollups)
  *
- * walkFiles already returns normalized forward-slash paths.
+ * Watcher walk returns normalized forward-slash paths.
  */
 declare function filterInScope(node: MetaNode, files: string[]): string[];
 
@@ -703,21 +640,6 @@ declare function cleanupStaleLocks(metaPaths: string[], logger?: {
  */
 declare function normalizePath(p: string): string;
 
-/**
- * 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'>, logger?: MinimalLogger): Promise<ScanFile[]>;
-
 /**
  * Compute a structure hash from a sorted file listing.
  *
@@ -734,32 +656,6 @@ declare function paginatedScan(watcher: WatcherClient, params: Omit<ScanParams,
  */
 declare function computeStructureHash(filePaths: string[]): string;
 
-/**
- * Recursive filesystem walker for file enumeration.
- *
- * Replaces paginated watcher scans for scope/delta/staleness checks.
- * Returns normalized forward-slash paths.
- *
- * @module walkFiles
- */
-/** Options for walkFiles. */
-interface WalkFilesOptions {
-    /** Directory names to exclude (in addition to defaults). */
-    exclude?: string[];
-    /** Only include files modified after this Unix timestamp (seconds). */
-    modifiedAfter?: number;
-    /** Maximum recursion depth. Default: 50. */
-    maxDepth?: number;
-}
-/**
- * Recursively walk a directory and return all file paths.
- *
- * @param root - Root directory to walk.
- * @param options - Walk options.
- * @returns Array of normalized file paths.
- */
-declare function walkFiles(root: string, options?: WalkFilesOptions): string[];
-
 /**
  * MetaExecutor implementation using the OpenClaw gateway HTTP API.
  *
@@ -778,7 +674,7 @@ interface GatewayExecutorOptions {
     apiKey?: string;
     /** Polling interval in ms. Default: 5000. */
     pollIntervalMs?: number;
-    /** Workspace directory for output staging. Default: J:\\jeeves\\jeeves-meta */
+    /** Workspace directory for output staging. Default: OS temp dir + /jeeves-meta. */
     workspaceDir?: string;
 }
 /**
@@ -802,6 +698,34 @@ declare class GatewayExecutor implements MetaExecutor {
     spawn(task: string, options?: MetaSpawnOptions): Promise<MetaSpawnResult>;
 }
 
+/**
+ * Pino logger factory.
+ *
+ * @module logger
+ */
+
+/** Minimal logger interface accepted by library functions. */
+interface MinimalLogger {
+    debug: (obj: Record<string, unknown>, msg: string) => void;
+    info: (obj: Record<string, unknown>, msg: string) => void;
+    warn: (obj: Record<string, unknown>, msg: string) => void;
+    error: (obj: Record<string, unknown>, msg: string) => void;
+}
+/** Logger configuration options. */
+interface LoggerConfig {
+    /** Log level (default: 'info'). */
+    level?: string;
+    /** Optional file path to write logs to. */
+    file?: string;
+}
+/**
+ * Create a pino logger instance.
+ *
+ * @param config - Optional logger configuration.
+ * @returns Configured pino logger.
+ */
+declare function createLogger(config?: LoggerConfig): pino.Logger;
+
 /**
  * Build task prompts for each synthesis step.
  *
@@ -853,7 +777,7 @@ declare function buildCriticTask(ctx: MetaContext, meta: MetaJson, config: MetaC
  * @param watcher - WatcherClient for scope enumeration.
  * @returns The computed context package.
  */
-declare function buildContextPackage(node: MetaNode, meta: MetaJson): MetaContext;
+declare function buildContextPackage(node: MetaNode, meta: MetaJson, watcher: WatcherClient): Promise<MetaContext>;
 
 /**
  * Parse subprocess outputs for each synthesis step.
@@ -1064,22 +988,27 @@ declare function computeEffectiveStaleness(candidates: Array<{
 declare function selectCandidate(candidates: StalenessCandidate[]): StalenessCandidate | null;
 
 /**
- * Staleness detection via watcher scan.
+ * Staleness detection via watcher walk.
  *
- * A meta is stale when any file in its scope was modified after _generatedAt.
+ * A meta is stale when any watched file in its scope was modified after
+ * `_generatedAt`.
  *
  * @module scheduling/staleness
  */
 
 /**
- * Check if a meta is stale by querying the watcher for modified files.
+ * Check if a meta is stale.
+ *
+ * Uses watcher `/walk` to enumerate watched files under the scope prefix,
+ * then applies a local mtime check (fast) to detect any modifications since
+ * `_generatedAt`. Short-circuits on first match.
  *
  * @param scopePrefix - Path prefix for this meta's scope.
  * @param meta - Current meta.json content.
  * @param watcher - WatcherClient instance.
- * @returns True if any file in scope was modified after _generatedAt.
+ * @returns True if any file in scope was modified after `_generatedAt`.
  */
-declare function isStale(scopePrefix: string, meta: MetaJson): boolean;
+declare function isStale(scopePrefix: string, meta: MetaJson, watcher: WatcherClient): Promise<boolean>;
 /**
  * Compute actual staleness in seconds (now minus _generatedAt).
  *
@@ -1258,7 +1187,7 @@ declare class RuleRegistrar {
 /**
  * HTTP implementation of the WatcherClient interface.
  *
- * Talks to jeeves-watcher's POST /scan and POST /rules endpoints
+ * Talks to jeeves-watcher's POST /walk and POST /rules/register endpoints
  * with retry and exponential backoff.
  *
  * @module watcher-client/HttpWatcherClient
@@ -1289,9 +1218,8 @@ declare class HttpWatcherClient implements WatcherClient {
     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>;
+    walk(globs: string[]): Promise<string[]>;
 }
 
 /**
@@ -1367,6 +1295,8 @@ interface RouteDeps {
     watcher: HttpWatcherClient;
     scheduler: Scheduler | null;
     stats: ServiceStats;
+    /** Rule registrar for reporting registration state in /status. */
+    registrar?: RuleRegistrar;
     /** Set to true during graceful shutdown. */
     shuttingDown?: boolean;
 }
@@ -1417,6 +1347,8 @@ interface ShutdownDeps {
     queue: SynthesisQueue;
     logger: Logger;
     routeDeps?: RouteDeps;
+    /** Optional cleanup callback (e.g., stop health check). */
+    onShutdown?: () => void;
 }
 /**
  * Register shutdown handlers for SIGTERM and SIGINT.
@@ -1445,5 +1377,5 @@ declare function registerShutdownHandlers(deps: ShutdownDeps): void;
  */
 declare function startService(config: ServiceConfig, configPath?: string): Promise<void>;
 
-export { GatewayExecutor, HttpWatcherClient, ProgressReporter, RuleRegistrar, Scheduler, SynthesisQueue, acquireLock, actualStaleness, buildArchitectTask, buildBuilderTask, buildContextPackage, buildCriticTask, buildMetaFilter, buildOwnershipTree, cleanupStaleLocks, computeEffectiveStaleness, computeEma, computeStructureHash, createLogger, createServer, createSnapshot, discoverMetas, filterInScope, findNode, formatProgressEvent, getScopePrefix, hasSteerChanged, isArchitectTriggered, isLocked, isStale, listArchiveFiles, listMetas, loadServiceConfig, mergeAndWrite, metaConfigSchema, metaErrorSchema, metaJsonSchema, normalizePath, orchestrate, paginatedScan, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, selectCandidate, serviceConfigSchema, sleep, startService, toMetaError, walkFiles };
-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, ScanFile, ScanParams, ScanResponse, ServerOptions, ServiceConfig, ServiceStats, StalenessCandidate, WatcherClient };
+export { DEFAULT_PORT, DEFAULT_PORT_STR, GatewayExecutor, HttpWatcherClient, ProgressReporter, 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, metaErrorSchema, metaJsonSchema, normalizePath, orchestrate, parseArchitectOutput, parseBuilderOutput, parseCriticOutput, pruneArchive, readLatestArchive, readLockState, registerRoutes, registerShutdownHandlers, releaseLock, resolveConfigPath, resolveMetaDir, selectCandidate, serviceConfigSchema, sleep, startService, toMetaError };
+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 };