instar 1.3.490 → 1.3.492

package/dist/server/routes.js

@@ -32,6 +32,10 @@ import { CoherenceJournalReader, InvalidCursorError } from '../core/CoherenceJou
 import { creditUsherOnOutbound } from '../core/UsherActedCorrelator.js';
 import { validateWriteToken, canPerformOperation } from '../core/StateWriteAuthority.js';
 import { DegradationReporter } from '../monitoring/DegradationReporter.js';
+import { readGuardPostureBootSnapshot, resolveGuardConfigSnapshot, } from '../monitoring/guardPosture.js';
+import { buildGuardInventory } from '../monitoring/guardPostureView.js';
+import { GuardRegistry } from '../monitoring/GuardRegistry.js';
+import { isPeerUrlAllowedForCredentials } from './peerUrlGuard.js';
 import { FailureLedger } from '../monitoring/FailureLedger.js';
 import { FailureAttributionEngine } from '../monitoring/FailureAttributionEngine.js';
 import { FailureAnalyzer } from '../monitoring/FailureAnalyzer.js';
@@ -3496,20 +3500,70 @@ export function createRoutes(ctx) {
     // Cartographer doc-tree — hierarchical, semantic map of the codebase with
     // git-hash staleness derivation (cartographer-doc-tree-schema spec #1). Ships
     // dark behind cartographer.enabled (503 when disabled). Read-only — authoring
-    // is in-process only. Routes lazy-scaffold the structural skeleton on first use.
+    // is in-process only.
+    //
+    // fix instar#1069: NO request path runs an O(nodeCount)/67MB synchronous op on
+    // the event loop. /health + /stale serve the per-host SNAPSHOT the sweep writes;
+    // /tree is byte-bounded (too-large-for-request above the ceiling); the lazy
+    // scaffold()/loadIndex() preamble is GONE (routes serve indexState:'not-built'
+    // when no index exists — the boot-path chunked scaffold builds it off-request).
+    // The Slice-5 callsite lint forbids loadIndex/staleNodes/freshnessHealth/scaffold
+    // here, so this regression cannot return by accident.
+    /** Snapshot-enum + provenance, computed cheaply (one `git rev-parse --short HEAD`). */
+    const cartoSnapshotMeta = (snap) => {
+        if (!snap) {
+            return { snapshot: 'absent', snapshotStale: true, ageMs: null, headMoved: false, lastDetectStatus: null, lastDetectAt: null, headSha: null };
+        }
+        const currentHead = ctx.cartographer ? ctx.cartographer.currentHeadShort() : null;
+        const headMoved = snap.headSha != null && currentHead != null && snap.headSha !== currentHead;
+        const ageMs = snap.generatedAt ? Math.max(0, Date.now() - Date.parse(snap.generatedAt)) : null;
+        const failing = snap.lastDetectStatus !== 'ok';
+        return {
+            snapshot: failing ? 'detect-failing' : 'present',
+            snapshotStale: headMoved || failing,
+            ageMs,
+            headMoved,
+            lastDetectStatus: snap.lastDetectStatus,
+            lastDetectAt: snap.lastDetectAt,
+            headSha: snap.headSha,
+        };
+    };
     router.get('/cartographer/tree', (req, res) => {
         if (!ctx.cartographer) {
             res.status(503).json({ error: 'Cartographer not enabled' });
             return;
         }
-        let index = ctx.cartographer.loadIndex();
-        if (!index)
-            index = ctx.cartographer.scaffold();
+        const snap = ctx.cartographer.readSnapshot();
         if (req.query.format === 'compact') {
-            res.json({ root: index.root, generatedAt: index.generatedAt, nodeCount: Object.keys(index.nodes).length });
+            // Cheap: nodeCount + generatedAt from the snapshot (no index parse).
+            res.json({
+                root: '',
+                generatedAt: snap?.generatedAt ?? null,
+                nodeCount: snap?.counts.nodeCount ?? 0,
+                indexState: snap ? 'built' : 'not-built',
+                ...cartoSnapshotMeta(snap),
+            });
+            return;
+        }
+        // Full index: byte-bounded so a huge tree never triggers the 67MB sync parse.
+        const fsCfg = ctx.config.cartographer?.freshnessSweep;
+        const maxRequestNodes = typeof fsCfg?.maxRequestNodes === 'number' ? fsCfg.maxRequestNodes : 50000;
+        const byteCeiling = maxRequestNodes * 512; // generous per-entry estimate
+        const loaded = ctx.cartographer.loadIndexBounded(byteCeiling);
+        if (loaded.state === 'not-built') {
+            res.json({ root: '', generatedAt: null, nodeCount: 0, indexState: 'not-built', ...cartoSnapshotMeta(snap) });
             return;
         }
-        res.json(index);
+        if (loaded.state === 'too-large') {
+            res.json({
+                indexState: 'too-large-for-request',
+                nodeCount: snap?.counts.nodeCount ?? null,
+                guidance: 'index too large to serve whole; use GET /cartographer/navigate?query=... for a bounded subtree',
+                ...cartoSnapshotMeta(snap),
+            });
+            return;
+        }
+        res.json(loaded.index);
     });
     router.get('/cartographer/node', (req, res) => {
         if (!ctx.cartographer) {
@@ -3523,11 +3577,10 @@ export function createRoutes(ctx) {
             res.status(400).json({ error: 'invalid path' });
             return;
         }
-        if (!ctx.cartographer.loadIndex())
-            ctx.cartographer.scaffold();
+        // getNode reads ONE node file (O(1)) — no index parse, no scaffold preamble.
         const node = ctx.cartographer.getNode(p);
         if (!node) {
-            res.status(404).json({ error: 'no such node' });
+            res.status(404).json({ error: 'no such node', indexState: ctx.cartographer.readSnapshot() ? 'built' : 'not-built' });
             return;
         }
         res.json(node);
@@ -3537,29 +3590,57 @@ export function createRoutes(ctx) {
             res.status(503).json({ error: 'Cartographer not enabled' });
             return;
         }
-        if (!ctx.cartographer.loadIndex())
-            ctx.cartographer.scaffold();
-        const nodes = ctx.cartographer.staleNodes();
-        res.json({ count: nodes.length, nodes });
+        const snap = ctx.cartographer.readSnapshot();
+        const meta = cartoSnapshotMeta(snap);
+        if (!snap) {
+            res.json({ count: 0, nodes: [], total: 0, truncated: false, ...meta });
+            return;
+        }
+        // Serve the bounded, secret-filtered sample with the honest total + truncation.
+        const reasonFor = (s) => s === 'never-authored' ? 'no summary authored yet'
+            : s === 'stale' ? 'code changed since the summary was authored'
+                : s === 'path-gone' ? 'covered path no longer in HEAD' : '';
+        const nodes = snap.staleSample.map((e) => ({ path: e.path, status: e.status, reason: reasonFor(e.status) }));
+        res.json({ count: nodes.length, nodes, total: snap.staleTotal, truncated: snap.staleSampleTruncated, ...meta });
     });
     router.get('/cartographer/health', (_req, res) => {
         if (!ctx.cartographer) {
             res.status(503).json({ error: 'Cartographer not enabled' });
             return;
         }
-        if (!ctx.cartographer.loadIndex())
-            ctx.cartographer.scaffold();
         const sweepCfg = ctx.config
             .cartographer?.freshnessSweep;
-        // Spec #2: surface the freshness ratio + the two ABSOLUTE backlog counts so a
-        // green ratio can't hide a growing un-authored/quarantined backlog. Grace =
-        // one cadence so a just-scaffolded node isn't counted as debt immediately.
-        const graceMs = (sweepCfg?.cadenceMs ?? 600000) * 2;
+        const snap = ctx.cartographer.readSnapshot();
+        const meta = cartoSnapshotMeta(snap);
+        // fix instar#1069: the entire freshness block is served from the SNAPSHOT — the
+        // route never calls health()/freshnessHealth() (the request-thread starvers).
+        // Legacy field names/semantics are preserved (additive contract); new fields
+        // carry snapshot provenance so a stale/failing detect is visible on the route.
+        if (!snap) {
+            res.json({
+                enabled: true,
+                nodeCount: 0, authoredCount: 0, neverAuthoredCount: 0, staleCount: 0, generatedAt: null,
+                freshness: {
+                    nodeCount: 0, authorableCount: 0, freshCount: 0, staleCount: 0, neverAuthoredCount: 0,
+                    neverAuthoredWithinGrace: 0, neverAuthoredPastGrace: 0, authorFailedCount: 0, freshRatio: 1, generatedAt: null,
+                },
+                sweepEnabled: sweepCfg?.enabled === true,
+                ...meta,
+            });
+            return;
+        }
         res.json({
             enabled: true,
-            ...ctx.cartographer.health(),
-            freshness: ctx.cartographer.freshnessHealth({ graceMs }),
+            // Legacy health() fields, sourced from the snapshot:
+            nodeCount: snap.counts.nodeCount,
+            authoredCount: snap.counts.authoredCount,
+            neverAuthoredCount: snap.counts.neverAuthored,
+            staleCount: snap.counts.stale,
+            generatedAt: snap.generatedAt,
+            // Legacy freshnessHealth() block, sourced from the snapshot:
+            freshness: snap.freshness,
             sweepEnabled: sweepCfg?.enabled === true,
+            ...meta,
         });
     });
     // Tier-1 (inline opportunistic) write route (spec #2 — doc-freshness). The ONE
@@ -3610,8 +3691,8 @@ export function createRoutes(ctx) {
             res.status(400).json({ error: 'invalid summary' });
             return;
         }
-        if (!ctx.cartographer.loadIndex())
-            ctx.cartographer.scaffold();
+        // fix instar#1069: no lazy scaffold()/loadIndex() preamble — getNode is a single
+        // node-file read. An un-scaffolded node 400s (the boot scaffold builds the index).
         const node = ctx.cartographer.getNode(p);
         if (!node) {
             res.status(400).json({ error: 'no such node — only an existing scaffolded node can be refreshed' });
@@ -3688,8 +3769,9 @@ export function createRoutes(ctx) {
             res.status(400).json({ error: 'maxResults out of range (1..500)' });
             return;
         }
-        if (!ctx.cartographer.loadIndex())
-            ctx.cartographer.scaffold();
+        // fix instar#1069: no lazy scaffold()/loadIndex() preamble — the navigator is
+        // bounded (maxNodesVisited) and returns an empty manifest when the root node is
+        // absent (index not built yet); the boot-path scaffold builds it off-request.
         const manifest = cartographerNavigate(ctx.cartographer, query, {
             maxDepth: maxDepthOverride ?? navCfg.maxDepth,
             branchingFactor: navCfg.branchingFactor,
@@ -4270,6 +4352,138 @@ export function createRoutes(ctx) {
         const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(Math.floor(rawLimit), 1000) : 200;
         res.json({ entries: ctx.reapLog.read(limit) });
     });
+    // ── Guard Posture (GUARD-POSTURE-ENDPOINT-SPEC) ─────────────────────
+    // Read-only, Bearer-auth (router-level middleware — NEVER added to any auth
+    // exemption list: posture is an attack-timing oracle, spec §3). Reports
+    // every shipped guard's HONEST effective state: config-on is not working
+    // (the Mini's reaper lesson). Local inventory is fully synchronous (one
+    // disk-read config snapshot + sync in-memory runtime getters, <100ms);
+    // ?scope=pool fans out to peers with classified per-peer failures, never a
+    // 500. Deliberately NO `guards.enabled` config gate — an off-switch on the
+    // guard-visibility surface would itself be an invisible disabled guard
+    // (always-on read-only observability; reap-log/TokenLedger precedent).
+    const guardsPoolLimiter = rateLimiter(60_000, 6);
+    router.get('/guards', async (req, res) => {
+        const stateDir = ctx.config.stateDir;
+        const projectDir = path.dirname(stateDir);
+        const snapshot = resolveGuardConfigSnapshot(projectDir);
+        if (snapshot.readError) {
+            // Config-read failure is a top-level error — never a truthful-looking
+            // empty inventory (spec §2.2).
+            res.status(500).json({ error: `guard inventory unavailable: config read failed (${snapshot.readError})` });
+            return;
+        }
+        const inventory = buildGuardInventory({
+            snapshot,
+            bootSnapshot: readGuardPostureBootSnapshot(stateDir),
+            registry: ctx.guardRegistry ?? new GuardRegistry(),
+        });
+        const selfMachineId = ctx.meshSelfId ?? null;
+        const body = {
+            machineId: selfMachineId,
+            nickname: selfMachineId
+                ? (ctx.machinePoolRegistry?.getCapacity(selfMachineId)?.nickname ?? null)
+                : null,
+            version: ProcessIntegrity.getInstance()?.runningVersion || ctx.config.version || '0.0.0',
+            generatedAt: new Date().toISOString(),
+            guards: inventory.guards,
+            summary: inventory.summary,
+        };
+        if (req.query.scope !== 'pool') {
+            res.json(body);
+            return;
+        }
+        // scope=pool — every registered machine accounted for: a posture row or a
+        // NAMED, classified failure row; silent omission re-creates the blind spot
+        // at the pool level (spec §2.3). Non-recursive (peers get plain /guards),
+        // rate-limited (anti-amplification, spec §3(d)).
+        guardsPoolLimiter(req, res, async () => {
+            const known = (ctx.listPoolMachines?.() ?? []).filter((m) => m.machineId !== selfMachineId);
+            if (known.length === 0) {
+                res.json({ ...body, pool: { enabled: false, peersQueried: 0, knownMachines: 0, machines: [], failed: [] } });
+                return;
+            }
+            const extraAllowlist = ctx.config.multiMachine
+                ?.peerUrlAllowlist;
+            const machines = [];
+            const failed = [];
+            let peersQueried = 0;
+            await Promise.all(known.map(async (m) => {
+                const capacity = ctx.machinePoolRegistry?.getCapacity(m.machineId) ?? null;
+                const peerVersion = capacity?.hardware?.instarVersion;
+                if (!m.lastKnownUrl) {
+                    failed.push({ machineId: m.machineId, reason: 'no-known-url' });
+                    return;
+                }
+                if (capacity && capacity.online === false) {
+                    // The heartbeat piggyback (durable last-known posture on the pool
+                    // view) covers dark peers — a doomed fetch buys nothing but timeout.
+                    failed.push({ machineId: m.machineId, reason: 'offline' });
+                    return;
+                }
+                const verdict = isPeerUrlAllowedForCredentials(m.lastKnownUrl, extraAllowlist);
+                if (!verdict.ok) {
+                    // The Bearer token was NEVER attached (spec §3(c)) — visible, named.
+                    failed.push({ machineId: m.machineId, reason: 'url-rejected' });
+                    return;
+                }
+                peersQueried++;
+                try {
+                    const r = await fetch(`${m.lastKnownUrl}/guards`, {
+                        headers: { Authorization: `Bearer ${ctx.config.authToken}` },
+                        signal: AbortSignal.timeout(5000),
+                    });
+                    if (r.status === 404) {
+                        // Pre-/guards peer version: "needs update to report", not a
+                        // phantom outage (rollout-skew honesty, spec §2.3).
+                        failed.push({ machineId: m.machineId, reason: 'route-missing', ...(peerVersion ? { version: peerVersion } : {}) });
+                        return;
+                    }
+                    if (r.status === 401 || r.status === 403) {
+                        failed.push({ machineId: m.machineId, reason: 'unauthorized' });
+                        return;
+                    }
+                    if (!r.ok) {
+                        failed.push({ machineId: m.machineId, reason: 'error' });
+                        return;
+                    }
+                    const peerBody = (await r.json());
+                    machines.push({
+                        // Merge identity: the row is keyed on the REGISTRY's machine
+                        // identity; the body's self-reported machineId is data and a
+                        // mismatch is FLAGGED, never allowed to shadow another row.
+                        machineId: m.machineId,
+                        nickname: capacity?.nickname ?? m.nickname,
+                        ...(typeof peerBody.machineId === 'string' && peerBody.machineId !== m.machineId
+                            ? { identityMismatch: true, claimedMachineId: peerBody.machineId }
+                            : {}),
+                        version: peerBody.version,
+                        generatedAt: peerBody.generatedAt,
+                        guards: peerBody.guards,
+                        summary: peerBody.summary,
+                    });
+                }
+                catch (err) {
+                    // Normalized enum only — raw err.message leaks URL/TLS internals.
+                    const name = err instanceof Error ? err.name : '';
+                    failed.push({
+                        machineId: m.machineId,
+                        reason: name === 'TimeoutError' || name === 'AbortError' ? 'timeout' : 'unreachable',
+                    });
+                }
+            }));
+            res.json({
+                ...body,
+                pool: {
+                    enabled: !!ctx.machinePoolRegistry,
+                    knownMachines: known.length,
+                    peersQueried,
+                    machines,
+                    failed,
+                },
+            });
+        });
+    });
     // Coherence Journal merged read API (COHERENCE-JOURNAL-SPEC §3.5). The
     // pull-surface answer to "which machine was topic N on / where are its
     // artifacts?" — a bounded, honest-about-trust merged view over this machine's