@legioncodeinc/hive 0.1.0

package/dist/shared/fleet-telemetry.js

@@ -0,0 +1,61 @@
+/**
+ * Shared fleet-TELEMETRY shapes — hive PRD-004/PRD-005, mirroring doctor's
+ * `src/telemetry/schema.ts` (Contract C in `library/ledger/EXECUTION_LEDGER.md`).
+ *
+ * hive does not depend on the doctor package (each fleet member is its own published
+ * npm package), so this module is a hand-kept, browser-and-server-safe COPY of the wire shape
+ * doctor's SSE stream (`GET http://127.0.0.1:3852/events`, event `fleet-telemetry`) actually
+ * emits. Keep it in lockstep with doctor's schema.ts if that contract ever changes.
+ *
+ * `metrics` is deliberately `Readonly<Record<string, number>>`: honeycomb ships three counters
+ * (`actionsTaken`, `filesProcessed`, `memoriesCreated`), nectar ships five
+ * (`filesRegistered`, `nectarsMinted`, `descriptionsGenerated`, `hiveGraphVersions`,
+ * `embeddingsComputed`) — every reader built on this module (PRD-005b's metrics render, PRD-004c's
+ * derivation) is schema-tolerant by construction: it never hardcodes one service's key names.
+ */
+import { z } from "zod";
+/** The one SSE event name doctor's stream ever emits (mirrors doctor's `ingestion/sse.ts`). */
+export const FLEET_TELEMETRY_EVENT_NAME = "fleet-telemetry";
+// ── Defensive parse (untrusted transport boundary: the SSE frame body / the JSON fetch body) ──
+const FleetHealthSchema = z.enum(["ok", "degraded", "unreachable", "unknown"]);
+const TelemetryFaultReasonSchema = z.enum(["missing", "locked", "malformed", "read-error"]);
+const FleetDeeplakeStatsSchema = z.object({
+    connected: z.boolean().nullable(),
+    lastCommunicationAt: z.string().nullable(),
+});
+const FleetServiceModelSchema = z.object({
+    name: z.string().min(1),
+    health: FleetHealthSchema,
+    lastSeen: z.string().nullable(),
+    metrics: z.record(z.string(), z.number()),
+    deeplake: FleetDeeplakeStatsSchema.nullable(),
+    telemetryFault: TelemetryFaultReasonSchema.nullable(),
+});
+const FleetLogEntrySchema = z.object({
+    service: z.string().min(1),
+    ts: z.string().min(1),
+    level: z.string().min(1),
+    message: z.string(),
+});
+const FleetTelemetryEventSchema = z.object({
+    asOf: z.string().min(1),
+    services: z.array(FleetServiceModelSchema),
+    logs: z.array(FleetLogEntrySchema),
+});
+/**
+ * Defensively parse one `fleet-telemetry` SSE frame's `data:` JSON (or the same shape from any
+ * future JSON transport). Returns `null` on anything malformed rather than throwing, so one bad
+ * frame never crashes the consuming hook (mirrors `fleet-status.ts`'s `safeParse`-and-degrade posture).
+ */
+export function parseFleetTelemetryEvent(raw) {
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const parsed = FleetTelemetryEventSchema.safeParse(parsedJson);
+    return parsed.success ? parsed.data : null;
+}
+//# sourceMappingURL=fleet-telemetry.js.map

package/dist/shared/fleet-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-telemetry.js","sourceRoot":"","sources":["../../src/shared/fleet-telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsDxB,+FAA+F;AAC/F,MAAM,CAAC,MAAM,0BAA0B,GAAG,iBAA0B,CAAC;AAErE,iGAAiG;AAEjG,MAAM,iBAAiB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC,CAAC;AAC/E,MAAM,0BAA0B,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;AAE5F,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACjC,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC;AAEH,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,MAAM,EAAE,iBAAiB;IACzB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IACzC,QAAQ,EAAE,wBAAwB,CAAC,QAAQ,EAAE;IAC7C,cAAc,EAAE,0BAA0B,CAAC,QAAQ,EAAE;CACrD,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC;AAEH,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,uBAAuB,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;CAClC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAW;IACnD,IAAI,UAAmB,CAAC;IACxB,IAAI,CAAC;QACJ,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;IACD,MAAM,MAAM,GAAG,yBAAyB,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC/D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5C,CAAC"}

package/dist/shared/lifecycle-flags.d.ts

@@ -0,0 +1,34 @@
+/**
+ * PRD-058d — the single-sourced `memory.lifecycle.*` FLAG REFERENCE (symbol, default, effect).
+ *
+ * This is the ONE table the settings page renders AND the config-reference doc lists AND the daemon
+ * config module re-exports, so the symbol / default / master-equation effect can never drift between
+ * the operator surface and the documentation (AC-55d.1.3). It lives in `src/shared` (browser-safe, no
+ * `zod`/`process.env`/daemon import) so the DASHBOARD bundle can render it without pulling daemon code
+ * across the bundle boundary, while `src/daemon/runtime/memories/lifecycle-config.ts` re-exports it
+ * (and OWNS the matching schema defaults, asserted in parity by the lifecycle-config spec).
+ *
+ * The defaults below are the documented values from `memory-lifecycle-scoring.md`'s "Parameters and
+ * defaults" table; the daemon config module's `DEFAULT_*` constants resolve to these same values from
+ * the owning engines, and the lifecycle-config spec asserts the two agree (so a future engine default
+ * change is caught, not silently drifted).
+ */
+/** One row of the operator-facing flag reference. */
+export interface LifecycleFlagRef {
+    /** The mathematical symbol from the scoring doc (`a`, `h(memories)`, `θ_detect`, …). */
+    readonly symbol: string;
+    /** The `memory.lifecycle.*` config path. */
+    readonly configPath: string;
+    /** The `HONEYCOMB_LIFECYCLE_*` env override. */
+    readonly envOverride: string;
+    /** The documented default, rendered for display. */
+    readonly defaultValue: string;
+    /** The effect on the master equation `P = R · A^a · C^c · (1 − σ)^s · κ` / on detection. */
+    readonly effect: string;
+}
+/**
+ * The single source of the lifecycle flag reference (AC-55d.1.3). Every flag from the scoring-doc
+ * parameter table plus the two posture flags, each with its symbol, default, config path, env
+ * override, and master-equation effect. The settings page + the config-reference doc both read THIS.
+ */
+export declare const LIFECYCLE_FLAG_REFERENCE: readonly LifecycleFlagRef[];

package/dist/shared/lifecycle-flags.js

@@ -0,0 +1,39 @@
+/**
+ * PRD-058d — the single-sourced `memory.lifecycle.*` FLAG REFERENCE (symbol, default, effect).
+ *
+ * This is the ONE table the settings page renders AND the config-reference doc lists AND the daemon
+ * config module re-exports, so the symbol / default / master-equation effect can never drift between
+ * the operator surface and the documentation (AC-55d.1.3). It lives in `src/shared` (browser-safe, no
+ * `zod`/`process.env`/daemon import) so the DASHBOARD bundle can render it without pulling daemon code
+ * across the bundle boundary, while `src/daemon/runtime/memories/lifecycle-config.ts` re-exports it
+ * (and OWNS the matching schema defaults, asserted in parity by the lifecycle-config spec).
+ *
+ * The defaults below are the documented values from `memory-lifecycle-scoring.md`'s "Parameters and
+ * defaults" table; the daemon config module's `DEFAULT_*` constants resolve to these same values from
+ * the owning engines, and the lifecycle-config spec asserts the two agree (so a future engine default
+ * change is caught, not silently drifted).
+ */
+/**
+ * The single source of the lifecycle flag reference (AC-55d.1.3). Every flag from the scoring-doc
+ * parameter table plus the two posture flags, each with its symbol, default, config path, env
+ * override, and master-equation effect. The settings page + the config-reference doc both read THIS.
+ */
+export const LIFECYCLE_FLAG_REFERENCE = Object.freeze([
+    { symbol: "a", configPath: "memory.lifecycle.activationExponent", envOverride: "HONEYCOMB_LIFECYCLE_ACTIVATION_EXPONENT", defaultValue: "1", effect: "exponent on the activation/freshness term A^a" },
+    { symbol: "c", configPath: "memory.lifecycle.confidenceExponent", envOverride: "HONEYCOMB_LIFECYCLE_CONFIDENCE_EXPONENT", defaultValue: "0", effect: "exponent on the calibrated-confidence term C^c (dormant until calibrated)" },
+    { symbol: "s", configPath: "memory.lifecycle.stalenessExponent", envOverride: "HONEYCOMB_LIFECYCLE_STALENESS_EXPONENT", defaultValue: "0", effect: "exponent on the staleness term (1 − σ)^s (0 under observe)" },
+    { symbol: "h(memories)", configPath: "memory.lifecycle.halfLifeDaysByClass.memories", envOverride: "HONEYCOMB_LIFECYCLE_HALFLIFE_MEMORIES_DAYS", defaultValue: "180 d", effect: "shapes A for distilled facts (slower decay)" },
+    { symbol: "h(memory)", configPath: "memory.lifecycle.halfLifeDaysByClass.memory", envOverride: "HONEYCOMB_LIFECYCLE_HALFLIFE_MEMORY_DAYS", defaultValue: "45 d", effect: "shapes A for session summaries" },
+    { symbol: "h(sessions)", configPath: "memory.lifecycle.halfLifeDaysByClass.sessions", envOverride: "HONEYCOMB_LIFECYCLE_HALFLIFE_SESSIONS_DAYS", defaultValue: "10 d", effect: "shapes A for raw dialogue (fastest decay)" },
+    { symbol: "d", configPath: "memory.lifecycle.actrDecay", envOverride: "HONEYCOMB_LIFECYCLE_ACTR_DECAY", defaultValue: "0.5", effect: "ACT-R decay shaping A (Stage 2)" },
+    { symbol: "A_min", configPath: "memory.lifecycle.activationFloor", envOverride: "HONEYCOMB_LIFECYCLE_ACTIVATION_FLOOR", defaultValue: "0.05", effect: "clamps A so a cold memory keeps a sliver of salience" },
+    { symbol: "h_verify", configPath: "memory.lifecycle.verificationHalfLifeDays", envOverride: "HONEYCOMB_LIFECYCLE_VERIFICATION_HALFLIFE_DAYS", defaultValue: "14 d", effect: "shapes σ via the verification-freshness factor v(m,t)" },
+    { symbol: "θ_detect", configPath: "memory.lifecycle.contradictionThreshold", envOverride: "HONEYCOMB_LIFECYCLE_CONTRADICTION_THRESHOLD", defaultValue: "0.6", effect: "gates conflict detection (Contra > θ_detect)" },
+    { symbol: "γ", configPath: "memory.lifecycle.corroborationWeight", envOverride: "HONEYCOMB_LIFECYCLE_CORROBORATION_WEIGHT", defaultValue: "0.5", effect: "shapes the conflict vote weight w_i" },
+    { symbol: "τ_supersede", configPath: "memory.lifecycle.supersedeMargin", envOverride: "HONEYCOMB_LIFECYCLE_SUPERSEDE_MARGIN", defaultValue: "0.5", effect: "conflict verdict cut (margin ≥ τ_supersede → supersede)" },
+    { symbol: "τ_review", configPath: "memory.lifecycle.reviewMargin", envOverride: "HONEYCOMB_LIFECYCLE_REVIEW_MARGIN", defaultValue: "0.15", effect: "conflict verdict cut (τ_review ≤ margin < τ_supersede → review)" },
+    { symbol: "ρ", configPath: "memory.lifecycle.openConflictSuppression", envOverride: "HONEYCOMB_LIFECYCLE_OPEN_CONFLICT_SUPPRESSION", defaultValue: "0", effect: "κ for the open-conflict loser (0 fully suppress, reversible)" },
+    { symbol: "auto-resolve", configPath: "memory.lifecycle.conflictAutoResolve", envOverride: "HONEYCOMB_LIFECYCLE_CONFLICT_AUTORESOLVE", defaultValue: "false", effect: "when off, conflicts are detected + queued only (human-in-the-loop)" },
+    { symbol: "posture", configPath: "memory.lifecycle.staleRefPosture", envOverride: "HONEYCOMB_LIFECYCLE_STALEREF_POSTURE", defaultValue: "observe", effect: "observe (s = 0, inert) vs execute (s > 0, demote)" },
+]);
+//# sourceMappingURL=lifecycle-flags.js.map

package/dist/shared/lifecycle-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-flags.js","sourceRoot":"","sources":["../../src/shared/lifecycle-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgBH;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAgC,MAAM,CAAC,MAAM,CAAC;IAClF,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,qCAAqC,EAAE,WAAW,EAAE,yCAAyC,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,+CAA+C,EAAE;IACtM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,qCAAqC,EAAE,WAAW,EAAE,yCAAyC,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,2EAA2E,EAAE;IAClO,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,oCAAoC,EAAE,WAAW,EAAE,wCAAwC,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,4DAA4D,EAAE;IACjN,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,+CAA+C,EAAE,WAAW,EAAE,4CAA4C,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,6CAA6C,EAAE;IAC/N,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,6CAA6C,EAAE,WAAW,EAAE,0CAA0C,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,gCAAgC,EAAE;IAC3M,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,+CAA+C,EAAE,WAAW,EAAE,4CAA4C,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,2CAA2C,EAAE;IAC5N,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,4BAA4B,EAAE,WAAW,EAAE,gCAAgC,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,iCAAiC,EAAE;IACxK,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,kCAAkC,EAAE,WAAW,EAAE,sCAAsC,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,sDAAsD,EAAE;IAC9M,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,2CAA2C,EAAE,WAAW,EAAE,gDAAgD,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,uDAAuD,EAAE;IACrO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,yCAAyC,EAAE,WAAW,EAAE,6CAA6C,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,8CAA8C,EAAE;IACtN,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,sCAAsC,EAAE,WAAW,EAAE,0CAA0C,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,qCAAqC,EAAE;IAChM,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,kCAAkC,EAAE,WAAW,EAAE,sCAAsC,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,yDAAyD,EAAE;IACtN,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,+BAA+B,EAAE,WAAW,EAAE,mCAAmC,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,iEAAiE,EAAE;IACtN,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,0CAA0C,EAAE,WAAW,EAAE,+CAA+C,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,8DAA8D,EAAE;IAChO,EAAE,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,sCAAsC,EAAE,WAAW,EAAE,0CAA0C,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,oEAAoE,EAAE;IAC5O,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,kCAAkC,EAAE,WAAW,EAAE,sCAAsC,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,mDAAmD,EAAE;CAChN,CAAC,CAAC"}

package/dist/shared/memory-types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The CLOSED memory-type taxonomy — the SINGLE SOURCE OF TRUTH for the six fixed
+ * memory `type` tokens, their human/LLM-facing descriptions, and the default.
+ *
+ * Every surface that constrains or describes a memory `type` imports from HERE and
+ * NEVER re-declares the list:
+ *   - the daemon's `POST /api/memories` zod gate (`src/daemon/runtime/memories/api.ts`)
+ *     validates the user-supplied `type` against {@link MEMORY_TYPES};
+ *   - the dashboard Add-memory form renders the {@link MEMORY_TYPES} as a `<select>`;
+ *   - the MCP `memory_store` tool publishes the enum + the LLM guidance string so an
+ *     agent classifies the memory it is about to store;
+ *   - the `honeycomb remember --type` CLI validates against the same set.
+ * A parity test (`tests/shared/memory-types-parity.test.ts`) asserts every surface
+ * draws from THIS module so the four surfaces cannot drift. Duplicating the list into
+ * another file is a drift bug and is flagged by `npm run dup` (jscpd).
+ *
+ * ── Pure by design (no zod) ──────────────────────────────────────────────────
+ * This module declares ONLY plain tuples/records — no zod import. {@link MEMORY_TYPES}
+ * is a `readonly [...]` tuple so it feeds `z.enum(MEMORY_TYPES)` under BOTH zod majors
+ * the repo uses: the app's `zod ^4` (daemon/dashboard) and the MCP server's `zod/v3`
+ * (the MCP SDK's major). Keeping the tuple zod-free is what lets one source feed both.
+ *
+ * ── Closed-set, write-time gate (back-compat) ────────────────────────────────
+ * The gate constrains USER-FACING writes (API / dashboard / CLI / MCP) only. It is a
+ * WRITE-TIME validation; it never rewrites stored rows. Existing rows whose `type` is a
+ * legacy/free-form value keep that value and still display. The autonomous capture
+ * pipeline (`fan-out.ts` → controlled-writes) enqueues its own `fact_type` directly and
+ * does NOT pass through this gate, so a model-assigned type outside the six never breaks
+ * (the column DDL keeps its `DEFAULT 'fact'`; no schema migration).
+ */
+/**
+ * The six fixed memory types — the closed set. ORDER IS LOAD-BEARING for the
+ * dashboard dropdown render; `fact` is first (the default). A `readonly` tuple so
+ * `z.enum(MEMORY_TYPES)` infers the exact union under both zod majors.
+ */
+export declare const MEMORY_TYPES: readonly ["fact", "convention", "preference", "decision", "gotcha", "reference"];
+/** One memory type token (the union of the six). */
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+/** The default applied when a user-facing write omits `type` — matches the column DDL `DEFAULT 'fact'`. */
+export declare const DEFAULT_MEMORY_TYPE: MemoryType;
+/**
+ * The one-line description of each type — how a reader OR an agent decides which to
+ * apply. The MCP tool schema + the CLI `--help` enumerate these so the LLM/user
+ * classifies correctly. Keyed by token so a lookup can never name a non-enum type.
+ */
+export declare const MEMORY_TYPE_DESCRIPTIONS: Readonly<Record<MemoryType, string>>;
+/** Narrow an arbitrary string to a {@link MemoryType} (the closed-set membership test). */
+export declare function isMemoryType(value: string): value is MemoryType;
+/**
+ * The LLM/user-facing guidance string: every token paired with WHEN to use it, on its
+ * own line. Built ONCE from {@link MEMORY_TYPES} + {@link MEMORY_TYPE_DESCRIPTIONS} so the
+ * MCP tool description and the CLI `--help` enumerate the identical set — they cannot
+ * drift from the gate. `fact` is annotated as the default.
+ */
+export declare function memoryTypeGuidance(): string;

package/dist/shared/memory-types.js

@@ -0,0 +1,75 @@
+/**
+ * The CLOSED memory-type taxonomy — the SINGLE SOURCE OF TRUTH for the six fixed
+ * memory `type` tokens, their human/LLM-facing descriptions, and the default.
+ *
+ * Every surface that constrains or describes a memory `type` imports from HERE and
+ * NEVER re-declares the list:
+ *   - the daemon's `POST /api/memories` zod gate (`src/daemon/runtime/memories/api.ts`)
+ *     validates the user-supplied `type` against {@link MEMORY_TYPES};
+ *   - the dashboard Add-memory form renders the {@link MEMORY_TYPES} as a `<select>`;
+ *   - the MCP `memory_store` tool publishes the enum + the LLM guidance string so an
+ *     agent classifies the memory it is about to store;
+ *   - the `honeycomb remember --type` CLI validates against the same set.
+ * A parity test (`tests/shared/memory-types-parity.test.ts`) asserts every surface
+ * draws from THIS module so the four surfaces cannot drift. Duplicating the list into
+ * another file is a drift bug and is flagged by `npm run dup` (jscpd).
+ *
+ * ── Pure by design (no zod) ──────────────────────────────────────────────────
+ * This module declares ONLY plain tuples/records — no zod import. {@link MEMORY_TYPES}
+ * is a `readonly [...]` tuple so it feeds `z.enum(MEMORY_TYPES)` under BOTH zod majors
+ * the repo uses: the app's `zod ^4` (daemon/dashboard) and the MCP server's `zod/v3`
+ * (the MCP SDK's major). Keeping the tuple zod-free is what lets one source feed both.
+ *
+ * ── Closed-set, write-time gate (back-compat) ────────────────────────────────
+ * The gate constrains USER-FACING writes (API / dashboard / CLI / MCP) only. It is a
+ * WRITE-TIME validation; it never rewrites stored rows. Existing rows whose `type` is a
+ * legacy/free-form value keep that value and still display. The autonomous capture
+ * pipeline (`fan-out.ts` → controlled-writes) enqueues its own `fact_type` directly and
+ * does NOT pass through this gate, so a model-assigned type outside the six never breaks
+ * (the column DDL keeps its `DEFAULT 'fact'`; no schema migration).
+ */
+/**
+ * The six fixed memory types — the closed set. ORDER IS LOAD-BEARING for the
+ * dashboard dropdown render; `fact` is first (the default). A `readonly` tuple so
+ * `z.enum(MEMORY_TYPES)` infers the exact union under both zod majors.
+ */
+export const MEMORY_TYPES = [
+    "fact",
+    "convention",
+    "preference",
+    "decision",
+    "gotcha",
+    "reference",
+];
+/** The default applied when a user-facing write omits `type` — matches the column DDL `DEFAULT 'fact'`. */
+export const DEFAULT_MEMORY_TYPE = "fact";
+/**
+ * The one-line description of each type — how a reader OR an agent decides which to
+ * apply. The MCP tool schema + the CLI `--help` enumerate these so the LLM/user
+ * classifies correctly. Keyed by token so a lookup can never name a non-enum type.
+ */
+export const MEMORY_TYPE_DESCRIPTIONS = Object.freeze({
+    fact: "A stable, verifiable truth about the system, codebase, or domain.",
+    convention: "How things are done here: idioms, standards, patterns to follow by default.",
+    preference: "The user/team's stated way of working; corrections and do/don't guidance.",
+    decision: "An architectural or design choice and its rationale; don't relitigate it.",
+    gotcha: "A non-obvious trap, failure mode, or constraint to watch out for.",
+    reference: "A pointer to an external resource (URL, dashboard, ticket, doc).",
+});
+/** Narrow an arbitrary string to a {@link MemoryType} (the closed-set membership test). */
+export function isMemoryType(value) {
+    return MEMORY_TYPES.includes(value);
+}
+/**
+ * The LLM/user-facing guidance string: every token paired with WHEN to use it, on its
+ * own line. Built ONCE from {@link MEMORY_TYPES} + {@link MEMORY_TYPE_DESCRIPTIONS} so the
+ * MCP tool description and the CLI `--help` enumerate the identical set — they cannot
+ * drift from the gate. `fact` is annotated as the default.
+ */
+export function memoryTypeGuidance() {
+    return MEMORY_TYPES.map((t) => {
+        const suffix = t === DEFAULT_MEMORY_TYPE ? " (default)" : "";
+        return `- ${t}${suffix}: ${MEMORY_TYPE_DESCRIPTIONS[t]}`;
+    }).join("\n");
+}
+//# sourceMappingURL=memory-types.js.map

package/dist/shared/memory-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-types.js","sourceRoot":"","sources":["../../src/shared/memory-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC3B,MAAM;IACN,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,QAAQ;IACR,WAAW;CACF,CAAC;AAKX,2GAA2G;AAC3G,MAAM,CAAC,MAAM,mBAAmB,GAAe,MAAM,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAyC,MAAM,CAAC,MAAM,CAAC;IAC3F,IAAI,EAAE,mEAAmE;IACzE,UAAU,EAAE,6EAA6E;IACzF,UAAU,EAAE,2EAA2E;IACvF,QAAQ,EAAE,2EAA2E;IACrF,MAAM,EAAE,mEAAmE;IAC3E,SAAS,EAAE,kEAAkE;CAC7E,CAAC,CAAC;AAEH,2FAA2F;AAC3F,MAAM,UAAU,YAAY,CAAC,KAAa;IACzC,OAAQ,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IACjC,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,CAAC,KAAK,mBAAmB,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,OAAO,KAAK,CAAC,GAAG,MAAM,KAAK,wBAAwB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/shared/service-status.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Bee-loader status STATE model + derivation — hive PRD-004b (state contract) / PRD-004c
+ * (derivation). Locked state set (PRD-004 index): `error`, `degraded`, `starting`, `warming`,
+ * `active`. This is the SINGLE shared derivation `/buzzing` (PRD-004a) and the health rail
+ * (PRD-005a) both resolve through, so a service means the same thing on both surfaces (svg-AC-4).
+ *
+ * The derivation is a PURE function of a normalized {@link ServiceSignal} plus a small amount of
+ * externally-tracked timing context (`now`, `firstActiveAt`) — never a re-derivation of doctor's
+ * own health classification, and never reaching out to doctor itself. Both the SSE-fed live path
+ * and the `GET /api/fleet-status` fail-soft path normalize into the SAME {@link ServiceSignal} shape
+ * before calling {@link deriveServiceState}, which is what makes the derivation source-agnostic
+ * (sd-AC-6): the same underlying condition yields the same state regardless of which feed reported it.
+ */
+import type { FleetHealth, FleetServiceModel, TelemetryFaultReason } from "./fleet-telemetry.js";
+import type { FleetDaemonStatus } from "./fleet-readiness.js";
+/** The five locked bee-loader states (PRD-004 index, svg-AC-6). No additional/renamed state. */
+export declare const SERVICE_STATES: readonly ["error", "degraded", "starting", "warming", "active"];
+/** One of the five locked states. */
+export type ServiceState = (typeof SERVICE_STATES)[number];
+/** True iff `value` is one of the five locked {@link ServiceState}s (svg-AC-5's fallback guard). */
+export declare function isServiceState(value: string): value is ServiceState;
+/**
+ * The minimal, source-agnostic per-service signal the derivation reads (sd-AC-6). Both the rich
+ * SSE-fed {@link FleetServiceModel} and the coarser REST `/api/fleet-status` projection normalize
+ * into this shape (see {@link fromFleetServiceModel} / {@link fromFleetDaemonStatus}) before the
+ * SAME {@link deriveServiceState} call runs, so the rule never branches on which feed produced it.
+ */
+export interface ServiceSignal {
+    readonly health: FleetHealth;
+    /** ISO-8601 of the last confirmed check-in, or `null` when the feed does not carry one (e.g. the REST projection). */
+    readonly lastSeen: string | null;
+    /** Non-null when this tick's telemetry read for this service was skipped/faulted (SSE-only signal; REST fallback never carries one). */
+    readonly telemetryFault: TelemetryFaultReason | null;
+}
+/** Normalize a live SSE {@link FleetServiceModel} into the source-agnostic {@link ServiceSignal}. */
+export declare function fromFleetServiceModel(model: FleetServiceModel): ServiceSignal;
+/** Normalize a fail-soft REST {@link FleetDaemonStatus} row into the same {@link ServiceSignal} shape. */
+export declare function fromFleetDaemonStatus(daemon: FleetDaemonStatus): ServiceSignal;
+/** How long (ms) a service stays `warming` after it is FIRST observed healthy (PRD-004 index's "very recently first-seen"). */
+export declare const DEFAULT_WARMING_GRACE_MS = 10000;
+/** How stale (ms) a reported `lastSeen` may be before the derivation overrides to `error` regardless of the reported health (sd-AC-3). */
+export declare const DEFAULT_STALE_AFTER_MS = 20000;
+/** Input to {@link deriveServiceState}. */
+export interface ServiceDerivationInput {
+    /**
+     * The service's current normalized signal, or `null` when it is a REGISTERED service that has
+     * not yet appeared in any tick / any projection row (sd-AC-2 — never omitted, never `active`).
+     */
+    readonly signal: ServiceSignal | null;
+    /** The clock reading (ms) the derivation runs at (injectable for deterministic tests). */
+    readonly now: number;
+    /**
+     * The wall-clock time (ms) this service was FIRST observed `health === "ok"`, tracked by the
+     * caller across ticks/reconnects (e.g. `use-fleet-telemetry.ts`'s per-service reducer). `null`
+     * when it has never been observed healthy. Kept OUTSIDE this pure function so the function
+     * itself stays a deterministic, unit-testable mapping (sd-AC-1) while the stateful bookkeeping
+     * lives in one place the caller owns.
+     */
+    readonly firstActiveAt: number | null;
+    /** Override the warming grace window (ms). Defaults to {@link DEFAULT_WARMING_GRACE_MS}. */
+    readonly warmingGraceMs?: number;
+    /** Override the staleness threshold (ms). Defaults to {@link DEFAULT_STALE_AFTER_MS}. */
+    readonly staleAfterMs?: number;
+}
+/**
+ * Derive exactly one of the five locked states from a service's merged registration+runtime
+ * signal (PRD-004c derivation table, sd-AC-1). Pure and source-agnostic: the SAME output for the
+ * same `(signal, now, firstActiveAt)` triple regardless of whether `signal` came from the SSE
+ * stream or the REST fallback projection (sd-AC-6/sd-AC-7). Per-service — this function never
+ * looks at any OTHER service's state, so a per-service update can never affect a sibling's derived
+ * state (sd-AC-8/sd-AC-9).
+ */
+export declare function deriveServiceState(input: ServiceDerivationInput): ServiceState;
+/**
+ * Advance the per-service "first observed healthy" bookkeeping {@link deriveServiceState}'s
+ * `warming` branch needs (PRD-004 index's "very recently first-seen"). Called once per received
+ * signal for a service: returns the SAME `firstActiveAt` when health stays non-`"ok"` or was
+ * already marked active-since some earlier time, records `now` the FIRST time health flips to
+ * `"ok"`, and resets to `null` if the service leaves `"ok"` (so a later re-activation re-enters the
+ * warming grace, honestly reflecting a fresh checked-in-and-healthy transition).
+ */
+export declare function nextFirstActiveAt(health: FleetHealth, previous: number | null, now: number): number | null;

package/dist/shared/service-status.js

@@ -0,0 +1,97 @@
+/**
+ * Bee-loader status STATE model + derivation — hive PRD-004b (state contract) / PRD-004c
+ * (derivation). Locked state set (PRD-004 index): `error`, `degraded`, `starting`, `warming`,
+ * `active`. This is the SINGLE shared derivation `/buzzing` (PRD-004a) and the health rail
+ * (PRD-005a) both resolve through, so a service means the same thing on both surfaces (svg-AC-4).
+ *
+ * The derivation is a PURE function of a normalized {@link ServiceSignal} plus a small amount of
+ * externally-tracked timing context (`now`, `firstActiveAt`) — never a re-derivation of doctor's
+ * own health classification, and never reaching out to doctor itself. Both the SSE-fed live path
+ * and the `GET /api/fleet-status` fail-soft path normalize into the SAME {@link ServiceSignal} shape
+ * before calling {@link deriveServiceState}, which is what makes the derivation source-agnostic
+ * (sd-AC-6): the same underlying condition yields the same state regardless of which feed reported it.
+ */
+/** The five locked bee-loader states (PRD-004 index, svg-AC-6). No additional/renamed state. */
+export const SERVICE_STATES = ["error", "degraded", "starting", "warming", "active"];
+/** True iff `value` is one of the five locked {@link ServiceState}s (svg-AC-5's fallback guard). */
+export function isServiceState(value) {
+    return SERVICE_STATES.includes(value);
+}
+/** Normalize a live SSE {@link FleetServiceModel} into the source-agnostic {@link ServiceSignal}. */
+export function fromFleetServiceModel(model) {
+    return { health: model.health, lastSeen: model.lastSeen, telemetryFault: model.telemetryFault };
+}
+/** Normalize a fail-soft REST {@link FleetDaemonStatus} row into the same {@link ServiceSignal} shape. */
+export function fromFleetDaemonStatus(daemon) {
+    // The coarse projection carries no `lastSeen`/`telemetryFault` — normalize to the "unknown" values
+    // so the SAME derivation function runs on either feed (sd-AC-6/sd-AC-7) rather than a parallel rule.
+    return { health: daemon.health, lastSeen: null, telemetryFault: null };
+}
+/** How long (ms) a service stays `warming` after it is FIRST observed healthy (PRD-004 index's "very recently first-seen"). */
+export const DEFAULT_WARMING_GRACE_MS = 10_000;
+/** How stale (ms) a reported `lastSeen` may be before the derivation overrides to `error` regardless of the reported health (sd-AC-3). */
+export const DEFAULT_STALE_AFTER_MS = 20_000;
+/**
+ * Derive exactly one of the five locked states from a service's merged registration+runtime
+ * signal (PRD-004c derivation table, sd-AC-1). Pure and source-agnostic: the SAME output for the
+ * same `(signal, now, firstActiveAt)` triple regardless of whether `signal` came from the SSE
+ * stream or the REST fallback projection (sd-AC-6/sd-AC-7). Per-service — this function never
+ * looks at any OTHER service's state, so a per-service update can never affect a sibling's derived
+ * state (sd-AC-8/sd-AC-9).
+ */
+export function deriveServiceState(input) {
+    const { signal, now, firstActiveAt } = input;
+    const warmingGraceMs = input.warmingGraceMs ?? DEFAULT_WARMING_GRACE_MS;
+    const staleAfterMs = input.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    // sd-AC-2: registered but no runtime signal yet (never appeared in a tick/projection row).
+    if (signal === null)
+        return "starting";
+    // sd-AC-9: an isolated per-service telemetry read fault degrades that service alone.
+    if (signal.telemetryFault !== null)
+        return "degraded";
+    // sd-AC-3: failed/unreachable, OR a stale last-seen beyond threshold even if the reported
+    // health still says otherwise (a safety net for a cached/stale snapshot).
+    if (signal.health === "unreachable")
+        return "error";
+    if (signal.lastSeen !== null) {
+        const lastSeenMs = Date.parse(signal.lastSeen);
+        if (Number.isFinite(lastSeenMs) && now - lastSeenMs > staleAfterMs)
+            return "error";
+    }
+    switch (signal.health) {
+        case "degraded":
+            // sd-AC-4: up but unhealthy/partial.
+            return "degraded";
+        case "unknown":
+            // Registered, checked in per the poll loop's Contract C convention of a not-yet-bound
+            // service reporting `"unknown"` — treated the same as sd-AC-2's never-seen case.
+            return "starting";
+        case "ok": {
+            // sd-AC-5: checked in and healthy. `warming` for a brief grace window right after the
+            // FIRST observed transition to healthy, `active` once settled.
+            if (firstActiveAt !== null && now - firstActiveAt < warmingGraceMs)
+                return "warming";
+            return "active";
+        }
+        default: {
+            // `"unreachable"` is excluded here by the early return above (TS narrows `signal.health`
+            // across that guard), so the remaining exhaustive member set is exactly ok/degraded/unknown.
+            const exhaustive = signal.health;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * Advance the per-service "first observed healthy" bookkeeping {@link deriveServiceState}'s
+ * `warming` branch needs (PRD-004 index's "very recently first-seen"). Called once per received
+ * signal for a service: returns the SAME `firstActiveAt` when health stays non-`"ok"` or was
+ * already marked active-since some earlier time, records `now` the FIRST time health flips to
+ * `"ok"`, and resets to `null` if the service leaves `"ok"` (so a later re-activation re-enters the
+ * warming grace, honestly reflecting a fresh checked-in-and-healthy transition).
+ */
+export function nextFirstActiveAt(health, previous, now) {
+    if (health !== "ok")
+        return null;
+    return previous ?? now;
+}
+//# sourceMappingURL=service-status.js.map

package/dist/shared/service-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-status.js","sourceRoot":"","sources":["../../src/shared/service-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,gGAAgG;AAChG,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAK9F,oGAAoG;AACpG,MAAM,UAAU,cAAc,CAAC,KAAa;IAC3C,OAAQ,cAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAgBD,qGAAqG;AACrG,MAAM,UAAU,qBAAqB,CAAC,KAAwB;IAC7D,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;AACjG,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,qBAAqB,CAAC,MAAyB;IAC9D,mGAAmG;IACnG,qGAAqG;IACrG,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;AACxE,CAAC;AAED,+HAA+H;AAC/H,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAE/C,0IAA0I;AAC1I,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAyB7C;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAA6B;IAC/D,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,KAAK,CAAC;IAC7C,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,IAAI,wBAAwB,CAAC;IACxE,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,IAAI,sBAAsB,CAAC;IAElE,2FAA2F;IAC3F,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,UAAU,CAAC;IAEvC,qFAAqF;IACrF,IAAI,MAAM,CAAC,cAAc,KAAK,IAAI;QAAE,OAAO,UAAU,CAAC;IAEtD,0FAA0F;IAC1F,0EAA0E;IAC1E,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa;QAAE,OAAO,OAAO,CAAC;IACpD,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC/C,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,UAAU,GAAG,YAAY;YAAE,OAAO,OAAO,CAAC;IACpF,CAAC;IAED,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACvB,KAAK,UAAU;YACd,qCAAqC;YACrC,OAAO,UAAU,CAAC;QACnB,KAAK,SAAS;YACb,sFAAsF;YACtF,iFAAiF;YACjF,OAAO,UAAU,CAAC;QACnB,KAAK,IAAI,CAAC,CAAC,CAAC;YACX,sFAAsF;YACtF,+DAA+D;YAC/D,IAAI,aAAa,KAAK,IAAI,IAAI,GAAG,GAAG,aAAa,GAAG,cAAc;gBAAE,OAAO,SAAS,CAAC;YACrF,OAAO,QAAQ,CAAC;QACjB,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACT,yFAAyF;YACzF,6FAA6F;YAC7F,MAAM,UAAU,GAAU,MAAM,CAAC,MAAM,CAAC;YACxC,OAAO,UAAU,CAAC;QACnB,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAmB,EAAE,QAAuB,EAAE,GAAW;IAC1F,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,QAAQ,IAAI,GAAG,CAAC;AACxB,CAAC"}