@karmaniverous/jeeves-meta 0.15.3 → 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/architect.md

@@ -91,6 +91,23 @@ Define what "verify before asserting" means for this data shape:
 Always require: exact entity titles/names (not paraphrases), evidence citations,
 partial implementation notes, config default verification from schema files.
 
+{{#if (gt scope.fileCount 500)}}
+## LARGE SCOPE — SAMPLING MODE
+
+This entity has {{scope.fileCount}} files. Do NOT attempt to read or
+explore the full scope. Instead:
+
+1. Read _state and _content from previous cycles to understand existing
+   data shape knowledge
+2. Sample at most 5–10 representative files to verify the data shape
+   hasn't fundamentally changed
+3. Focus your brief updates on what the _feedback says needs improving
+4. Preserve the existing progressive processing strategy unless the
+   data shape has materially changed
+
+Your job on re-runs is refinement, not rediscovery.
+{{/if}}
+
 ### 7. Progressive Processing (_state)
 
 When the scope is large (hundreds of files or more), instruct the Builder to