@gamaze/hicortex 0.20.9 → 0.21.0

package/dist/dashboard.d.ts

@@ -1,10 +1,12 @@
 /**
- * /dashboard — view-only memory analytics (#224).
+ * /dashboard — view-only memory analytics (#224) + the console's live-data
+ * endpoints (#409/#421 Phase 1: /dashboard/field, /dashboard/events).
  *
  * STRICTLY view-only: this module computes metrics, reads snapshots, writes
  * ONE snapshot row per full nightly run (the writer is here because the
  * metric SQL lives next to its definition, not in nightly.ts), and exposes
- * the pure data handler mounted at GET /dashboard/data. There are NO mutation
+ * the pure data handlers mounted at GET /dashboard/data,
+ * GET /dashboard/field and GET /dashboard/events. There are NO mutation
  * endpoints on the dashboard surface — the only write path is the nightly
  * snapshot writer + the one-time backfill, both internal.
  *
@@ -20,17 +22,44 @@
  */
 import type express from "express";
 import type Database from "better-sqlite3";
+import { type Stage } from "./stages.js";
 /** Corpus-shape snapshot. `adoption` is null in backfilled rows (point-in-time,
  *  can't be reconstructed from created_at). */
 export interface DashboardMetrics {
+    /**
+     * `mem` counts ALL rows (backcompat — the growth chart's series). #422 adds
+     * `live_mem` (non-absorbed: what recall serves + the field paints) and
+     * `absorbed` (= mem − live_mem, the dedup/reconsol evidence rows). Both are
+     * undefined on backfilled rows — whether a historical row was absorbed at
+     * that moment is not reconstructable from created_at (honest omission).
+     */
     totals: {
         mem: number;
         lesson: number;
         link: number;
+        live_mem?: number;
+        absorbed?: number;
+    };
+    /**
+     * #422 Phase 2 — per-stage counts over LIVE (non-absorbed) rows, derived
+     * with the SAME math as /dashboard/field (the shared deriveStageForRow —
+     * one formula, two surfaces, drift impossible). Undefined on backfilled
+     * rows (historical strengths are not reconstructable). Drives the
+     * graduation deltas in the activity bars.
+     */
+    stage_counts?: {
+        forming: number;
+        belief: number;
+        truth: number;
+        fading: number;
     };
     by_type: Record<string, number>;
     by_domain: Record<string, number>;
     by_source_agent: Record<string, number>;
+    /** #421 machine × harness: memories per capture machine. Rows written
+     *  before migration v15 have NULL source_machine → grouped under
+     *  "(unstamped)" (the console labels them "earlier captures"). */
+    by_source_machine: Record<string, number>;
     /** Per-run deltas; undefined on backfilled rows (created_at can't reconstruct
      *  what a given nightly produced). */
     new_this_run?: {
@@ -102,6 +131,16 @@ export interface DashboardMetrics {
             bytes: number;
             path?: string;
         };
+        /**
+         * #427: reconsolidation scout counters, flat snake_case mirroring the
+         * stage report (scout_scanned / scout_correction_shaped /
+         * scout_candidates_found). Present whenever consolidation ran —
+         * quiet-night zeros are real values; undefined = no consolidation that
+         * night (and always absent on backfill rows).
+         */
+        scout_scanned?: number;
+        scout_correction_shaped?: number;
+        scout_candidates_found?: number;
     };
     /** Corpus capacity (#245). `memory_soft_cap` is the configured ceiling (0 =
      *  disabled); always present in real snapshots, undefined on backfilled
@@ -138,6 +177,12 @@ export interface DashboardData {
     };
     headline: {
         total_memories: number;
+        /**
+         * #422 Phase 2 — LIVE (non-absorbed) memory count: what recall serves and
+         * the field paints. The console's overview counter and cap bar key off
+         * THIS (total_memories stays ALL rows for backcompat — the growth chart).
+         */
+        live_memories: number;
         uses_per_showing: number | null;
         cold_count: number;
         /** Corpus vs cap (#245). `memory_soft_cap` is 0 when the cap is disabled
@@ -163,6 +208,47 @@ export interface DashboardData {
         by_type: Record<string, number>;
         by_domain: Record<string, number>;
         by_source_agent: Record<string, number>;
+        /** #421 machine × harness; "(unstamped)" = pre-v15 rows. */
+        by_source_machine: Record<string, number>;
+    };
+    /**
+     * #422 Phase 2 — capture health: per machine × agent /distill outcome
+     * accounting for the most recent day with rows (posts / sessions / bytes /
+     * held / retried). ALWAYS present; {day: null, rows: []} when nothing is
+     * recorded (fresh install / all rows pruned — the page degrades to the
+     * phase-1 counts-only rows).
+     */
+    capture_health: {
+        day: string | null;
+        rows: Array<{
+            machine: string;
+            agent: string;
+            posts: number;
+            sessions: number;
+            bytes: number;
+            held: number;
+            retried: number;
+        }>;
+    };
+    /**
+     * #423 phase 3 — fleet presence: the operator's capture pauses + per-bundle
+     * last-seen (derived ONLY from /distill activity — see capture-pause.ts's
+     * module doc for why recall traffic can never attribute). ALWAYS present;
+     * empty arrays when nothing is recorded (fresh install). The page degrades
+     * to the phase-2 rendering when the block is absent (pre-phase-3 server).
+     */
+    fleet: {
+        pauses: Array<{
+            machine: string;
+            harness: string;
+            paused_at: string;
+        }>;
+        last_seen: Array<{
+            machine: string;
+            harness: string;
+            last_seen: string;
+            last_outcome: string;
+        }>;
     };
     digest: {
         date: string | null;
@@ -215,9 +301,23 @@ export interface DashboardData {
 /**
  * Compute the full corpus-shape metrics from the live DB. The same function
  * backs both the nightly snapshot writer and the live /dashboard/data
- * composition view — one definition of corpus shape.
+ * composition view — one definition of corpus shape. #422 adds the
+ * live/absorbed split (`totals.live_mem`/`absorbed`) and `stage_counts` —
+ * both derived here so every snapshot row carries them automatically.
  */
 export declare function computeDashboardMetrics(db: Database.Database): DashboardMetrics;
+/**
+ * Count LIVE (non-absorbed) memories per derived stage — the snapshot's
+ * `stage_counts` (#422 Phase 2). Same math as the field payload via the
+ * shared deriveStageForRow; absorbed rows are excluded exactly like the
+ * field paints them (invisible evidence is not a maturity stage).
+ */
+export declare function computeStageCounts(db: Database.Database): {
+    forming: number;
+    belief: number;
+    truth: number;
+    fading: number;
+};
 export interface NightlyDelta {
     added: number;
     lessonsGenerated?: number;
@@ -284,6 +384,15 @@ export interface NightlyDelta {
     backupPath?: string;
     backupBytes?: number;
     backupOk?: boolean;
+    /**
+     * #427: reconsolidation scout counters. Forwarded whenever consolidation
+     * ran (the stage's quiet-night shape carries real zeros — the scan doesn't
+     * run on a quiet night); undefined when consolidation didn't run at all.
+     * Stamped flat snake_case, mirroring the stage report.
+     */
+    scoutScanned?: number;
+    scoutCorrectionShaped?: number;
+    scoutCandidatesFound?: number;
 }
 /**
  * Write one snapshot row for `runAt` (an ISO timestamp the caller chooses —
@@ -369,3 +478,213 @@ export declare function accountHandler(getConfig: () => Record<string, unknown>
  * {error} exactly like accountHandler.
  */
 export declare function accountTokenHandler(getToken: () => string | undefined): express.RequestHandler;
+/** One memory in the field payload — minimal fields, no content body. */
+export interface DashboardFieldMemory {
+    id: string;
+    /** First content line, de-markdowned, ≤ RECALL_TITLE_CHARS (memoryTitle). */
+    title: string;
+    /** Derived primary domain (argmax tag weight); null = unscoped. */
+    domain: string | null;
+    /** Derived maturity stage (E-reframe: presentation, never stored). */
+    stage: Stage;
+    /** effectiveStrength rounded to 1e-6, same as retrieval's wire format. */
+    strength: number;
+    access_count: number;
+    created_at: string;
+    source_agent: string | null;
+    /** Machine the capture ran on (#421 machine × harness). Null on rows
+     *  written before migration v15 — the console groups those under
+     *  "earlier captures". */
+    source_machine: string | null;
+}
+/** One link edge — endpoints + relationship only (strength stays off-wire). */
+export interface DashboardFieldLink {
+    a: string;
+    b: string;
+    rel: string;
+}
+/** The /dashboard/field response. */
+export interface DashboardField {
+    generated_at: string;
+    /** The thresholds the stages were derived with, echoed so the page paints
+     *  from the same constants the server scored with (calibration.ts is the
+     *  single home — the echo is display, not a second source). Recall grades
+     *  are GONE (#426 owner semantics ruling 2026-09-13: recall depends on the
+     *  conversation, a graded scale implies a target that does not exist). */
+    thresholds: {
+        stage: {
+            fading_days: number;
+            fading_strength: number;
+            belief: number;
+            truth: number;
+        };
+        /** The recall relevance floor (RECALL_MIN_SIMILARITY) — echoed so the
+         *  console gates its /search calls with the same constant the server's
+         *  own recall gates with (#409 console polish; the echo is display, not
+         *  a second source — same rule as the stage bands). Absent nothing: the
+         *  key always rides the payload; a pre-polish page ignores it. */
+        recall_min_similarity: number;
+        /** #426 final ruling 2026-09-13: the console's recall-level band edges
+         *  (RECALL_USES_* — PROVISIONAL, owner anchor 2026-09-13, pending fleet
+         *  telemetry). Same echo rule as recall_min_similarity: calibration.ts is
+         *  the single home, the page never hardcodes the edges, and a page older
+         *  than this key simply ignores it (no band). These classify the console
+         *  card's zone word and position the gradient; per-memory recall grades
+         *  remain GONE from the field payload (the earlier #426 ruling — a
+         *  memory's recall fitness is conversation-dependent). */
+        recall_uses: {
+            /** Below this reads Low. */
+            low_max: number;
+            /** Below this (and ≥ low_max) reads Normal; at/above reads Overfetching. */
+            normal_max: number;
+            /** Display-axis maximum (marker clamps here). */
+            axis_max: number;
+        };
+    };
+    memories: DashboardFieldMemory[];
+    links: DashboardFieldLink[];
+}
+/**
+ * The pure data handler for GET /dashboard/field. Reads the whole live store
+ * (minus absorbed rows) + all link edges, derives stage + effective strength
+ * per memory, and returns the field payload. Never throws on empty stores —
+ * an empty brain is a valid field.
+ */
+export declare function handleDashboardField(db: Database.Database): {
+    status: number;
+    body: DashboardField;
+};
+/**
+ * Express adapter for GET /dashboard/field. Bearer-only by construction
+ * (mounted after createAuthMiddleware — no exemption). Gzips the payload
+ * when the client advertises Accept-Encoding: gzip: the field is one row per
+ * memory on possibly very large stores, so the wire cost is the point
+ * (minimal fields + compression, per the #409 payload-size risk note).
+ * Failures surface as a 500 {error} like the sibling adapters.
+ */
+export declare function dashboardFieldHandler(getDb: () => Database.Database): express.RequestHandler;
+/** One night of the replay ledger. `by_agent` keys are source_agent strings
+ *  ("(unknown)" when the memory row is gone); learned counts added, enriched
+ *  counts distinct enriched memories, merged counts dedup losers. */
+export interface DashboardEventsNight {
+    date: string;
+    added: string[];
+    enriched: string[];
+    merged: Array<{
+        loser: string;
+        canonical: string;
+    }>;
+    linked: Array<{
+        a: string;
+        b: string;
+    }>;
+    by_agent: Record<string, {
+        learned: number;
+        enriched: number;
+        merged: number;
+    }>;
+}
+/** The /dashboard/events response. */
+export interface DashboardEvents {
+    nights: DashboardEventsNight[];
+}
+/**
+ * The pure data handler for GET /dashboard/events?days=N. Buckets the four
+ * event sources into UTC nights (only nights with events, ascending) within
+ * the last `days` calendar days (today inclusive).
+ */
+export declare function handleDashboardEvents(db: Database.Database, query: {
+    days?: unknown;
+}): {
+    status: number;
+    body: DashboardEvents | {
+        error: string;
+    };
+};
+/**
+ * Express adapter for GET /dashboard/events. Bearer-only by construction
+ * (mounted after createAuthMiddleware — no exemption). The ledger is ids
+ * only (no titles), so it stays plain JSON — gzip is the /field adapter's
+ * concern. Failures surface as a 500 {error} like the sibling adapters.
+ */
+export declare function dashboardEventsHandler(getDb: () => Database.Database): express.RequestHandler;
+/** The GET /dashboard/model + PUT-success response shape (snake_case wire). */
+export interface DashboardModelSettings {
+    /** Boot-resolved runtime provider label (e.g. "ollama", "claude-cli",
+     *  "openai" for the openai-compat path); null when the daemon runs no LLM.
+     *  Runtime truth, not config — the card's model line comes from
+     *  /health/detail, this carries only the provider. */
+    provider: string | null;
+    /** config llmBackend — null when unset (baseUrl+apiKey = openai-compat). */
+    backend: string | null;
+    /** config llmBaseUrl — null when unset (defaults are the UI's placeholders,
+     *  never resolved here). */
+    base_url: string | null;
+    /** config llmModel — null when unset. */
+    model: string | null;
+    /** config maxTokens — null when unset. */
+    max_tokens: number | null;
+    /** config enableThinking — null when unset. */
+    enable_thinking: boolean | null;
+    /** Whether llmApiKey is set. The VALUE is never on the wire. */
+    api_key_set: boolean;
+    /** Constant true — the daemon resolves config at boot, so every write
+     *  lands on restart. The modal footnotes it. */
+    applies_on_restart: true;
+}
+/**
+ * The pure GET handler: echo the CONFIG values raw (null when unset — the UI
+ * shows defaults as placeholders, so this never resolves them) + the runtime
+ * provider from the daemon's in-memory llmConfig.
+ */
+export declare function handleDashboardModelGet(config: Record<string, unknown> | null | undefined, llmConfig: {
+    provider: string;
+} | null): {
+    status: 200;
+    body: DashboardModelSettings;
+};
+/**
+ * The pure PUT handler: validate the allowlisted subset, persist via the
+ * injected writer (which THROWS on a malformed config — the adapter maps that
+ * to a 500 and the file stays untouched), answer with the fresh GET shape
+ * built from the post-write config. `null` REMOVES a config key.
+ */
+export declare function handleDashboardModelPut(body: unknown, persist: (updates: Record<string, unknown>) => Record<string, unknown>, getLlmConfig: () => {
+    provider: string;
+} | null): {
+    status: number;
+    body: DashboardModelSettings | {
+        error: string;
+    };
+};
+/**
+ * Express adapter for GET /dashboard/model. Bearer-only by construction
+ * (mounted after createAuthMiddleware — NO exemption, unlike the page shells:
+ * this carries install config). Failures surface as a 500 {error}.
+ */
+export declare function dashboardModelGetHandler(getConfig: () => Record<string, unknown> | null | undefined, getLlmConfig: () => {
+    provider: string;
+} | null): express.RequestHandler;
+/**
+ * Express adapter for PUT /dashboard/model. Same auth posture as the GET.
+ * The injected persist closure owns the config path (the server passes
+ * init.ts persistConfigUpdates over stateDir/config.json); its load/persist
+ * failures (malformed config, unwritable file) map to a 500 {error} with the
+ * file left untouched — never a silent partial write.
+ */
+export declare function dashboardModelPutHandler(persist: (updates: Record<string, unknown>) => Record<string, unknown>, getLlmConfig: () => {
+    provider: string;
+} | null): express.RequestHandler;
+/** The PUT's body: {machine?: string|null, harness: string, paused: boolean}. */
+export declare function handleDashboardCapturePausePut(body: unknown, setPause: (machine: string, harness: string, paused: boolean) => string | null): {
+    status: number;
+    body: Record<string, unknown>;
+};
+/**
+ * Express adapter for PUT /dashboard/capture-pause. Bearer-only by
+ * construction (mounted after createAuthMiddleware, no shell exemption).
+ * The effect is immediate — no restart: the /distill handler reads the
+ * pause table on every post, so the very next capture POST from the bundle
+ * is skipped (200) or captured as before.
+ */
+export declare function dashboardCapturePausePutHandler(getDb: () => Database.Database): express.RequestHandler;