@karmaniverous/jeeves-meta 0.15.3 → 0.15.5

package/dist/phaseState/phaseTransitions.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Pure phase-state transition functions.
+ *
+ * Implements every row of the §8 "Transitions and invalidation cascade" table.
+ * No I/O — pure functions over PhaseState and documented inputs.
+ *
+ * @module phaseState/phaseTransitions
+ */
+import type { PhaseState } from '../schema/meta.js';
+/**
+ * Create a fresh (fully-complete) phase state.
+ */
+export declare function freshPhaseState(): PhaseState;
+/**
+ * Create a phase state for a never-synthesized meta (all pending from architect).
+ */
+export declare function initialPhaseState(): PhaseState;
+/**
+ * Enforce the per-meta invariant: at most one phase is pending or running,
+ * and it is the first non-fresh phase in pipeline order.
+ *
+ * Stale phases that become the first non-fresh phase are promoted to pending.
+ */
+export declare function enforceInvariant(state: PhaseState): PhaseState;
+/**
+ * Architect invalidated: architect → pending; builder, critic → stale.
+ * Triggers: _structureHash change, _steer change, _architect change,
+ * _crossRefs declaration change, _synthesisCount \>= architectEvery.
+ */
+export declare function invalidateArchitect(state: PhaseState): PhaseState;
+/**
+ * Builder invalidated (scope mtime or cross-ref _content change):
+ * builder → pending; critic → stale.
+ * Only applies when architect is fresh; otherwise, builder stays stale.
+ */
+export declare function invalidateBuilder(state: PhaseState): PhaseState;
+/**
+ * Architect completes successfully.
+ * architect → fresh; builder → pending; critic → stale.
+ */
+export declare function architectSuccess(state: PhaseState): PhaseState;
+/**
+ * Builder completes successfully.
+ * builder → fresh; critic → pending.
+ */
+export declare function builderSuccess(state: PhaseState): PhaseState;
+/**
+ * Critic completes successfully.
+ * critic → fresh. Meta becomes fully fresh.
+ */
+export declare function criticSuccess(state: PhaseState): PhaseState;
+/**
+ * A phase fails (error, timeout, or abort).
+ * Target phase → failed; upstream and downstream unchanged.
+ */
+export declare function phaseFailed(state: PhaseState, phase: 'architect' | 'builder' | 'critic'): PhaseState;
+/**
+ * Retry a failed phase: failed → pending.
+ * Only valid when the phase is currently failed.
+ */
+export declare function retryPhase(state: PhaseState, phase: 'architect' | 'builder' | 'critic'): PhaseState;
+/**
+ * Retry all failed phases: each failed phase → pending.
+ * Used by scheduler ticks and queue reads to auto-promote failed phases.
+ */
+export declare function retryAllFailed(state: PhaseState): PhaseState;
+/**
+ * Mark a phase as running (scheduler picks it).
+ */
+export declare function phaseRunning(state: PhaseState, phase: 'architect' | 'builder' | 'critic'): PhaseState;
+/**
+ * Get the owed phase: first non-fresh phase in pipeline order, or null.
+ */
+export declare function getOwedPhase(state: PhaseState): 'architect' | 'builder' | 'critic' | null;
+/**
+ * Check if a meta is fully fresh (all phases fresh).
+ */
+export declare function isFullyFresh(state: PhaseState): boolean;
+/**
+ * Get the scheduler priority band for a meta's owed phase.
+ * 1 = critic (highest), 2 = builder, 3 = architect, null = fully fresh.
+ */
+export declare function getPriorityBand(state: PhaseState): 1 | 2 | 3 | null;

package/dist/progress/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Progress reporting via OpenClaw gateway `/tools/invoke` → `message` tool.
+ *
+ * @module progress
+ */
+import type { Logger } from 'pino';
+export type ProgressPhase = 'architect' | 'builder' | 'critic';
+export type ProgressEvent = {
+    type: 'synthesis_start' | 'phase_start' | 'phase_complete' | 'synthesis_complete' | 'error';
+    /** Owner path (not .meta path) of the entity being synthesized. */
+    path: string;
+    phase?: ProgressPhase;
+    tokens?: number;
+    durationMs?: number;
+    error?: string;
+};
+export type ProgressReporterConfig = {
+    gatewayUrl: string;
+    gatewayApiKey?: string;
+    /**
+     * Messaging channel name (e.g. 'slack'). When set alongside reportTarget,
+     * included in the gateway message payload as `channel`.
+     * Legacy: if reportTarget is unset, reportChannel is used as the target
+     * (single-channel mode, backward compatible).
+     */
+    reportChannel?: string;
+    /** Channel/user ID to send messages to. Takes priority over reportChannel as target. */
+    reportTarget?: string;
+    /** Optional base URL for the service, used to construct entity links. */
+    serverBaseUrl?: string;
+};
+export declare function formatProgressEvent(event: ProgressEvent, serverBaseUrl?: string): string;
+export declare class ProgressReporter {
+    private readonly config;
+    private readonly logger;
+    constructor(config: ProgressReporterConfig, logger: Logger);
+    report(event: ProgressEvent): Promise<void>;
+}

package/dist/prompts/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

package/dist/prompts/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Built-in default prompts for the synthesis pipeline.
+ *
+ * Prompts ship as .md files bundled into dist/prompts/ via rollup-plugin-copy.
+ * Loaded at runtime relative to the compiled module location.
+ *
+ * Users can override via `defaultArchitect` / `defaultCritic` in the service
+ * config. Most installations should use the built-in defaults.
+ *
+ * @module prompts
+ */
+/** Built-in default architect prompt. */
+export declare const DEFAULT_ARCHITECT_PROMPT: string;
+/** Built-in default critic prompt. */
+export declare const DEFAULT_CRITIC_PROMPT: string;

package/dist/queue/index.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Hybrid 3-layer synthesis queue.
+ *
+ * Layer 1: Current — the single item currently executing (at most one).
+ * Layer 2: Overrides — items manually enqueued via POST /synthesize with path.
+ *          FIFO among overrides, ahead of automatic candidates.
+ * Layer 3: Automatic — computed on read, not persisted. All metas with a
+ *          pending phase, ranked by scheduler priority.
+ *
+ * Legacy: `pending` array is the union of overrides + automatic.
+ *
+ * @module queue
+ */
+import type { Logger } from 'pino';
+import type { PhaseName } from '../schema/meta.js';
+/** A queued synthesis work item. */
+export interface QueueItem {
+    path: string;
+    priority: boolean;
+    enqueuedAt: string;
+}
+/** An override entry in the explicit queue layer. */
+export interface OverrideEntry {
+    path: string;
+    enqueuedAt: string;
+}
+/** The currently executing item with phase info. */
+export interface CurrentItem {
+    path: string;
+    phase: PhaseName;
+    startedAt: string;
+}
+/** Result returned by {@link SynthesisQueue.enqueue}. */
+export interface EnqueueResult {
+    position: number;
+    alreadyQueued: boolean;
+}
+/** Snapshot of queue state for the /status endpoint. */
+export interface QueueState {
+    depth: number;
+    items: Array<{
+        path: string;
+        priority: boolean;
+        enqueuedAt: string;
+    }>;
+}
+/**
+ * Hybrid 3-layer synthesis queue.
+ *
+ * Only one synthesis runs at a time. Override items (explicit triggers)
+ * take priority over automatic candidates.
+ */
+export declare class SynthesisQueue {
+    /** Legacy queue (used by processQueue for backward compat). */
+    private queue;
+    private currentItem;
+    private processing;
+    private logger;
+    private onEnqueueCallback;
+    /** Explicit override entries (3-layer model). */
+    private overrideEntries;
+    /** Currently executing item with phase info (3-layer model). */
+    private currentPhaseItem;
+    constructor(logger: Logger);
+    /** Set a callback to invoke when a new (non-duplicate) item is enqueued. */
+    onEnqueue(callback: () => void): void;
+    /**
+     * Add an explicit override entry (from POST /synthesize with path).
+     * Deduped by path. Returns position and whether already queued.
+     */
+    enqueueOverride(path: string): EnqueueResult;
+    /** Dequeue the next override entry, or undefined if empty. */
+    dequeueOverride(): OverrideEntry | undefined;
+    /** Get all override entries (shallow copy). */
+    get overrides(): OverrideEntry[];
+    /** Clear all override entries. Returns count removed. */
+    clearOverrides(): number;
+    /** Check if a path is in the override layer. */
+    hasOverride(path: string): boolean;
+    /** Set the currently executing phase item. */
+    setCurrentPhase(path: string, phase: PhaseName): void;
+    /** Clear the current phase item. */
+    clearCurrentPhase(): void;
+    /** The currently executing phase item, or null. */
+    get currentPhase(): CurrentItem | null;
+    /**
+     * Add a path to the synthesis queue.
+     *
+     * @param path - Meta path to synthesize.
+     * @param priority - If true, insert at front of queue.
+     * @returns Position and whether the path was already queued.
+     */
+    enqueue(path: string, priority?: boolean): EnqueueResult;
+    /** Remove and return the next item from the queue. */
+    dequeue(): QueueItem | undefined;
+    /** Mark the currently-running synthesis as complete. */
+    complete(): void;
+    /** Number of items waiting in the queue (excludes current). */
+    get depth(): number;
+    /** The item currently being synthesized, or null. */
+    get current(): QueueItem | null;
+    /** A shallow copy of the queued items. */
+    get items(): QueueItem[];
+    /** A shallow copy of the pending items (alias for items). */
+    get pending(): QueueItem[];
+    /**
+     * Remove all pending items from the queue.
+     * Does not affect the currently-running item.
+     *
+     * @returns The number of items removed.
+     */
+    clear(): number;
+    /** Check whether a path is in the queue or currently being synthesized. */
+    has(path: string): boolean;
+    /** Get the 0-indexed position of a path in the queue. */
+    getPosition(path: string): number | null;
+    /** Dequeue the next item: overrides first, then legacy queue. */
+    private nextItem;
+    /** Return a snapshot of queue state for the /status endpoint. */
+    getState(): QueueState;
+    /**
+     * Process queued items one at a time until all queues are empty.
+     *
+     * Override entries are processed first (FIFO), then legacy queue items.
+     * Re-entry is prevented: if already processing, the call returns
+     * immediately. Errors are logged and do not block subsequent items.
+     *
+     * @param synthesizeFn - Async function that performs synthesis for a path.
+     */
+    processQueue(synthesizeFn: (path: string) => Promise<void>): Promise<void>;
+}

package/dist/readMetaJson.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Read and parse a meta.json file from a `.meta/` directory.
+ *
+ * Shared utility to eliminate repeated `JSON.parse(readFileSync(...))` across
+ * discovery, orchestration, and route handlers.
+ *
+ * @module readMetaJson
+ */
+import type { MetaJson } from './schema/index.js';
+/**
+ * Read and parse a meta.json file from a `.meta/` directory path (async).
+ *
+ * @param metaPath - Path to the `.meta/` directory.
+ * @returns Parsed meta.json content.
+ * @throws If the file doesn't exist or contains invalid JSON.
+ */
+export declare function readMetaJson(metaPath: string): Promise<MetaJson>;

package/dist/routes/__testUtils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared test utilities for route test files.
+ *
+ * Provides factories for RouteDeps, logger mocks, watcher mocks, and
+ * filesystem-based meta fixtures. Eliminates duplication across 9+ test files.
+ *
+ * @module routes/__testUtils
+ */
+import type { Logger } from 'pino';
+import type { WatcherClient } from '../interfaces/index.js';
+import type { RouteDeps } from './index.js';
+/** Create a mock pino logger with all standard methods. */
+export declare function makeTestLogger(): Logger;
+/** Overrides for makeTestDeps — config can be partially specified. */
+type TestDepsOverrides = Omit<Partial<RouteDeps>, 'config'> & {
+    config?: Partial<RouteDeps['config']>;
+};
+/** Create a RouteDeps object with sensible test defaults. */
+export declare function makeTestDeps(overrides?: TestDepsOverrides): RouteDeps;
+/**
+ * Create a mock WatcherClient that resolves walk() with given paths.
+ *
+ * @param metaJsonPaths - Paths to return from walk().
+ * @param scan - Optional custom scan mock (defaults to empty results).
+ */
+export declare function makeTestWatcher(metaJsonPaths?: string[], scan?: import("vitest").Mock<import("@vitest/spy").Procedure>): WatcherClient;
+/** Create a mock WatcherClient that rejects walk() calls. */
+export declare function makeFailingTestWatcher(): WatcherClient;
+/**
+ * Create a .meta/meta.json on disk and return the meta.json path.
+ *
+ * @param ownerDir - The owner directory to create .meta/ in.
+ * @param meta - Additional meta fields (merged with default _id).
+ * @returns The path to the created meta.json file.
+ */
+export declare function createTestMeta(ownerDir: string, meta?: Record<string, unknown>): string;
+export {};

package/dist/routes/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * GET /config — query service configuration with optional JSONPath.
+ *
+ * Replaces the old GET /config/validate endpoint with the core SDK's
+ * `createConfigQueryHandler()` for JSONPath support.
+ *
+ * @module routes/config
+ */
+import type { FastifyInstance } from 'fastify';
+import type { RouteDeps } from './index.js';
+export declare function registerConfigRoute(app: FastifyInstance, deps: RouteDeps): void;

package/dist/routes/configApply.d.ts

@@ -0,0 +1,13 @@
+/**
+ * POST /config/apply — apply a config patch using the runtime config path.
+ *
+ * The core SDK's `createConfigApplyHandler` derives the config path from
+ * `getComponentConfigDir()` which uses the npm global config root. This
+ * local implementation uses the actual runtime config path instead, so
+ * temp files are written alongside the active config file.
+ *
+ * @module routes/configApply
+ */
+import type { FastifyInstance } from 'fastify';
+/** Register the POST /config/apply route. */
+export declare function registerConfigApplyRoute(app: FastifyInstance, configPath?: string): void;

package/dist/routes/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Route registration for jeeves-meta service.
+ *
+ * @module routes
+ */
+import type { FastifyInstance } from 'fastify';
+import type { Logger } from 'pino';
+import type { MetaCache } from '../cache.js';
+import type { GatewayExecutor } from '../executor/index.js';
+import type { WatcherClient } from '../interfaces/index.js';
+import type { SynthesisQueue } from '../queue/index.js';
+import type { RuleRegistrar } from '../rules/index.js';
+import type { Scheduler } from '../scheduler/index.js';
+import type { ServiceConfig } from '../schema/config.js';
+/** Runtime stats tracked by the service. */
+export interface ServiceStats {
+    totalSyntheses: number;
+    totalTokens: number;
+    totalErrors: number;
+    lastCycleDurationMs: number | null;
+    lastCycleAt: string | null;
+}
+/**
+ * Large generated fields excluded from detail/update response projections.
+ * Shared between metas detail and metasUpdate routes.
+ */
+export declare const DEFAULT_EXCLUDE_FIELDS: Set<string>;
+/** Dependencies injected into route handlers. */
+export interface RouteDeps {
+    config: ServiceConfig;
+    logger: Logger;
+    queue: SynthesisQueue;
+    watcher: WatcherClient;
+    scheduler: Scheduler | null;
+    stats: ServiceStats;
+    /** Cached listMetas results with TTL. */
+    cache: MetaCache;
+    /** Service readiness flag — false during startup. */
+    ready: boolean;
+    /** Rule registrar for reporting registration state in /status. */
+    registrar?: RuleRegistrar;
+    /** Executor instance for abort support. */
+    executor?: Pick<GatewayExecutor, 'abort'>;
+    /** Set to true during graceful shutdown. */
+    shuttingDown?: boolean;
+    /** Runtime config file path for config-apply. */
+    configPath?: string;
+}
+/** Register all HTTP routes on the Fastify instance. */
+export declare function registerRoutes(app: FastifyInstance, deps: RouteDeps): void;

package/dist/routes/metas.d.ts

@@ -0,0 +1,9 @@
+/**
+ * GET /metas — list metas with optional filters.
+ * GET /metas/:path — single meta detail.
+ *
+ * @module routes/metas
+ */
+import type { FastifyInstance } from 'fastify';
+import { type RouteDeps } from './index.js';
+export declare function registerMetasRoutes(app: FastifyInstance, deps: RouteDeps): void;

package/dist/routes/metasUpdate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * PATCH /metas/:path — update user-settable reserved properties on a meta.
+ *
+ * Supported fields: _steer, _emphasis, _depth, _crossRefs, _disabled.
+ * Set a field to null to remove it. Unknown keys are rejected.
+ *
+ * @module routes/metasUpdate
+ */
+import type { FastifyInstance } from 'fastify';
+import { type RouteDeps } from './index.js';
+export declare function registerMetasUpdateRoute(app: FastifyInstance, deps: RouteDeps): void;

package/dist/routes/preview.d.ts

@@ -0,0 +1,8 @@
+/**
+ * GET /preview — dry-run synthesis preview.
+ *
+ * @module routes/preview
+ */
+import type { FastifyInstance } from 'fastify';
+import type { RouteDeps } from './index.js';
+export declare function registerPreviewRoute(app: FastifyInstance, deps: RouteDeps): void;

package/dist/routes/queue.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Queue management and abort routes.
+ *
+ * - GET /queue — 3-layer queue model (current, overrides, automatic, pending)
+ * - POST /queue/clear — remove override entries only
+ * - POST /synthesize/abort — abort the current synthesis
+ *
+ * @module routes/queue
+ */
+import type { FastifyInstance } from 'fastify';
+import type { RouteDeps } from './index.js';
+/** Register queue management routes. */
+export declare function registerQueueRoutes(app: FastifyInstance, deps: RouteDeps): void;

package/dist/routes/seed.d.ts

@@ -0,0 +1,8 @@
+/**
+ * POST /seed — create a .meta/ directory with an empty meta.json.
+ *
+ * @module routes/seed
+ */
+import type { FastifyInstance } from 'fastify';
+import type { RouteDeps } from './index.js';
+export declare function registerSeedRoute(app: FastifyInstance, deps: RouteDeps): void;

package/dist/routes/status.d.ts

@@ -0,0 +1,13 @@
+/**
+ * GET /status — service health and status overview.
+ *
+ * Uses the core SDK's `createStatusHandler` factory with a custom
+ * `getHealth` callback that preserves all existing health details.
+ *
+ * @module routes/status
+ */
+import type { ServiceState } from '@karmaniverous/jeeves-meta-core';
+import type { FastifyInstance } from 'fastify';
+import type { RouteDeps } from './index.js';
+export type { ServiceState };
+export declare function registerStatusRoute(app: FastifyInstance, deps: RouteDeps): void;

package/dist/routes/synthesize.d.ts

@@ -0,0 +1,12 @@
+/**
+ * POST /synthesize route handler.
+ *
+ * Path-targeted triggers create explicit override entries in the queue.
+ * Corpus-wide triggers discover the stalest candidate.
+ *
+ * @module routes/synthesize
+ */
+import type { FastifyInstance } from 'fastify';
+import type { RouteDeps } from './index.js';
+/** Register the POST /synthesize route. */
+export declare function registerSynthesizeRoute(app: FastifyInstance, deps: RouteDeps): void;

package/dist/routes/unlock.d.ts

@@ -0,0 +1,8 @@
+/**
+ * POST /unlock — remove .lock from a .meta/ directory.
+ *
+ * @module routes/unlock
+ */
+import type { FastifyInstance } from 'fastify';
+import type { RouteDeps } from './index.js';
+export declare function registerUnlockRoute(app: FastifyInstance, deps: RouteDeps): void;

package/dist/rules/healthCheck.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Periodic watcher health check for rule registration resilience.
+ *
+ * Pings watcher `/status` on a configurable interval, detects restarts
+ * (uptime decrease), and re-registers virtual rules automatically.
+ * Independent of the synthesis scheduler.
+ *
+ * @module rules/healthCheck
+ */
+import type { Logger } from 'pino';
+import type { RuleRegistrar } from './index.js';
+/**
+ * Manages the periodic watcher health check loop.
+ *
+ * Starts a `setInterval` that pings the watcher and delegates
+ * restart detection to `RuleRegistrar.checkAndReregister()`.
+ */
+export declare class WatcherHealthCheck {
+    private readonly watcherUrl;
+    private readonly intervalMs;
+    private readonly registrar;
+    private readonly logger;
+    private handle;
+    constructor(opts: {
+        watcherUrl: string;
+        intervalMs: number;
+        registrar: RuleRegistrar;
+        logger: Logger;
+    });
+    /** Start the periodic health check. No-op if intervalMs is 0. */
+    start(): void;
+    /** Stop the periodic health check. */
+    stop(): void;
+    /** Single health check iteration. */
+    private check;
+}

package/dist/rules/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Virtual rule registration with jeeves-watcher.
+ *
+ * Service registers inference rules at startup (with retry) and
+ * re-registers opportunistically when watcher restart is detected.
+ *
+ * @module rules
+ */
+import type { Logger } from 'pino';
+import type { WatcherClient } from '../interfaces/index.js';
+import type { MetaConfig } from '../schema/config.js';
+/**
+ * Manages virtual rule registration with watcher.
+ *
+ * - Registers at startup with exponential retry
+ * - Tracks watcher uptime for restart detection
+ * - Re-registers opportunistically when uptime decreases
+ */
+export declare class RuleRegistrar {
+    private readonly config;
+    private readonly logger;
+    private readonly watcherClient;
+    private lastWatcherUptime;
+    private registered;
+    constructor(config: MetaConfig, logger: Logger, watcher: WatcherClient);
+    /** Whether rules have been successfully registered. */
+    get isRegistered(): boolean;
+    /**
+     * Register rules with watcher. Retries with exponential backoff.
+     * Non-blocking — logs errors but never throws.
+     */
+    register(): Promise<void>;
+    /**
+     * Check watcher uptime and re-register if it decreased (restart detected).
+     *
+     * @param currentUptime - Current watcher uptime in seconds.
+     */
+    checkAndReregister(currentUptime: number): Promise<void>;
+}

package/dist/rules/verify.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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
+ */
+import type { WatcherClient } from '../interfaces/index.js';
+import type { MinimalLogger } from '../logger/index.js';
+/**
+ * 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.
+ */
+export declare function verifyRuleApplication(watcher: WatcherClient, logger: MinimalLogger): Promise<number>;