@astragenie/astramemory-local 0.7.2

package/dist/server/health-state.d.ts

@@ -0,0 +1,29 @@
+/**
+ * health-state.ts — mutable per-daemon health snapshot (D3).
+ *
+ * Written by the boot sequence, the background embed prober, and the job
+ * worker; read by the /health route. Enables degraded-start: the daemon
+ * binds its port immediately and reports 'starting' → 'ok' | 'degraded'
+ * instead of dying when Ollama is slow to load a model at logon.
+ */
+export type DaemonStatus = 'starting' | 'ok' | 'degraded';
+export interface EmbedHealth {
+    /** null = not probed yet (starting); true/false = last probe outcome. */
+    ok: boolean | null;
+    lastOkAt: number | null;
+    lastError: string | null;
+    attempts: number;
+}
+export interface WorkerHealth {
+    lastTickAt: number | null;
+}
+export interface HealthState {
+    readonly startedAt: number;
+    embed: EmbedHealth;
+    worker: WorkerHealth;
+    /** Resolved data directory — lets /health report disk_free_bytes. */
+    dataDir?: string;
+    status(): DaemonStatus;
+    uptimeSeconds(): number;
+}
+export declare function createHealthState(now?: () => number): HealthState;

package/dist/server/health-state.js

@@ -0,0 +1,28 @@
+/**
+ * health-state.ts — mutable per-daemon health snapshot (D3).
+ *
+ * Written by the boot sequence, the background embed prober, and the job
+ * worker; read by the /health route. Enables degraded-start: the daemon
+ * binds its port immediately and reports 'starting' → 'ok' | 'degraded'
+ * instead of dying when Ollama is slow to load a model at logon.
+ */
+export function createHealthState(now = Date.now) {
+    const startedAt = now();
+    const state = {
+        startedAt,
+        embed: { ok: null, lastOkAt: null, lastError: null, attempts: 0 },
+        worker: { lastTickAt: null },
+        status() {
+            if (state.embed.ok === true)
+                return 'ok';
+            if (state.embed.ok === null)
+                return 'starting';
+            return 'degraded';
+        },
+        uptimeSeconds() {
+            return Math.floor((now() - startedAt) / 1000);
+        },
+    };
+    return state;
+}
+//# sourceMappingURL=health-state.js.map

package/dist/server/health-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-state.js","sourceRoot":"","sources":["../../src/server/health-state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0BH,MAAM,UAAU,iBAAiB,CAAC,MAAoB,IAAI,CAAC,GAAG;IAC5D,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC;IACxB,MAAM,KAAK,GAAgB;QACzB,SAAS;QACT,KAAK,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE;QACjE,MAAM,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE;QAC5B,MAAM;YACJ,IAAI,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YACzC,IAAI,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,IAAI;gBAAE,OAAO,UAAU,CAAC;YAC/C,OAAO,UAAU,CAAC;QACpB,CAAC;QACD,aAAa;YACX,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC;QAChD,CAAC;KACF,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/server/lib/network.d.ts

@@ -0,0 +1,12 @@
+/**
+ * isLoopbackHost — the single predicate that decides both (a) whether the
+ * HTTP server binds beyond the local machine and (b) whether /health and
+ * /version stay public (FEAT-406).
+ *
+ * Deriving the auth boundary from the same value that controls the bind
+ * (rather than a second independent "require auth" flag) closes the gap the
+ * PM pre-mortem flagged: a config typo or partial rollout can no longer
+ * leave the daemon bound non-locally while /health/version stay
+ * unauthenticated — there is only one knob, not two that can disagree.
+ */
+export declare function isLoopbackHost(host: string): boolean;

package/dist/server/lib/network.js

@@ -0,0 +1,16 @@
+/**
+ * isLoopbackHost — the single predicate that decides both (a) whether the
+ * HTTP server binds beyond the local machine and (b) whether /health and
+ * /version stay public (FEAT-406).
+ *
+ * Deriving the auth boundary from the same value that controls the bind
+ * (rather than a second independent "require auth" flag) closes the gap the
+ * PM pre-mortem flagged: a config typo or partial rollout can no longer
+ * leave the daemon bound non-locally while /health/version stay
+ * unauthenticated — there is only one knob, not two that can disagree.
+ */
+export function isLoopbackHost(host) {
+    const h = host.trim().toLowerCase();
+    return h === '127.0.0.1' || h === 'localhost' || h === '::1';
+}
+//# sourceMappingURL=network.js.map

package/dist/server/lib/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../../src/server/lib/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,OAAO,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,KAAK,CAAC;AAC/D,CAAC"}

package/dist/server/lib/score-contract.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Response-side [0,1] score wire contract enforcement (FEAT-413/SLICE-411).
+ *
+ * fuseScores() (src/search/fuse.ts) is the only *intended* score producer
+ * today, but nothing stops a future second fusion strategy, a manual score
+ * override, or a stale cache read from constructing a hit whose score sits
+ * outside [0,1] (or is NaN/Infinity). This module enforces the contract at
+ * the JSON serialization boundary — independent of fuseScores() internal
+ * math — so an out-of-contract score is clamped and logged server-side
+ * instead of shipping invalid wire data that only the plugin's client-side
+ * Zod schema rejects (the cedc8a9 failure mode: plugin exit 3, daemon
+ * oblivious).
+ */
+export interface ScoreContractContext {
+    /** Route the score is being serialized for, e.g. 'GET /search'. */
+    route: string;
+    /** Id of the hit/memory the score belongs to. */
+    id: string;
+}
+/**
+ * Clamp a single score into [0,1]. Non-finite values map to a safe bound
+ * (NaN -> 0, +Infinity -> 1, -Infinity -> 0). Logs a structured warning with
+ * route + id context whenever the input was out of contract; in-contract
+ * values pass through unchanged with no log emitted (no noise on the happy
+ * path).
+ */
+export declare function clampScore(value: number, ctx: ScoreContractContext): number;
+/**
+ * Clamp scores across a list of hits/memories at a response serialization
+ * site. Returns the same item (same reference) when its score is already
+ * in-contract, so an untouched happy-path array is bit-identical.
+ */
+export declare function clampScores<T extends {
+    id: string;
+    score: number;
+}>(items: T[], route: string): T[];

package/dist/server/lib/score-contract.js

@@ -0,0 +1,54 @@
+/**
+ * Response-side [0,1] score wire contract enforcement (FEAT-413/SLICE-411).
+ *
+ * fuseScores() (src/search/fuse.ts) is the only *intended* score producer
+ * today, but nothing stops a future second fusion strategy, a manual score
+ * override, or a stale cache read from constructing a hit whose score sits
+ * outside [0,1] (or is NaN/Infinity). This module enforces the contract at
+ * the JSON serialization boundary — independent of fuseScores() internal
+ * math — so an out-of-contract score is clamped and logged server-side
+ * instead of shipping invalid wire data that only the plugin's client-side
+ * Zod schema rejects (the cedc8a9 failure mode: plugin exit 3, daemon
+ * oblivious).
+ */
+import { childLogger } from '../../log/logger.js';
+const log = childLogger({ component: 'score-contract' });
+/**
+ * Clamp a single score into [0,1]. Non-finite values map to a safe bound
+ * (NaN -> 0, +Infinity -> 1, -Infinity -> 0). Logs a structured warning with
+ * route + id context whenever the input was out of contract; in-contract
+ * values pass through unchanged with no log emitted (no noise on the happy
+ * path).
+ */
+export function clampScore(value, ctx) {
+    if (Number.isNaN(value)) {
+        log.warn({ route: ctx.route, id: ctx.id, value: 'NaN' }, 'score-contract: non-finite score clamped to 0');
+        return 0;
+    }
+    if (!Number.isFinite(value)) {
+        const clamped = value > 0 ? 1 : 0;
+        log.warn({ route: ctx.route, id: ctx.id, value: value > 0 ? 'Infinity' : '-Infinity' }, 'score-contract: non-finite score clamped');
+        return clamped;
+    }
+    if (value < 0) {
+        log.warn({ route: ctx.route, id: ctx.id, value }, 'score-contract: score below 0 clamped to 0');
+        return 0;
+    }
+    if (value > 1) {
+        log.warn({ route: ctx.route, id: ctx.id, value }, 'score-contract: score above 1 clamped to 1');
+        return 1;
+    }
+    return value;
+}
+/**
+ * Clamp scores across a list of hits/memories at a response serialization
+ * site. Returns the same item (same reference) when its score is already
+ * in-contract, so an untouched happy-path array is bit-identical.
+ */
+export function clampScores(items, route) {
+    return items.map(item => {
+        const clamped = clampScore(item.score, { route, id: item.id });
+        return clamped === item.score ? item : { ...item, score: clamped };
+    });
+}
+//# sourceMappingURL=score-contract.js.map

package/dist/server/lib/score-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-contract.js","sourceRoot":"","sources":["../../../src/server/lib/score-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC,CAAC;AASzD;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,GAAyB;IACjE,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,+CAA+C,CAAC,CAAC;QAC1G,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,0CAA0C,CAAC,CAAC;QACpI,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,4CAA4C,CAAC,CAAC;QAChG,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,4CAA4C,CAAC,CAAC;QAChG,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAA0C,KAAU,EAAE,KAAa;IAC5F,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;QACtB,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/D,OAAO,OAAO,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IACrE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/server/lib/stable-stringify.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical JSON stringification with sorted object keys.
+ * INPUT CONTRACT: caller must pass Zod-validated plain-JSON values only.
+ * Supported: null, boolean, number (finite), string, array (order preserved), plain object.
+ * UNSUPPORTED (throws or produces lossy output): Date, BigInt, Symbol, undefined,
+ * cyclic references, class instances. Feeding any of these is a programming error.
+ *
+ * Used by ingest route to hash request bodies for idempotency replay.
+ */
+export declare function stableStringify(value: unknown): string;

package/dist/server/lib/stable-stringify.js

@@ -0,0 +1,27 @@
+/**
+ * Canonical JSON stringification with sorted object keys.
+ * INPUT CONTRACT: caller must pass Zod-validated plain-JSON values only.
+ * Supported: null, boolean, number (finite), string, array (order preserved), plain object.
+ * UNSUPPORTED (throws or produces lossy output): Date, BigInt, Symbol, undefined,
+ * cyclic references, class instances. Feeding any of these is a programming error.
+ *
+ * Used by ingest route to hash request bodies for idempotency replay.
+ */
+export function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) ?? 'null';
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(stableStringify).join(',') + ']';
+    }
+    // Object — sort keys and recurse
+    const sorted = Object.keys(value)
+        .sort()
+        .map(k => {
+        const serialisedKey = JSON.stringify(k);
+        const serialisedVal = stableStringify(value[k]);
+        return `${serialisedKey}:${serialisedVal}`;
+    });
+    return '{' + sorted.join(',') + '}';
+}
+//# sourceMappingURL=stable-stringify.js.map

package/dist/server/lib/stable-stringify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-stringify.js","sourceRoot":"","sources":["../../../src/server/lib/stable-stringify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;IACzC,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAC1D,CAAC;IAED,iCAAiC;IACjC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC;SACzD,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,CAAC,EAAE;QACP,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,aAAa,GAAG,eAAe,CAAE,KAAiC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7E,OAAO,GAAG,aAAa,IAAI,aAAa,EAAE,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEL,OAAO,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;AACtC,CAAC"}

package/dist/server/lib/wire-meta.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Single source of truth for wire protocol metadata and package version.
+ * Both health.ts and version.ts import from here; no literal duplicates.
+ */
+export declare const PKG_VERSION: string;
+export declare const WIRE_VERSIONS_SUPPORTED: readonly ["v0.0", "v1.0"];
+export declare const SCHEMA_VERSION: 13;

package/dist/server/lib/wire-meta.js

@@ -0,0 +1,29 @@
+/**
+ * Single source of truth for wire protocol metadata and package version.
+ * Both health.ts and version.ts import from here; no literal duplicates.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Package version — read once at module load, Zod-validated cast
+// ---------------------------------------------------------------------------
+const _dir = dirname(fileURLToPath(import.meta.url));
+const _pkgPath = join(_dir, '..', '..', '..', 'package.json');
+const _PkgSchema = z.object({ version: z.string() });
+export const PKG_VERSION = _PkgSchema.parse(JSON.parse(readFileSync(_pkgPath, 'utf-8'))).version;
+// ---------------------------------------------------------------------------
+// Wire versions — single authoritative list
+// ---------------------------------------------------------------------------
+export const WIRE_VERSIONS_SUPPORTED = ['v0.0', 'v1.0'];
+// ---------------------------------------------------------------------------
+// Schema version — single authoritative literal
+// migrate() asserts that MAX(version) FROM schema_version equals this constant
+// at startup. Bump this whenever a new migration file is added.
+// ---------------------------------------------------------------------------
+// Migrations 001-013 (009 = tag hygiene FEAT-403; 010 = sync-pull event_id FEAT-407;
+// 011 = embed-dim FEAT-409; 012 = entities/memory_entities FEAT-402 slice 1;
+// 013 = memory TTL/archival tiers FEAT-404).
+export const SCHEMA_VERSION = 13;
+//# sourceMappingURL=wire-meta.js.map

package/dist/server/lib/wire-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-meta.js","sourceRoot":"","sources":["../../../src/server/lib/wire-meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8EAA8E;AAC9E,iEAAiE;AACjE,8EAA8E;AAE9E,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;AAE9D,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAErD,MAAM,CAAC,MAAM,WAAW,GAAW,UAAU,CAAC,KAAK,CACjD,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAC5C,CAAC,OAAO,CAAC;AAEV,8EAA8E;AAC9E,4CAA4C;AAC5C,8EAA8E;AAE9E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAsC,CAAC;AAE7F,8EAA8E;AAC9E,gDAAgD;AAChD,+EAA+E;AAC/E,gEAAgE;AAChE,8EAA8E;AAE9E,qFAAqF;AACrF,6EAA6E;AAC7E,6CAA6C;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAG,EAAW,CAAC"}

package/dist/server/queries/dashboard.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Read-only queries powering the /dashboard HTML endpoint.
+ * Extracted here so tests can exercise them independently of the route layer.
+ */
+import type { DB } from '../../storage/db.js';
+import { type UsefulnessRate } from '../../storage/usefulness.js';
+import type { HealthState } from '../health-state.js';
+export interface MemoryCountByType {
+    type: string;
+    count: number;
+}
+export interface RecentMemory {
+    id: string;
+    type: string;
+    text: string;
+    importance: number;
+    confidence: number;
+    session_id: string | null;
+    created_at: number;
+}
+export interface JobStateCount {
+    state: string;
+    count: number;
+}
+/** FEAT-410: job counts grouped by (kind, state) — distinguishes e.g.
+ *  distill:poison=2 from reembed:poison=1, which the state-only
+ *  `queryJobStates` cannot. */
+export interface JobStateByKind {
+    kind: string;
+    state: string;
+    count: number;
+}
+/** FEAT-410: pending consolidation-proposal count + oldest created_at. */
+export interface ConsolidationSummary {
+    count: number;
+    oldest: number | null;
+}
+/** FEAT-410: a failed/poison job row with its error text, for the
+ *  "what failed and why" surface. */
+export interface RecentFailedJob {
+    id: string;
+    kind: string;
+    state: string;
+    last_error: string | null;
+    updated_at: number;
+}
+/** FEAT-410: entity-linking pipeline-stage visibility. */
+export interface EntityLinkage {
+    entityCount: number;
+    unlinkedMemoryCount: number;
+}
+/** FEAT-410: subsystem health rolled up from the boot-time HealthState —
+ *  reuses the same instance /health reads instead of recomputing anything. */
+export interface DashboardHealth {
+    status: ReturnType<HealthState['status']>;
+    uptimeSeconds: number;
+    embed: {
+        ok: boolean | null;
+        lastOkAt: number | null;
+        lastError: string | null;
+        attempts: number;
+    };
+    worker: {
+        alive: boolean;
+        lastTickAt: number | null;
+        lastTickAgoMs: number | null;
+    };
+    diskFreeBytes: number | null;
+}
+export interface HourlyThroughput {
+    hour: string;
+    count: number;
+}
+export interface ProviderRow {
+    provider: string;
+    model: string;
+    dim: number | null;
+    last_health_ok: number;
+    last_check_at: number | null;
+}
+export interface BudgetSpendRow {
+    day: string;
+    usd_total: number;
+    calls: number;
+}
+export interface DashboardData {
+    memoryCounts: MemoryCountByType[];
+    recentMemories: RecentMemory[];
+    jobStates: JobStateCount[];
+    jobStatesByKind: JobStateByKind[];
+    hourlyThroughput: HourlyThroughput[];
+    providers: ProviderRow[];
+    todaySpend: BudgetSpendRow | null;
+    mtdSpend: number;
+    mtdCalls: number;
+    usefulness: UsefulnessRate;
+    consolidation: ConsolidationSummary;
+    recentFailedJobs: RecentFailedJob[];
+    entityLinkage: EntityLinkage;
+    /** null when no HealthState was wired in (e.g. bare test apps) — callers
+     *  degrade the same way /health does when this field is absent. */
+    health: DashboardHealth | null;
+}
+export declare function queryMemoryCounts(db: DB): MemoryCountByType[];
+export declare function queryRecentMemories(db: DB): RecentMemory[];
+export declare function queryJobStates(db: DB): JobStateCount[];
+/** FEAT-410 AC-1: job counts grouped by kind AND state. */
+export declare function queryJobStatesByKind(db: DB): JobStateByKind[];
+/** FEAT-410 AC-3/AC-4: pending proposal count + oldest created_at (via the
+ *  existing ProposalRepo — no new table scan). Never throws on an empty
+ *  queue; ProposalRepo.list('pending') already orders by created_at ASC so
+ *  the first row is the oldest. */
+export declare function queryConsolidationSummary(db: DB): ConsolidationSummary;
+/** FEAT-410 AC-5: most recent failed/poison jobs with their error text,
+ *  newest-updated first. */
+export declare function queryRecentFailedJobs(db: DB, limit?: number): RecentFailedJob[];
+/** FEAT-410: entity count + unlinked-memory count (currently-valid,
+ *  not-archived memories with no memory_entities row) for the entity-link
+ *  pipeline stage. Same "currently valid" predicate used by archival.ts. */
+export declare function queryEntityLinkage(db: DB): EntityLinkage;
+/** FEAT-410: merge the boot-time HealthState (built for /health) into
+ *  DashboardData instead of recomputing subsystem health from scratch. */
+export declare function buildDashboardHealth(healthState: HealthState): DashboardHealth;
+export declare function queryHourlyThroughput(db: DB): HourlyThroughput[];
+export declare function queryProviders(db: DB): ProviderRow[];
+export declare function queryBudget(db: DB): {
+    today: BudgetSpendRow | null;
+    mtdUsd: number;
+    mtdCalls: number;
+};
+/** ADR-010 recall-usefulness rate, last 7 days. Per-type breakdown is
+ *  intentionally not part of the dashboard primary path (FEAT-410 design:
+ *  real product-quality signal, but not an operational glance-screen
+ *  signal) — see storage/usefulness.ts's usefulnessByType for that data. */
+export declare function queryUsefulness(db: DB): UsefulnessRate;
+/**
+ * Run all dashboard queries in a single pass. `healthState` is the same
+ * instance built at boot for GET /health (FEAT-410) — when omitted (bare
+ * test apps), `health` is null and callers degrade the same way /health
+ * does without it.
+ */
+export declare function queryDashboard(db: DB, healthState?: HealthState): Promise<DashboardData>;

package/dist/server/queries/dashboard.js

@@ -0,0 +1,166 @@
+/**
+ * Read-only queries powering the /dashboard HTML endpoint.
+ * Extracted here so tests can exercise them independently of the route layer.
+ */
+import { statfsSync } from 'node:fs';
+import { usefulnessRate } from '../../storage/usefulness.js';
+import { ProposalRepo } from '../../consolidate/proposals.js';
+// ---------------------------------------------------------------------------
+// Query implementations
+// ---------------------------------------------------------------------------
+export function queryMemoryCounts(db) {
+    return db.prepare('SELECT type, COUNT(*) as count FROM memories GROUP BY type ORDER BY 2 DESC').all();
+}
+export function queryRecentMemories(db) {
+    return db.prepare(`
+    SELECT id, type, text, importance, confidence, session_id, created_at
+    FROM memories
+    ORDER BY created_at DESC
+    LIMIT 25
+  `).all();
+}
+export function queryJobStates(db) {
+    return db.prepare('SELECT state, COUNT(*) as count FROM jobs GROUP BY state').all();
+}
+/** FEAT-410 AC-1: job counts grouped by kind AND state. */
+export function queryJobStatesByKind(db) {
+    return db.prepare('SELECT kind, state, COUNT(*) as count FROM jobs GROUP BY kind, state').all();
+}
+/** FEAT-410 AC-3/AC-4: pending proposal count + oldest created_at (via the
+ *  existing ProposalRepo — no new table scan). Never throws on an empty
+ *  queue; ProposalRepo.list('pending') already orders by created_at ASC so
+ *  the first row is the oldest. */
+export function queryConsolidationSummary(db) {
+    const pending = new ProposalRepo(db).list('pending');
+    if (pending.length === 0)
+        return { count: 0, oldest: null };
+    return { count: pending.length, oldest: pending[0].created_at };
+}
+/** FEAT-410 AC-5: most recent failed/poison jobs with their error text,
+ *  newest-updated first. */
+export function queryRecentFailedJobs(db, limit = 10) {
+    return db.prepare(`
+    SELECT id, kind, state, last_error, updated_at
+    FROM jobs
+    WHERE state IN ('failed', 'poison')
+    ORDER BY updated_at DESC
+    LIMIT ?
+  `).all(limit);
+}
+/** FEAT-410: entity count + unlinked-memory count (currently-valid,
+ *  not-archived memories with no memory_entities row) for the entity-link
+ *  pipeline stage. Same "currently valid" predicate used by archival.ts. */
+export function queryEntityLinkage(db) {
+    const entityCount = db.prepare('SELECT COUNT(*) as n FROM entities').get().n;
+    const unlinkedMemoryCount = db.prepare(`
+    SELECT COUNT(*) as n
+    FROM memories m
+    WHERE valid_to IS NULL AND archived = 0
+      AND NOT EXISTS (SELECT 1 FROM memory_entities me WHERE me.memory_id = m.id)
+  `).get().n;
+    return { entityCount, unlinkedMemoryCount };
+}
+/** Generous liveness window: the worker stamps lastTickAt at tick START, so
+ *  a single long-running job (LLM distill can take up to the 60s chat
+ *  timeout) must not read as "worker dead". Mirrors health.ts's own
+ *  WORKER_ALIVE_WINDOW_MS — duplicated locally by design (same precedent as
+ *  the stub pages' local auth check) to avoid a routes/health.ts <->
+ *  queries/dashboard.ts import cycle. */
+const WORKER_ALIVE_WINDOW_MS = 90_000;
+function diskFreeBytes(dataDir) {
+    try {
+        const s = statfsSync(dataDir);
+        return s.bavail * s.bsize;
+    }
+    catch {
+        return null;
+    }
+}
+/** FEAT-410: merge the boot-time HealthState (built for /health) into
+ *  DashboardData instead of recomputing subsystem health from scratch. */
+export function buildDashboardHealth(healthState) {
+    const lastTick = healthState.worker.lastTickAt;
+    return {
+        status: healthState.status(),
+        uptimeSeconds: healthState.uptimeSeconds(),
+        embed: { ...healthState.embed },
+        worker: {
+            alive: lastTick !== null && Date.now() - lastTick < WORKER_ALIVE_WINDOW_MS,
+            lastTickAt: lastTick,
+            lastTickAgoMs: lastTick === null ? null : Date.now() - lastTick,
+        },
+        diskFreeBytes: healthState.dataDir ? diskFreeBytes(healthState.dataDir) : null,
+    };
+}
+export function queryHourlyThroughput(db) {
+    const since24hMs = Date.now() - 24 * 60 * 60 * 1000;
+    return db.prepare(`
+    SELECT
+      strftime('%Y-%m-%d %H', datetime(created_at / 1000, 'unixepoch')) AS hour,
+      COUNT(*) AS count
+    FROM memories
+    WHERE created_at > ?
+    GROUP BY hour
+    ORDER BY hour
+  `).all(since24hMs);
+}
+export function queryProviders(db) {
+    return db.prepare('SELECT provider, model, dim, last_health_ok, last_check_at FROM provider_state').all();
+}
+export function queryBudget(db) {
+    const todayKey = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    const monthPrefix = todayKey.slice(0, 7); // YYYY-MM
+    const today = db.prepare('SELECT day, usd_total, calls FROM budget_spend WHERE day = ?').get(todayKey) ?? null;
+    const mtd = db.prepare("SELECT COALESCE(SUM(usd_total), 0) AS usd_total, COALESCE(SUM(calls), 0) AS calls FROM budget_spend WHERE day LIKE ? || '%'").get(monthPrefix);
+    return {
+        today,
+        mtdUsd: mtd?.usd_total ?? 0,
+        mtdCalls: mtd?.calls ?? 0,
+    };
+}
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+/** ADR-010 recall-usefulness rate, last 7 days. Per-type breakdown is
+ *  intentionally not part of the dashboard primary path (FEAT-410 design:
+ *  real product-quality signal, but not an operational glance-screen
+ *  signal) — see storage/usefulness.ts's usefulnessByType for that data. */
+export function queryUsefulness(db) {
+    const since = Date.now() - SEVEN_DAYS_MS;
+    return usefulnessRate(db, { sinceMs: since });
+}
+/**
+ * Run all dashboard queries in a single pass. `healthState` is the same
+ * instance built at boot for GET /health (FEAT-410) — when omitted (bare
+ * test apps), `health` is null and callers degrade the same way /health
+ * does without it.
+ */
+export async function queryDashboard(db, healthState) {
+    const memoryCounts = queryMemoryCounts(db);
+    const recentMemories = queryRecentMemories(db);
+    const jobStates = queryJobStates(db);
+    const jobStatesByKind = queryJobStatesByKind(db);
+    const hourlyThroughput = queryHourlyThroughput(db);
+    const providers = queryProviders(db);
+    const budget = queryBudget(db);
+    const usefulness = queryUsefulness(db);
+    const consolidation = queryConsolidationSummary(db);
+    const recentFailedJobs = queryRecentFailedJobs(db);
+    const entityLinkage = queryEntityLinkage(db);
+    const health = healthState ? buildDashboardHealth(healthState) : null;
+    return {
+        memoryCounts,
+        recentMemories,
+        jobStates,
+        jobStatesByKind,
+        hourlyThroughput,
+        providers,
+        todaySpend: budget.today,
+        mtdSpend: budget.mtdUsd,
+        mtdCalls: budget.mtdCalls,
+        usefulness,
+        consolidation,
+        recentFailedJobs,
+        entityLinkage,
+        health,
+    };
+}
+//# sourceMappingURL=dashboard.js.map

package/dist/server/queries/dashboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.js","sourceRoot":"","sources":["../../../src/server/queries/dashboard.ts"],"names":[],"mappings":"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"}

package/dist/server/routes/consolidation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Consolidation routes (Wave 4b, ADR-004 stage 9):
+ *   POST /consolidation/run                     -> 200 ConsolidateSummary
+ *   GET  /consolidation/proposals?status=       -> { proposals: [...] }
+ *   POST /consolidation/proposals/:id/accept    -> 200 proposal | 404 | 409
+ *   POST /consolidation/proposals/:id/reject    -> 200 proposal | 404 | 409
+ *
+ * /run executes the deterministic pass inline (no LLM in v1 — cheap enough
+ * to run synchronously); the `consolidate` job kind wraps the same call for
+ * scheduled runs.
+ */
+import type { FastifyInstance } from 'fastify';
+import type { DB } from '../../storage/db.js';
+export declare function consolidationRoutes(db: DB): (app: FastifyInstance) => Promise<void>;