@karmaniverous/jeeves-meta 0.20.0-1 → 0.20.0

package/README.md

@@ -56,7 +56,7 @@ jeeves-meta service install --config /path/to/jeeves-meta/config.json
 
 | Method | Path | Description |
 | --- | --- | --- |
-| GET | `/status` | Service health, queue state, dependency checks, phase-state summary |
+| GET | `/status` | Service health, queue state, dependency checks, phase-state summary. Meta counts come from the last meta list (at most 60 s old, refreshed in the background), so the check never waits on a corpus walk. |
 | GET | `/metas` | List metas with summary stats and per-meta projection. Response includes `phaseState` and `owedPhase` per meta. |
 | GET | `/metas/:path` | Full detail for a single meta, with optional archive history. Response includes `phaseState`, `owedPhase` and `crossRefs`. |
 | GET | `/preview` | Dry-run: preview inputs for next synthesis |
@@ -71,7 +71,7 @@ jeeves-meta service install --config /path/to/jeeves-meta/config.json
 | PATCH | `/metas/:path` | Update user-settable reserved properties (`_steer`, `_emphasis`, `_depth`, `_crossRefs`, `_disabled`) |
 | GET | `/openapi.json` | The OpenAPI 3.1 document of every route above |
 
-Every route is defined in `META_CATALOG` (`@karmaniverous/jeeves-meta-core`) and validated against it: a malformed request is answered 400 `FST_ERR_VALIDATION`. Every route except `/config`, `/config/apply` and `/openapi.json` answers 503 `META_NOT_READY` while the service starts. Use [`@karmaniverous/jeeves-meta-sdk`](../sdk/README.md) for a typed client.
+Every route is defined in `META_CATALOG` (`@karmaniverous/jeeves-meta-core`) and validated against it: a malformed request is answered 400 `FST_ERR_VALIDATION`. While the service starts, `GET /status` answers 200 with `serviceState: "starting"` (no meta counts until the first meta list loads), `/config`, `/config/apply` and `/openapi.json` are served, and every other route answers 503 `META_NOT_READY`. Use [`@karmaniverous/jeeves-meta-sdk`](../sdk/README.md) for a typed client.
 
 ### Errors
 

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

@@ -657,7 +657,8 @@ function getDeltaFiles(generatedAt, scopeFiles) {
 }
 
 /**
- * In-memory cache for listMetas results with TTL and concurrent refresh guard.
+ * In-memory cache for listMetas results with TTL, concurrent refresh guard
+ * and a non-blocking read (`peek`) for health checks.
  *
  * @module cache
  */
@@ -677,6 +678,22 @@ class MetaCache {
         }
         return this.refresh(config, watcher);
     }
+    /**
+     * The cached result without waiting on a stale one: when it has expired,
+     * return it anyway and refresh in the background. Only the first load,
+     * with nothing cached yet, is awaited. For callers that must answer fast
+     * (`GET /status`), where a 60 s-old list is good enough.
+     */
+    async peek(config, watcher) {
+        if (!this.result)
+            return this.refresh(config, watcher);
+        if (Date.now() - this.updatedAt >= TTL_MS) {
+            // A failed background refresh keeps the old result; the next caller
+            // retries it.
+            this.refresh(config, watcher).catch(() => undefined);
+        }
+        return this.result;
+    }
     /** Force-expire the cache so next get() triggers a refresh. */
     invalidate() {
         this.updatedAt = 0;
@@ -31854,6 +31871,8 @@ async function checkWatcher(url) {
 function deriveServiceState(deps) {
     if (deps.shuttingDown)
         return 'stopping';
+    if (!deps.ready)
+        return 'starting';
     if (deps.queue.currentPhase)
         return 'synthesizing';
     if (deps.queue.depth > 0)
@@ -31888,41 +31907,47 @@ function createStatusHandlers(deps) {
             };
             let nextPhase = null;
             let metaCounts = null;
-            try {
-                const metaResult = await cache.get(config, watcher);
-                // Count raw phase states (before retry) for display
-                for (const entry of metaResult.entries) {
-                    const ps = derivePhaseState(entry.meta);
-                    for (const phase of ['architect', 'builder', 'critic']) {
-                        phaseStateSummary[phase][ps[phase]]++;
+            // While starting, the first meta list is still loading: report the
+            // state, dependencies and stats without it (Decision 199).
+            if (deps.ready) {
+                try {
+                    // Never wait on a refresh of the whole corpus: a health check answers
+                    // from the last list, refreshed in the background.
+                    const metaResult = await cache.peek(config, watcher);
+                    // Count raw phase states (before retry) for display
+                    for (const entry of metaResult.entries) {
+                        const ps = derivePhaseState(entry.meta);
+                        for (const phase of ['architect', 'builder', 'critic']) {
+                            phaseStateSummary[phase][ps[phase]]++;
+                        }
                     }
-                }
-                // Build candidates (with auto-retry) for scheduling
-                const candidates = buildPhaseCandidates(metaResult.entries, config.architectEvery);
-                // Find next phase candidate
-                const winner = selectPhaseCandidate(candidates, config.depthWeight);
-                if (winner) {
-                    nextPhase = {
-                        path: winner.node.metaPath,
-                        phase: winner.owedPhase,
-                        band: winner.band,
-                        staleness: finiteOrNull(winner.effectiveStaleness),
+                    // Build candidates (with auto-retry) for scheduling
+                    const candidates = buildPhaseCandidates(metaResult.entries, config.architectEvery);
+                    // Find next phase candidate
+                    const winner = selectPhaseCandidate(candidates, config.depthWeight);
+                    if (winner) {
+                        nextPhase = {
+                            path: winner.node.metaPath,
+                            phase: winner.owedPhase,
+                            band: winner.band,
+                            staleness: finiteOrNull(winner.effectiveStaleness),
+                        };
+                    }
+                    // Meta counts summary
+                    const summary = computeSummary(metaResult.entries, config.depthWeight);
+                    metaCounts = {
+                        total: summary.total,
+                        enabled: summary.total - summary.disabled,
+                        disabled: summary.disabled,
+                        neverSynthesized: summary.neverSynthesized,
+                        stale: summary.stale,
+                        errors: summary.errors,
+                        locked: summary.locked,
                     };
                 }
-                // Meta counts summary
-                const summary = computeSummary(metaResult.entries, config.depthWeight);
-                metaCounts = {
-                    total: summary.total,
-                    enabled: summary.total - summary.disabled,
-                    disabled: summary.disabled,
-                    neverSynthesized: summary.neverSynthesized,
-                    stale: summary.stale,
-                    errors: summary.errors,
-                    locked: summary.locked,
-                };
-            }
-            catch {
-                // Watcher unreachable — phase summary unavailable
+                catch {
+                    // Watcher unreachable — phase summary unavailable
+                }
             }
             return {
                 serviceState: deriveServiceState(deps),
@@ -32169,7 +32194,12 @@ function registerRoutes(app, deps) {
  * @module server
  */
 /** Routes served while the service is starting (matched route URLs). */
-const UNGATED_ROUTES = new Set(['/config', '/config/apply', '/openapi.json']);
+const UNGATED_ROUTES = new Set([
+    '/status',
+    '/config',
+    '/config/apply',
+    '/openapi.json',
+]);
 /**
  * Create and configure the Fastify server.
  *
@@ -32400,9 +32430,10 @@ async function startService(config, configPath, configApply) {
     queue.onEnqueue(() => {
         void queue.processQueue(synthesizeFn);
     });
-    // Startup: clean stale locks (gap #16)
+    // Startup: clean stale locks (gap #16). Through the cache, so the first
+    // GET /status after start-up answers without a second walk.
     try {
-        const metaResult = await listMetas(config, watcher);
+        const metaResult = await cache.get(config, watcher);
         const metaPaths = metaResult.entries.map((e) => e.node.metaPath);
         cleanupStaleLocks(metaPaths, logger);
     }

package/package.json

@@ -8,8 +8,8 @@
   },
   "dependencies": {
     "@karmaniverous/jeeves": "0.11.0",
-    "@karmaniverous/jeeves-meta-core": "^0.4.0-0",
-    "@karmaniverous/jeeves-meta-sdk": "^0.0.0 || ^0.1.0-0",
+    "@karmaniverous/jeeves-meta-core": "^0.4.0",
+    "@karmaniverous/jeeves-meta-sdk": "^0.1.0",
     "@karmaniverous/jeeves-watcher-sdk": "^0.4.1",
     "commander": "^15",
     "croner": "^10",
@@ -112,5 +112,5 @@
     "wire:record": "vitest run --config vitest.wire-record.config.ts"
   },
   "type": "module",
-  "version": "0.20.0-1"
+  "version": "0.20.0"
 }