@karmaniverous/jeeves-meta 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -30,7 +30,7 @@ declare function listArchiveFiles(metaPath: string): string[];
  * @param maxArchive - Maximum snapshots to retain.
  * @returns Number of files pruned.
  */
-declare function pruneArchive(metaPath: string, maxArchive: number): number;
+declare function pruneArchive(metaPath: string, maxArchive: number): Promise<number>;
 
 /**
  * Zod schema for jeeves-meta service configuration.
@@ -89,6 +89,11 @@ declare const serviceConfigSchema: z.ZodObject<{
         level: z.ZodDefault<z.ZodString>;
         file: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    autoSeed: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        match: z.ZodString;
+        steer: z.ZodOptional<z.ZodString>;
+        crossRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>>;
 }, z.core.$strip>;
 /** Inferred type for service configuration. */
 type ServiceConfig = z.infer<typeof serviceConfigSchema>;
@@ -123,8 +128,9 @@ type MetaError = z.infer<typeof metaErrorSchema>;
 
 /** Zod schema for the reserved (underscore-prefixed) meta.json properties. */
 declare const metaJsonSchema: z.ZodObject<{
-    _id: z.ZodUUID;
+    _id: z.ZodOptional<z.ZodUUID>;
     _steer: z.ZodOptional<z.ZodString>;
+    _crossRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     _architect: z.ZodOptional<z.ZodString>;
     _builder: z.ZodOptional<z.ZodString>;
     _critic: z.ZodOptional<z.ZodString>;
@@ -169,7 +175,7 @@ type MetaJson = z.infer<typeof metaJsonSchema>;
  * @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;
+declare function readLatestArchive(metaPath: string): Promise<MetaJson | null>;
 
 /**
  * Create archive snapshots of meta.json.
@@ -187,7 +193,7 @@ declare function readLatestArchive(metaPath: string): MetaJson | null;
  * @param meta - Current meta.json content.
  * @returns The archive file path.
  */
-declare function createSnapshot(metaPath: string, meta: MetaJson): string;
+declare function createSnapshot(metaPath: string, meta: MetaJson): Promise<string>;
 
 /**
  * Shared constants for the jeeves-meta service package.
@@ -253,6 +259,8 @@ interface MetaContext {
     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. */
@@ -353,26 +361,6 @@ interface WatcherClient {
     walk(globs: string[]): Promise<string[]>;
 }
 
-/**
- * Discover .meta/ directories via watcher `/walk` endpoint.
- *
- * Uses filesystem enumeration through the watcher (not Qdrant) to find
- * all `.meta/meta.json` files and returns deduplicated meta directory paths.
- *
- * @module discovery/discoverMetas
- */
-
-/**
- * Discover all .meta/ directories via watcher walk.
- *
- * Uses the watcher's `/walk` endpoint to find all `.meta/meta.json` files
- * and returns deduplicated meta directory paths.
- *
- * @param watcher - WatcherClient for walk queries.
- * @returns Array of normalized .meta/ directory paths.
- */
-declare function discoverMetas(watcher: WatcherClient): Promise<string[]>;
-
 /**
  * Types for meta discovery and ownership tree.
  *
@@ -473,6 +461,26 @@ interface MetaListResult {
  */
 declare function listMetas(config: MetaConfig, watcher: WatcherClient): Promise<MetaListResult>;
 
+/**
+ * Discover .meta/ directories via watcher `/walk` endpoint.
+ *
+ * Uses filesystem enumeration through the watcher (not Qdrant) to find
+ * all `.meta/meta.json` files and returns deduplicated meta directory paths.
+ *
+ * @module discovery/discoverMetas
+ */
+
+/**
+ * Discover all .meta/ directories via watcher walk.
+ *
+ * Uses the watcher's `/walk` endpoint to find all `.meta/meta.json` files
+ * and returns deduplicated meta directory paths.
+ *
+ * @param watcher - WatcherClient for walk queries.
+ * @returns Array of normalized .meta/ directory paths.
+ */
+declare function discoverMetas(watcher: WatcherClient): Promise<string[]>;
+
 /**
  * Build the ownership tree from discovered .meta/ paths.
  *
@@ -499,6 +507,34 @@ declare function buildOwnershipTree(metaPaths: string[]): OwnershipTree;
  */
 declare function findNode(tree: OwnershipTree, targetPath: string): MetaNode | undefined;
 
+/**
+ * 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;
+
 /**
  * Compute the file scope owned by a meta node.
  *
@@ -703,34 +739,6 @@ 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.
  *
@@ -782,7 +790,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, watcher: WatcherClient): Promise<MetaContext>;
+declare function buildContextPackage(node: MetaNode, meta: MetaJson, watcher: WatcherClient, logger?: MinimalLogger): Promise<MetaContext>;
 
 /**
  * Parse subprocess outputs for each synthesis step.
@@ -881,7 +889,7 @@ interface MergeOptions {
  * @returns The updated MetaJson.
  * @throws If validation fails (malformed output).
  */
-declare function mergeAndWrite(options: MergeOptions): MetaJson;
+declare function mergeAndWrite(options: MergeOptions): Promise<MetaJson>;
 
 /**
  * Progress reporting via OpenClaw gateway `/tools/invoke` → `message` tool.
@@ -1316,6 +1324,28 @@ interface RouteDeps {
 /** Register all HTTP routes on the Fastify instance. */
 declare function registerRoutes(app: FastifyInstance, deps: RouteDeps): void;
 
+/**
+ * Post-registration verification of virtual rule application.
+ *
+ * After rules are registered with the watcher, verifies that .meta/meta.json
+ * files are discoverable via watcher walk (which depends on virtual rules
+ * being applied). Logs a warning if expected metas are not found.
+ *
+ * @module rules/verify
+ */
+
+/**
+ * Verify that virtual rules are applied to indexed .meta/meta.json files.
+ *
+ * Runs a discovery pass and logs the result. If no metas are found but
+ * the filesystem likely has some, logs a warning suggesting reindex.
+ *
+ * @param watcher - WatcherClient for discovery.
+ * @param logger - Logger for reporting results.
+ * @returns Number of metas discovered.
+ */
+declare function verifyRuleApplication(watcher: WatcherClient, logger: MinimalLogger): Promise<number>;
+
 /** Sleep for a given number of milliseconds. */
 declare function sleep(ms: number): Promise<void>;
 
@@ -1382,5 +1412,5 @@ declare function registerShutdownHandlers(deps: ShutdownDeps): void;
  */
 declare function startService(config: ServiceConfig, configPath?: string): Promise<void>;
 
-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 { 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, verifyRuleApplication };
 export type { BuilderOutput, EnqueueResult, GatewayExecutorOptions, HttpWatcherClientOptions, InferenceRuleSpec, LockState, LoggerConfig, MergeOptions, MetaConfig, MetaContext, MetaEntry, MetaError, MetaExecutor, MetaJson, MetaListResult, MetaListSummary, MetaNode, MetaSpawnOptions, MetaSpawnResult, MinimalLogger, OrchestrateResult, OwnershipTree, ProgressCallback, ProgressEvent, ProgressPhase, ProgressReporterConfig, QueueItem, QueueState, RouteDeps, ServerOptions, ServiceConfig, ServiceStats, StalenessCandidate, WatcherClient };