@karmaniverous/jeeves-meta 0.15.4 → 0.15.6

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

package/dist/scheduler/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Croner-based scheduler that discovers the highest-priority ready phase
+ * across the corpus each tick and enqueues it for execution.
+ *
+ * @module scheduler
+ */
+import type { Logger } from 'pino';
+import type { MetaCache } from '../cache.js';
+import type { SynthesisQueue } from '../queue/index.js';
+import type { RuleRegistrar } from '../rules/index.js';
+import type { ServiceConfig } from '../schema/config.js';
+import type { HttpWatcherClient } from '../watcher-client/index.js';
+/** Result of a scheduler tick's candidate discovery. */
+export interface TickCandidate {
+    path: string;
+    phase: 'architect' | 'builder' | 'critic';
+    band: number;
+}
+/**
+ * Periodic scheduler that discovers the highest-priority ready phase
+ * across all metas and enqueues it for execution.
+ *
+ * Supports adaptive backoff when no candidates are found and hot-reloadable
+ * cron expressions via {@link Scheduler.updateSchedule}.
+ */
+export declare class Scheduler {
+    private job;
+    private backoffMultiplier;
+    private tickCount;
+    private readonly config;
+    private readonly queue;
+    private readonly logger;
+    private readonly watcher;
+    private readonly cache;
+    private registrar;
+    private currentExpression;
+    constructor(config: ServiceConfig, queue: SynthesisQueue, logger: Logger, watcher: HttpWatcherClient, cache: MetaCache);
+    /** Set the rule registrar for watcher restart detection. */
+    setRegistrar(registrar: RuleRegistrar): void;
+    /** Start the cron job. */
+    start(): void;
+    /** Stop the cron job. */
+    stop(): void;
+    /** Hot-reload the cron schedule expression. */
+    updateSchedule(expression: string): void;
+    /** Reset backoff multiplier (call after successful phase execution). */
+    resetBackoff(): void;
+    /** Whether the scheduler is currently running. */
+    get isRunning(): boolean;
+    /** Next scheduled tick time, or null if not running. */
+    get nextRunAt(): Date | null;
+    /**
+     * Single tick: discover the highest-priority ready phase and enqueue it.
+     *
+     * Applies adaptive backoff when no candidates are found.
+     */
+    private tick;
+    /**
+     * Discover the highest-priority ready phase across the corpus.
+     *
+     * Uses phase-state-aware scheduling: priority order is
+     * critic (band 1) \> builder (band 2) \> architect (band 3),
+     * with weighted staleness as tiebreaker within a band.
+     */
+    private discoverNextPhase;
+}

package/dist/scheduling/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Scheduling module — staleness detection and candidate selection.
+ *
+ * @module scheduling
+ */
+export { actualStaleness, computeStalenessScore, hasSteerChanged, isArchitectTriggered, isStale, MAX_STALENESS_SECONDS, } from './staleness.js';
+export { computeEffectiveStaleness, type StalenessCandidate, } from './weightedFormula.js';

package/dist/scheduling/staleness.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Staleness detection via watcher walk.
+ *
+ * A meta is stale when any watched file in its scope was modified after
+ * `_generatedAt`.
+ *
+ * @module scheduling/staleness
+ */
+import type { WatcherClient } from '../interfaces/index.js';
+import type { MetaJson } from '../schema/index.js';
+/**
+ * Check if a meta is stale.
+ *
+ * Uses watcher `/walk` to enumerate watched files under the scope prefix,
+ * then applies a local mtime check (fast) to detect any modifications since
+ * `_generatedAt`. Short-circuits on first match.
+ *
+ * @param scopePrefix - Path prefix for this meta's scope.
+ * @param meta - Current meta.json content.
+ * @param watcher - WatcherClient instance.
+ * @returns True if any file in scope was modified after `_generatedAt`.
+ */
+export declare function isStale(scopePrefix: string, meta: MetaJson, watcher: WatcherClient): Promise<boolean>;
+/** Maximum staleness for never-synthesized metas (1 year in seconds). */
+export declare const MAX_STALENESS_SECONDS: number;
+/**
+ * Compute actual staleness in seconds (now minus _generatedAt).
+ *
+ * Never-synthesized metas are capped at {@link MAX_STALENESS_SECONDS}
+ * (1 year) so that depth weighting can differentiate them. Without
+ * bounding, `Infinity * depthFactor` = `Infinity` for all depths.
+ *
+ * @param meta - Current meta.json content.
+ * @returns Staleness in seconds, capped at 1 year for never-synthesized metas.
+ */
+export declare function actualStaleness(meta: MetaJson): number;
+/**
+ * Check whether the architect step should be triggered.
+ *
+ * @param meta - Current meta.json.
+ * @param structureChanged - Whether the structure hash changed.
+ * @param steerChanged - Whether the steer directive changed.
+ * @param architectEvery - Config: run architect every N cycles.
+ * @returns True if the architect step should run.
+ */
+export declare function isArchitectTriggered(meta: MetaJson, structureChanged: boolean, steerChanged: boolean, architectEvery: number): boolean;
+/**
+ * Detect whether the steer directive changed since the last archive.
+ *
+ * @param currentSteer - Current _steer value (or undefined).
+ * @param archiveSteer - Archive _steer value (or undefined).
+ * @param hasArchive - Whether an archive snapshot exists.
+ * @returns True if steer changed.
+ */
+export declare function hasSteerChanged(currentSteer: string | undefined, archiveSteer: string | undefined, hasArchive: boolean): boolean;
+/**
+ * Compute a normalized staleness score (0–1) for display purposes.
+ *
+ * Uses the same depth/emphasis weighting as candidate selection,
+ * normalized to a 30-day window.
+ *
+ * @param stalenessSeconds - Raw staleness in seconds (null = never synthesized).
+ * @param depth - Meta tree depth.
+ * @param emphasis - Scheduling emphasis multiplier.
+ * @param depthWeight - Depth weighting exponent from config.
+ * @returns Normalized score between 0 and 1.
+ */
+export declare function computeStalenessScore(stalenessSeconds: number | null, depth: number, emphasis: number, depthWeight: number): number;

package/dist/scheduling/weightedFormula.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Weighted staleness formula for candidate selection.
+ *
+ * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ *
+ * @module scheduling/weightedFormula
+ */
+import type { MetaNode } from '../discovery/index.js';
+import type { MetaJson } from '../schema/index.js';
+/** A candidate meta with computed staleness. */
+export interface StalenessCandidate {
+    /** The meta node. */
+    node: MetaNode;
+    /** Current meta.json content. */
+    meta: MetaJson;
+    /** Actual staleness in seconds. */
+    actualStaleness: number;
+    /** Effective staleness after depth weighting. */
+    effectiveStaleness: number;
+}
+/**
+ * Compute effective staleness for a set of candidates.
+ *
+ * Normalizes depths so the minimum becomes 0, then applies the formula:
+ * effectiveStaleness = actualStaleness * (normalizedDepth + 1) ^ (depthWeight * emphasis)
+ *
+ * Per-meta _emphasis (default 1) multiplies depthWeight, allowing individual
+ * metas to tune how much their tree position affects scheduling.
+ *
+ * @param candidates - Array of \{ node, meta, actualStaleness \}.
+ * @param depthWeight - Exponent for depth weighting (0 = pure staleness).
+ * @returns Same array with effectiveStaleness computed.
+ */
+export declare function computeEffectiveStaleness(candidates: Array<{
+    node: MetaNode;
+    meta: MetaJson;
+    actualStaleness: number;
+}>, depthWeight: number): StalenessCandidate[];