@karmaniverous/jeeves-meta 0.15.4 → 0.15.5

package/dist/archive/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Archive module — snapshot creation, pruning, and reading.
+ *
+ * @module archive
+ */
+export { listArchiveFiles } from './listArchive.js';
+export { pruneArchive } from './prune.js';
+export { readArchiveFromDisk, readArchiveFromWatcher } from './readArchive.js';
+export { readLatestArchive } from './readLatest.js';
+export { createSnapshot } from './snapshot.js';

package/dist/archive/listArchive.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export declare function listArchiveFiles(metaPath: string): string[];

package/dist/archive/prune.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+export declare function pruneArchive(metaPath: string, maxArchive: number): Promise<number>;

package/dist/archive/readArchive.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Archive reading helpers — watcher scan with filesystem fallback.
+ *
+ * Used by the GET /metas/:path route to retrieve archive history.
+ * Prefers watcher scan for performance; falls back to disk reads
+ * when the watcher is unavailable.
+ *
+ * @module archive/readArchive
+ */
+import type { WatcherClient } from '../interfaces/index.js';
+/**
+ * Read archive history via watcher scan.
+ *
+ * @param watcher - WatcherClient with scan support.
+ * @param metaPath - Absolute path to the .meta/ directory.
+ * @param metaArchiveProperty - Additional filter properties for archive points.
+ * @param limit - Max entries to return (newest first). Undefined = all.
+ * @param projectMeta - Field projection function.
+ * @returns Array of projected archive entries, newest first.
+ */
+export declare function readArchiveFromWatcher(watcher: WatcherClient, metaPath: string, metaArchiveProperty: Record<string, unknown>, limit: number | undefined, projectMeta: (m: Record<string, unknown>) => Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+/**
+ * Read archive history from disk (fallback).
+ *
+ * @param metaPath - Absolute path to the .meta/ directory.
+ * @param limit - Max entries to return (newest first). Undefined = all.
+ * @param projectMeta - Field projection function.
+ * @returns Array of projected archive entries, newest first.
+ */
+export declare function readArchiveFromDisk(metaPath: string, limit: number | undefined, projectMeta: (m: Record<string, unknown>) => Record<string, unknown>): Promise<Array<Record<string, unknown>>>;

package/dist/archive/readLatest.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Read the latest archive snapshot for steer change detection.
+ *
+ * @module archive/readLatest
+ */
+import type { MetaJson } from '../schema/index.js';
+/**
+ * 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.
+ */
+export declare function readLatestArchive(metaPath: string): Promise<MetaJson | null>;

package/dist/archive/snapshot.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Create archive snapshots of meta.json.
+ *
+ * Copies current meta.json to archive/\{ISO-timestamp\}.json with
+ * _archived: true and _archivedAt added.
+ *
+ * @module archive/snapshot
+ */
+import type { MetaJson } from '../schema/index.js';
+/**
+ * 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.
+ */
+export declare function createSnapshot(metaPath: string, meta: MetaJson): Promise<string>;

package/dist/bootstrap.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Service bootstrap — wire up all components and start listening.
+ *
+ * @module bootstrap
+ */
+import { type ServiceConfig } from './schema/config.js';
+/**
+ * Bootstrap the service: create logger, build server, start listening,
+ * wire scheduler, queue processing, rule registration, config hot-reload,
+ * startup lock cleanup, and shutdown.
+ *
+ * @param config - Validated service configuration.
+ * @param configPath - Optional path to config file for hot-reload.
+ */
+export declare function startService(config: ServiceConfig, configPath?: string): Promise<void>;

package/dist/cache.d.ts

@@ -0,0 +1,22 @@
+/**
+ * In-memory cache for listMetas results with TTL and concurrent refresh guard.
+ *
+ * @module cache
+ */
+import { type MetaListResult } from './discovery/index.js';
+import type { WatcherClient } from './interfaces/index.js';
+import type { ServiceConfig } from './schema/config.js';
+/**
+ * Caches listMetas results to avoid expensive repeated filesystem walks.
+ * Supports concurrent refresh coalescing and manual invalidation.
+ */
+export declare class MetaCache {
+    private result;
+    private updatedAt;
+    private refreshPromise;
+    /** Get cached result or refresh if stale. */
+    get(config: ServiceConfig, watcher: WatcherClient): Promise<MetaListResult>;
+    /** Force-expire the cache so next get() triggers a refresh. */
+    invalidate(): void;
+    private refresh;
+}

package/dist/cli/jeeves-meta/index.js

@@ -1181,11 +1181,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,
@@ -1193,7 +1193,7 @@ function requireRetry$1 () {
 		  });
 		};
 
-		exports$1.timeouts = function(options) {
+		exports.timeouts = function(options) {
 		  if (options instanceof Array) {
 		    return [].concat(options);
 		  }
@@ -1230,7 +1230,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;
@@ -1241,7 +1241,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;
@@ -1261,7 +1261,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();
 
@@ -4270,7 +4270,7 @@ var hasRequiredRe;
 function requireRe () {
 	if (hasRequiredRe) return re.exports;
 	hasRequiredRe = 1;
-	(function (module, exports$1) {
+	(function (module, exports) {
 
 		const {
 		  MAX_SAFE_COMPONENT_LENGTH,
@@ -4278,14 +4278,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-]';
@@ -4408,7 +4408,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|\\*`);
@@ -4449,7 +4449,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]}$`);
@@ -4459,7 +4459,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]}$`);
@@ -4472,7 +4472,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
@@ -5404,6 +5404,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;
 
@@ -6853,6 +6909,7 @@ function requireSemver () {
 	const lte = requireLte();
 	const cmp = requireCmp();
 	const coerce = requireCoerce();
+	const truncate = requireTruncate();
 	const Comparator = requireComparator();
 	const Range = requireRange();
 	const satisfies = requireSatisfies();
@@ -6891,6 +6948,7 @@ function requireSemver () {
 	  lte,
 	  cmp,
 	  coerce,
+	  truncate,
 	  Comparator,
 	  Range,
 	  satisfies,
@@ -7335,31 +7393,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;
@@ -8418,6 +8476,106 @@ function sleepAsync(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
 
+/**
+ * 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. */
+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.
+ *
+ * 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.
+ *
+ */
+/**
+ * Normalize a file path to forward slashes.
+ *
+ * @param p - File path (may contain backslashes).
+ * @returns Path with all backslashes replaced by forward slashes.
+ */
+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. */
+z.object({
+    architect: phaseStatusSchema,
+    builder: phaseStatusSchema,
+    critic: phaseStatusSchema,
+});
+
 /**
  * Compute summary statistics from an array of MetaEntry objects.
  *
@@ -8491,25 +8649,6 @@ function computeSummary(entries, depthWeight) {
     };
 }
 
-/**
- * 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.
- */
-function normalizePath(p) {
-    return p.replaceAll('\\', '/');
-}
-
 /**
  * Discover .meta/ directories via watcher `/walk` endpoint.
  *
@@ -9185,43 +9324,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. */
@@ -9493,8 +9595,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));
@@ -12476,7 +12580,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({
@@ -12812,7 +12916,7 @@ function registerSeedRoute(app, deps) {
  * @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. */
@@ -13654,11 +13758,11 @@ function registerCustomCliCommands(program) {
  * 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,

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Commander CLI for jeeves-meta service.
+ *
+ * Uses `createServiceCli` from the core SDK for standard commands
+ * (start, status, config, init, service). Custom domain-specific
+ * commands are registered via `descriptor.customCliCommands`.
+ *
+ * @module cli
+ */
+export {};

package/dist/configHotReload.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared live config hot-reload support.
+ *
+ * Used by both file-watch reloads in bootstrap and POST /config/apply
+ * via the component descriptor's onConfigApply callback.
+ *
+ * @module configHotReload
+ */
+import type { Logger } from 'pino';
+import type { Scheduler } from './scheduler/index.js';
+import type { ServiceConfig } from './schema/config.js';
+/**
+ * Fields that require a service restart to take effect.
+ *
+ * Shared between the descriptor's `onConfigApply` and the file-watcher
+ * hot-reload in `bootstrap.ts`.
+ */
+export declare const RESTART_REQUIRED_FIELDS: readonly ["port", "watcherUrl", "gatewayUrl", "gatewayApiKey", "defaultArchitect", "defaultCritic"];
+interface ConfigHotReloadRuntime {
+    config: ServiceConfig;
+    logger: Logger;
+    scheduler: Scheduler | null;
+}
+/** Register the active service runtime for config-apply hot reload. */
+export declare function registerConfigHotReloadRuntime(nextRuntime: ConfigHotReloadRuntime): void;
+/** Clear the registered runtime. Primarily for tests. */
+export declare function clearConfigHotReloadRuntime(): void;
+/** Apply hot-reloadable config changes to the live shared config object. */
+export declare function applyHotReloadedConfig(newConfig: ServiceConfig): void;
+export {};

package/dist/configLoader.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Load and resolve jeeves-meta service config.
+ *
+ * Supports \@file: indirection and environment-variable substitution (dollar-brace pattern).
+ *
+ * @module configLoader
+ */
+import { type ServiceConfig } from './schema/config.js';
+/**
+ * Migrate legacy config path to the new canonical location.
+ *
+ * If the old path `{configRoot}/jeeves-meta.config.json` exists and the new
+ * path `{configRoot}/jeeves-meta/config.json` does NOT exist, copies the file
+ * to the new location and logs a warning.
+ *
+ * @param configRoot - Root directory for configuration files.
+ * @param warn - Optional callback for logging the migration warning.
+ */
+export declare function migrateConfigPath(configRoot: string, warn?: (msg: string) => void): void;
+/**
+ * Resolve config path from --config flag or JEEVES_META_CONFIG env var.
+ *
+ * @param args - CLI arguments (process.argv.slice(2)).
+ * @returns Resolved config path.
+ * @throws If no config path found.
+ */
+export declare function resolveConfigPath(args: string[]): string;
+/**
+ * Load service config from a JSON file.
+ *
+ * Resolves \@file: references for defaultArchitect and defaultCritic,
+ * and substitutes environment-variable placeholders throughout.
+ *
+ * @param configPath - Path to config JSON file.
+ * @returns Validated ServiceConfig.
+ */
+export declare function loadServiceConfig(configPath: string): ServiceConfig;