@karmaniverous/jeeves-meta 0.15.4 → 0.15.6

package/dist/index.js

@@ -1,6 +1,7 @@
 import fs, { readdirSync, readFileSync, existsSync, writeFileSync, renameSync, unlinkSync, statSync, mkdirSync, copyFileSync, watchFile } from 'node:fs';
 import path, { join, dirname, resolve, basename, relative, posix } from 'node:path';
 import { unlink, readFile, mkdir, writeFile, copyFile } from 'node:fs/promises';
+import { z } from 'zod';
 import { fileURLToPath } from 'node:url';
 import process$1 from 'node:process';
 import { randomUUID, createHash } from 'node:crypto';
@@ -12,7 +13,6 @@ import require$$4 from 'util';
 import require$$5 from 'assert';
 import require$$2 from 'events';
 import vm from 'vm';
-import { z } from 'zod';
 import * as commander from 'commander';
 import 'node:child_process';
 import { tmpdir } from 'node:os';
@@ -67,6 +67,72 @@ async function pruneArchive(metaPath, maxArchive) {
     return toRemove;
 }
 
+/**
+ * Shared component descriptor constants for jeeves-meta.
+ *
+ * Single source of truth consumed by both the service descriptor and
+ * the OpenClaw plugin registration.
+ */
+/** Shared jeeves-meta component descriptor constants. */
+const META_COMPONENT = {
+    name: 'meta',
+    servicePackage: '@karmaniverous/jeeves-meta',
+    pluginPackage: '@karmaniverous/jeeves-meta-openclaw',
+    defaultPort: 1938};
+
+/**
+ * Structured error schema from a synthesis step failure.
+ *
+ */
+/** Zod schema for synthesis step errors. */
+const metaErrorSchema = z.object({
+    /** Which step failed: 'architect', 'builder', or 'critic'. */
+    step: z.enum(['architect', 'builder', 'critic']),
+    /** Error classification code. */
+    code: z.string(),
+    /** Human-readable error message. */
+    message: z.string(),
+});
+
+/** Zod schema for the core (library-compatible) meta configuration. */
+/** Zod schema for the core (library-compatible) meta configuration. */
+const metaConfigSchema = z.object({
+    /** Watcher service base URL. */
+    watcherUrl: z.url(),
+    /** OpenClaw gateway base URL for subprocess spawning. */
+    gatewayUrl: z.url().default('http://127.0.0.1:18789'),
+    /** Optional API key for gateway authentication. */
+    gatewayApiKey: z.string().optional(),
+    /** Run architect every N cycles (per meta). */
+    architectEvery: z.number().int().min(1).default(10),
+    /** Exponent for depth weighting in staleness formula. */
+    depthWeight: z.number().min(0).default(0.5),
+    /** Maximum archive snapshots to retain per meta. */
+    maxArchive: z.number().int().min(1).default(20),
+    /** Maximum lines of context to include in subprocess prompts. */
+    maxLines: z.number().int().min(50).default(500),
+    /** Architect subprocess timeout in seconds. */
+    architectTimeout: z.number().int().min(30).default(180),
+    /** Builder subprocess timeout in seconds. */
+    builderTimeout: z.number().int().min(60).default(360),
+    /** Critic subprocess timeout in seconds. */
+    criticTimeout: z.number().int().min(30).default(240),
+    /** Thinking level for spawned synthesis sessions. */
+    thinking: z.string().default('low'),
+    /** Resolved architect system prompt text. Falls back to built-in default. */
+    defaultArchitect: z.string().optional(),
+    /** Resolved critic system prompt text. Falls back to built-in default. */
+    defaultCritic: z.string().optional(),
+    /** Skip unchanged candidates, bump _generatedAt. */
+    skipUnchanged: z.boolean().default(true),
+    /** Watcher metadata properties applied to live .meta/meta.json files. */
+    metaProperty: z.record(z.string(), z.unknown()).default({ _meta: 'current' }),
+    /** Watcher metadata properties applied to archive snapshots. */
+    metaArchiveProperty: z
+        .record(z.string(), z.unknown())
+        .default({ _meta: 'archive' }),
+});
+
 /**
  * Normalize file paths to forward slashes for consistency with watcher-indexed paths.
  *
@@ -74,7 +140,6 @@ async function pruneArchive(metaPath, maxArchive) {
  * 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.
@@ -85,6 +150,22 @@ async function pruneArchive(metaPath, maxArchive) {
 function normalizePath(p) {
     return p.replaceAll('\\', '/');
 }
+/** Valid states for a synthesis phase. */
+const phaseStatuses = [
+    'fresh',
+    'stale',
+    'pending',
+    'running',
+    'failed',
+];
+/** Zod schema for a per-phase status value. */
+const phaseStatusSchema = z.enum(phaseStatuses);
+/** Zod schema for the per-meta phase state record. */
+const phaseStateSchema = z.object({
+    architect: phaseStatusSchema,
+    builder: phaseStatusSchema,
+    critic: phaseStatusSchema,
+});
 
 /**
  * Archive reading helpers — watcher scan with filesystem fallback.
@@ -322,7 +403,7 @@ function packageDirectorySync({cwd, ignoreTypeOnlyPackageJson} = {}) {
  * @module constants
  */
 /** Default HTTP port for the jeeves-meta service. */
-const DEFAULT_PORT = 1938;
+const DEFAULT_PORT = META_COMPONENT.defaultPort;
 /** Default port as a string (for Commander CLI defaults). */
 const DEFAULT_PORT_STR = String(DEFAULT_PORT);
 /** Service name identifier. */
@@ -1503,11 +1584,11 @@ var hasRequiredRetry$1;
 function requireRetry$1 () {
 	if (hasRequiredRetry$1) return retry$1;
 	hasRequiredRetry$1 = 1;
-	(function (exports$1) {
+	(function (exports) {
 		var RetryOperation = requireRetry_operation();
 
-		exports$1.operation = function(options) {
-		  var timeouts = exports$1.timeouts(options);
+		exports.operation = function(options) {
+		  var timeouts = exports.timeouts(options);
 		  return new RetryOperation(timeouts, {
 		      forever: options && options.forever,
 		      unref: options && options.unref,
@@ -1515,7 +1596,7 @@ function requireRetry$1 () {
 		  });
 		};
 
-		exports$1.timeouts = function(options) {
+		exports.timeouts = function(options) {
 		  if (options instanceof Array) {
 		    return [].concat(options);
 		  }
@@ -1552,7 +1633,7 @@ function requireRetry$1 () {
 		  return timeouts;
 		};
 
-		exports$1.createTimeout = function(attempt, opts) {
+		exports.createTimeout = function(attempt, opts) {
 		  var random = (opts.randomize)
 		    ? (Math.random() + 1)
 		    : 1;
@@ -1563,7 +1644,7 @@ function requireRetry$1 () {
 		  return timeout;
 		};
 
-		exports$1.wrap = function(obj, options, methods) {
+		exports.wrap = function(obj, options, methods) {
 		  if (options instanceof Array) {
 		    methods = options;
 		    options = null;
@@ -1583,7 +1664,7 @@ function requireRetry$1 () {
 		    var original = obj[method];
 
 		    obj[method] = function retryWrapper(original) {
-		      var op       = exports$1.operation(options);
+		      var op       = exports.operation(options);
 		      var args     = Array.prototype.slice.call(arguments, 1);
 		      var callback = args.pop();
 
@@ -4592,7 +4673,7 @@ var hasRequiredRe;
 function requireRe () {
 	if (hasRequiredRe) return re.exports;
 	hasRequiredRe = 1;
-	(function (module, exports$1) {
+	(function (module, exports) {
 
 		const {
 		  MAX_SAFE_COMPONENT_LENGTH,
@@ -4600,14 +4681,14 @@ function requireRe () {
 		  MAX_LENGTH,
 		} = requireConstants();
 		const debug = requireDebug();
-		exports$1 = module.exports = {};
+		exports = module.exports = {};
 
 		// The actual regexps go on exports.re
-		const re = exports$1.re = [];
-		const safeRe = exports$1.safeRe = [];
-		const src = exports$1.src = [];
-		const safeSrc = exports$1.safeSrc = [];
-		const t = exports$1.t = {};
+		const re = exports.re = [];
+		const safeRe = exports.safeRe = [];
+		const src = exports.src = [];
+		const safeSrc = exports.safeSrc = [];
+		const t = exports.t = {};
 		let R = 0;
 
 		const LETTERDASHNUMBER = '[a-zA-Z0-9-]';
@@ -4730,7 +4811,7 @@ function requireRe () {
 		createToken('GTLT', '((?:<|>)?=?)');
 
 		// Something like "2.*" or "1.2.x".
-		// Note that "x.x" is a valid xRange identifer, meaning "any version"
+		// Note that "x.x" is a valid xRange identifier, meaning "any version"
 		// Only the first item is strictly required.
 		createToken('XRANGEIDENTIFIERLOOSE', `${src[t.NUMERICIDENTIFIERLOOSE]}|x|X|\\*`);
 		createToken('XRANGEIDENTIFIER', `${src[t.NUMERICIDENTIFIER]}|x|X|\\*`);
@@ -4771,7 +4852,7 @@ function requireRe () {
 		createToken('LONETILDE', '(?:~>?)');
 
 		createToken('TILDETRIM', `(\\s*)${src[t.LONETILDE]}\\s+`, true);
-		exports$1.tildeTrimReplace = '$1~';
+		exports.tildeTrimReplace = '$1~';
 
 		createToken('TILDE', `^${src[t.LONETILDE]}${src[t.XRANGEPLAIN]}$`);
 		createToken('TILDELOOSE', `^${src[t.LONETILDE]}${src[t.XRANGEPLAINLOOSE]}$`);
@@ -4781,7 +4862,7 @@ function requireRe () {
 		createToken('LONECARET', '(?:\\^)');
 
 		createToken('CARETTRIM', `(\\s*)${src[t.LONECARET]}\\s+`, true);
-		exports$1.caretTrimReplace = '$1^';
+		exports.caretTrimReplace = '$1^';
 
 		createToken('CARET', `^${src[t.LONECARET]}${src[t.XRANGEPLAIN]}$`);
 		createToken('CARETLOOSE', `^${src[t.LONECARET]}${src[t.XRANGEPLAINLOOSE]}$`);
@@ -4794,7 +4875,7 @@ function requireRe () {
 		// it modifies, so that `> 1.2.3` ==> `>1.2.3`
 		createToken('COMPARATORTRIM', `(\\s*)${src[t.GTLT]
 		}\\s*(${src[t.LOOSEPLAIN]}|${src[t.XRANGEPLAIN]})`, true);
-		exports$1.comparatorTrimReplace = '$1$2$3';
+		exports.comparatorTrimReplace = '$1$2$3';
 
 		// Something like `1.2.3 - 1.2.4`
 		// Note that these all use the loose form, because they'll be
@@ -5726,6 +5807,62 @@ function requireCoerce () {
 	return coerce_1;
 }
 
+var truncate_1;
+var hasRequiredTruncate;
+
+function requireTruncate () {
+	if (hasRequiredTruncate) return truncate_1;
+	hasRequiredTruncate = 1;
+
+	const parse = requireParse();
+	const constants = requireConstants();
+	const SemVer = requireSemver$1();
+
+	const truncate = (version, truncation, options) => {
+	  if (!constants.RELEASE_TYPES.includes(truncation)) {
+	    return null
+	  }
+
+	  const clonedVersion = cloneInputVersion(version, options);
+	  return clonedVersion && doTruncation(clonedVersion, truncation)
+	};
+
+	const cloneInputVersion = (version, options) => {
+	  const versionStringToParse = (
+	    version instanceof SemVer ? version.version : version
+	  );
+
+	  return parse(versionStringToParse, options)
+	};
+
+	const doTruncation = (version, truncation) => {
+	  if (isPrerelease(truncation)) {
+	    return version.version
+	  }
+
+	  version.prerelease = [];
+
+	  switch (truncation) {
+	    case 'major':
+	      version.minor = 0;
+	      version.patch = 0;
+	      break
+	    case 'minor':
+	      version.patch = 0;
+	      break
+	  }
+
+	  return version.format()
+	};
+
+	const isPrerelease = (type) => {
+	  return type.startsWith('pre')
+	};
+
+	truncate_1 = truncate;
+	return truncate_1;
+}
+
 var lrucache;
 var hasRequiredLrucache;
 
@@ -7175,6 +7312,7 @@ function requireSemver () {
 	const lte = requireLte();
 	const cmp = requireCmp();
 	const coerce = requireCoerce();
+	const truncate = requireTruncate();
 	const Comparator = requireComparator();
 	const Range = requireRange();
 	const satisfies = requireSatisfies();
@@ -7213,6 +7351,7 @@ function requireSemver () {
 	  lte,
 	  cmp,
 	  coerce,
+	  truncate,
 	  Comparator,
 	  Range,
 	  satisfies,
@@ -7510,31 +7649,31 @@ var hasRequiredExtraTypings;
 function requireExtraTypings () {
 	if (hasRequiredExtraTypings) return extraTypings.exports;
 	hasRequiredExtraTypings = 1;
-	(function (module, exports$1) {
+	(function (module, exports) {
 		const commander = require$$0;
 
-		exports$1 = module.exports = {};
+		exports = module.exports = {};
 
 		// Return a different global program than commander,
 		// and don't also return it as default export.
-		exports$1.program = new commander.Command();
+		exports.program = new commander.Command();
 
 		/**
 		 * Expose classes. The FooT versions are just types, so return Commander original implementations!
 		 */
 
-		exports$1.Argument = commander.Argument;
-		exports$1.Command = commander.Command;
-		exports$1.CommanderError = commander.CommanderError;
-		exports$1.Help = commander.Help;
-		exports$1.InvalidArgumentError = commander.InvalidArgumentError;
-		exports$1.InvalidOptionArgumentError = commander.InvalidArgumentError; // Deprecated
-		exports$1.Option = commander.Option;
+		exports.Argument = commander.Argument;
+		exports.Command = commander.Command;
+		exports.CommanderError = commander.CommanderError;
+		exports.Help = commander.Help;
+		exports.InvalidArgumentError = commander.InvalidArgumentError;
+		exports.InvalidOptionArgumentError = commander.InvalidArgumentError; // Deprecated
+		exports.Option = commander.Option;
 
-		exports$1.createCommand = (name) => new commander.Command(name);
-		exports$1.createOption = (flags, description) =>
+		exports.createCommand = (name) => new commander.Command(name);
+		exports.createOption = (flags, description) =>
 		  new commander.Option(flags, description);
-		exports$1.createArgument = (name, description) =>
+		exports.createArgument = (name, description) =>
 		  new commander.Argument(name, description); 
 	} (extraTypings, extraTypings.exports));
 	return extraTypings.exports;
@@ -8879,43 +9018,6 @@ function applyHotReloadedConfig(newConfig) {
  *
  * @module schema/config
  */
-/** Zod schema for the core (library-compatible) meta configuration. */
-const metaConfigSchema = z.object({
-    /** Watcher service base URL. */
-    watcherUrl: z.url(),
-    /** OpenClaw gateway base URL for subprocess spawning. */
-    gatewayUrl: z.url().default('http://127.0.0.1:18789'),
-    /** Optional API key for gateway authentication. */
-    gatewayApiKey: z.string().optional(),
-    /** Run architect every N cycles (per meta). */
-    architectEvery: z.number().int().min(1).default(10),
-    /** Exponent for depth weighting in staleness formula. */
-    depthWeight: z.number().min(0).default(0.5),
-    /** Maximum archive snapshots to retain per meta. */
-    maxArchive: z.number().int().min(1).default(20),
-    /** Maximum lines of context to include in subprocess prompts. */
-    maxLines: z.number().int().min(50).default(500),
-    /** Architect subprocess timeout in seconds. */
-    architectTimeout: z.number().int().min(30).default(180),
-    /** Builder subprocess timeout in seconds. */
-    builderTimeout: z.number().int().min(60).default(360),
-    /** Critic subprocess timeout in seconds. */
-    criticTimeout: z.number().int().min(30).default(240),
-    /** Thinking level for spawned synthesis sessions. */
-    thinking: z.string().default('low'),
-    /** Resolved architect system prompt text. Falls back to built-in default. */
-    defaultArchitect: z.string().optional(),
-    /** Resolved critic system prompt text. Falls back to built-in default. */
-    defaultCritic: z.string().optional(),
-    /** Skip unchanged candidates, bump _generatedAt. */
-    skipUnchanged: z.boolean().default(true),
-    /** Watcher metadata properties applied to live .meta/meta.json files. */
-    metaProperty: z.record(z.string(), z.unknown()).default({ _meta: 'current' }),
-    /** Watcher metadata properties applied to archive snapshots. */
-    metaArchiveProperty: z
-        .record(z.string(), z.unknown())
-        .default({ _meta: 'archive' }),
-});
 /** Zod schema for logging configuration. */
 const loggingSchema = z.object({
     /** Log level. */
@@ -9232,8 +9334,10 @@ class GatewayExecutor {
             ...(options?.thinking ? { thinking: options.thinking } : {}),
             ...(options?.model ? { model: options.model } : {}),
         });
-        const details = (spawnResult.result?.details ?? spawnResult.result);
-        const sessionKey = details?.childSessionKey ?? details?.sessionKey;
+        const details = (spawnResult.result?.details ??
+            spawnResult.result ??
+            {});
+        const sessionKey = details.childSessionKey ?? details.sessionKey;
         if (typeof sessionKey !== 'string' || !sessionKey) {
             throw new Error('Gateway sessions_spawn returned no sessionKey: ' +
                 JSON.stringify(spawnResult));
@@ -12027,7 +12131,7 @@ function registerMetasUpdateRoute(app, deps) {
         const metaDir = resolveMetaDir(targetPath);
         let meta;
         try {
-            meta = (await readMetaJson(metaDir));
+            meta = await readMetaJson(metaDir);
         }
         catch {
             return reply.status(404).send({
@@ -13024,11 +13128,11 @@ async function startService(config, configPath) {
  * Parsed jeeves-meta component descriptor.
  */
 const metaDescriptor = jeevesComponentDescriptorSchema.parse({
-    name: 'meta',
+    name: META_COMPONENT.name,
     version: SERVICE_VERSION,
-    servicePackage: '@karmaniverous/jeeves-meta',
-    pluginPackage: '@karmaniverous/jeeves-meta-openclaw',
-    defaultPort: 1938,
+    servicePackage: META_COMPONENT.servicePackage,
+    pluginPackage: META_COMPONENT.pluginPackage,
+    defaultPort: META_COMPONENT.defaultPort,
     // The runtime Zod custom validator only checks for a .parse() method.
     // Use unknown cast to bridge the Zod v4 (service) → v3 (core SDK) type gap.
     configSchema: serviceConfigSchema,
@@ -13079,21 +13183,6 @@ function computeEma(current, previous, decay = DEFAULT_DECAY) {
     return decay * current + (1 - decay) * previous;
 }
 
-/**
- * Structured error from a synthesis step failure.
- *
- * @module schema/error
- */
-/** Zod schema for synthesis step errors. */
-const metaErrorSchema = z.object({
-    /** Which step failed: 'architect', 'builder', or 'critic'. */
-    step: z.enum(['architect', 'builder', 'critic']),
-    /** Error classification code. */
-    code: z.string(),
-    /** Human-readable error message. */
-    message: z.string(),
-});
-
 /**
  * Zod schema for .meta/meta.json files.
  *
@@ -13102,22 +13191,6 @@ const metaErrorSchema = z.object({
  *
  * @module schema/meta
  */
-/** Valid states for a synthesis phase. */
-const phaseStatuses = [
-    'fresh',
-    'stale',
-    'pending',
-    'running',
-    'failed',
-];
-/** Zod schema for a per-phase status value. */
-const phaseStatusSchema = z.enum(phaseStatuses);
-/** Zod schema for the per-meta phase state record. */
-const phaseStateSchema = z.object({
-    architect: phaseStatusSchema,
-    builder: phaseStatusSchema,
-    critic: phaseStatusSchema,
-});
 /** Zod schema for the reserved (underscore-prefixed) meta.json properties. */
 const metaJsonSchema = z
     .object({

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';